Monday, February 11, 2008

How to make a theme NeoDock compatible?

Making a theme NeoDock compatible is easy. If you have read "How to make NeoDock Manager see my Plugins?", then you might have already figured it out. The Neo Dockstation is nothing but a layout switcher, using some markers on the theme XML file to figure out what to replace for what. So, you just need to set those markers on your theme layout file.

Any theme file for the Neo interface has two plugin entries - one for the top status bar and the other for the Neo plugin. The markers are placed for the top status bar plugin - the first <plugin... entry in the XML file.

1) Place the following line before the start of the plugin tag.

<!-- NeoDock Markup START - DONOT CHANGE THIS LINE!! -->

2) Place the following line after the end of the plugin tag, i.e. after </plugin>

<!-- NeoDock Markup END - DONOT CHANGE THIS LINE!! -->

Since these lines are marker, you must place them in separate lines, with no spaces or tabs before or after them.

With that, the switcher can now work with your theme. Do take a look at the NeoDock.home.xml file in \Application Data\Home for a complete example.

Sunday, February 10, 2008

How to make NeoDock Manager see my Plugins?

The NeoDock Manager is an application to build the Neo Dockstation. It detects installed plugins and shows them up on the interface so that you can add it to the dockstation. This tutorial shows how you can make your other plugins show up on NeoDock Manager. To do this, you shall need 2 XML files, 1 DLL file and some cosmetics!!

Let me start with how the Neo Dockstation works. There is nothing too tricky in it. The dockstation starts with the current theme XML file. Using two marker lines, it knows which plugin tag corresponds to the top portion of the Neo interface. The rest is simple. It creates a new layout file with the plugin tag from the current theme removed and inserts the plugin tag for the plugin to be loaded. After that it just loads this new layout!! Sometimes the most trivial is not the easiest to find - I went through the whole process of writing a plugin that loads other plugins before stumbling upon this method.

So, back to NeoDock Manager. Lets say you want the default status bar plugin to be visible in NeoDock Manager.

1) Create a folder in \Program Files\NeoDock\Plugins. You can name it anything. Say we call it "Shadow Status Bar".

2) Inside the folder, you shall have to create two XML files - one must be named setup.xml, the other one your choice, say we name it monobar.xml.

3) The setup.xml is what the NeoDock Manager will parse to find information about a plugin. Here is how it looks for the Shadow iconbar:

<?xml version="1.0" encoding="UTF-8" ?>

<neodock>


<plugin name="Shadow Iconbar" dllsource="\Windows\tpcutil.dll" clsid="
{837FC251-FE69-43ad-84E0-EBCEDEBA0884}" xmlsource="\Program Files\NeoDock\Plugins\Shadow Status Bar\monobar.xml">

<config exe="" />

<icon source="\Program Files\NeoDock\Plugins\Shadow Status Bar\iconbar.png" />

<title text="Status Bar" />

<description text="Default Icon Notifications" />

</plugin>

</neodock>

Lets take a look at these tags one by one.

neodock: This tag is a must to indicate that you are writing a setup for a NeoDock plugin.

plugin: This tag and all of its attributes is a must.


name = name that NeoDock Manager should display in its interface for this plugin.

dllsource = full path to the dll for this plugin.

clsid = GUID of this plugin.

xmlsource = full path to the xml file for this plugin. I shall explain what this file contains in a while.


The following four entries are optional.

config: exe = full path to the executable that can be used to configure this plugin.

icon:
source = full path to the image to display for this plugin in the dockstation.

title: text = a title for this plugin; used in the dockstation.

description: text = a description for the plugin; used in the dockstation.

4) Now lets create the other XML file - monobar.xml. This file contains the plugin tag that usually goes into the theme layout XML file. For the shadow status bar its something like this -

<plugin clsid="{837FC251-FE69-43ad-84E0-EBCEDEBA0884}" name="iconbar" height="20">

<iconbar fgcolor="COLOR_TRAYTEXT"/>


<background bgimage="\windows\CHome_framework_status_bar_bg.png" halign="center" bgcolor="COLOR_TRAYGRADLEFT" b-border-color="COLOR_WINDOWFRAME"/>


</plugin>
5) That's about it. The next time you run NeoDock Manager, it will scan through all folders in \Program Files\NeoDock\Plugins and will parse the setup.xml files in those folders. If everything is valid and relevant files do exist, the plugin would show up on the Manager. Thereafter you can add it to the dockstation.

Validity checks are made for the attributes in the plugin tag, meaning, the dll and xml files must be present at the location specified and the CLSID should match with the one given in the second xml file (monobar.xml in this example) . Other tags have some default values if not present.

The Manager attempts to create the required GUID entry in the registry for the dll. However, if an entry already exists with the given GUID, it shall not overwrite it. This is because, you might have made a mistake in specifying the right GUID for the plugin dll, in which case, overwriting the entry with the wrong information may crash some other program.

Feel free to leave me a comment if you have a problem! And also, please let me know if you find cool non-selectable plugins perfect for the Neo Dockstation.

Configuring the Weather Dock

The Weather Dock is a plugin for WM6 Standard reading weather information from Yahoo! Weather feed. The plugin displays
  • Temperature and text description for current weather at a location provided as a US Zip Code or a Yahoo! Location ID.
  • Feels like temperature and wind speed.
  • Lows and highs forecast for today and tomorrow.
  • Customizable units, update frequency and font colors.
  • Customizable background.
Here are the steps to configure the plugin.

1) The configure program is installed at \Program Files\NeoDock\Plugins\Weather Dock and is called WeatherConfig.exe. Alternatively, you can just click on the Configure button on the Neo Dockstation.


2) Different items on the interface are as follows:

ID: The ID can be a US Zip Code or a Yahoo! Location ID. The Yahoo! Location ID can be retrieved from http://weather.yahoo.com. After you enter your location and the weather page is loaded, check the URL of the page. The Yahoo! Location ID is the name of the html page. For e.g., if the URL is http://weather.yahoo.com/forecast/XYZ.html, then the Yahoo! Location ID is XYZ.

Unit: English shows temperature in Fahrenheit and speed in MPH. Metric shows it in Celcius and KmPH respectively.

Update every: The frequency between updates. Weather data is updated from the server at this frequency.

Color codes: Color codes means the color of the font on the plugin. "Fresh" indicates the color to use when displaying data that has been successfully updated the last time an update was tried. If an update fails, the "Stale" color is used. Use HTML coding to specify the color - #RRGGBB.

3) Once you have entered all the information, press Save. Give the program some time to contact the server and resolve the ID.



4) Press OK. Once done, exit out. If you are using the plugin on the Neo Dockstation, reload the plugin.

When the Weather Dock is first loaded, it tries to update the current weather. The Weather Dock then updates weather information at "Update every" intervals. If an update fails, the Weather Dock keeps trying every minute until it is able to do so. Once updated, it goes back to the "Update every" frequency.

NOTE: I have noticed that the icon for the current weather is not changing since tomorrow. Even during the night, it shows the sun!!! I thought the plugin has malfunctioned. However that was not the case as it seems. The problem was rather with the RSS feed I was getting from Yahoo! Weather. If you find errors in the images displayed, please perform the following check first: open the URL http://weather.yahoo.com/forecastrss?p=ID , where ID is your Location ID, and see the output of the page in a browser. For me, even this page has been displaying the same icon for a few days. It seems the condition code is not being updated in the server for some reason.

Saturday, February 9, 2008

Neo Dockstation

After successfully implementing the Iconbar plugin, I wanted to do more. Unfortunately, the way the Neo interface is designed, it does not leave much room to hook more than one plugin. The only way that remains is to go and edit the files and load different plugins in place of the top status bar...not a practical way!! So, here it is - the Neo Dockstation!!


The Neo Dockstation is an assimilation of different aspects of the Neo interface (plugins, dynamic layouts and interface build up...) that finally enables one to load different plugins at the click of a button. It sits on the Neo interface like any other tab and shows the different plugins that can be loaded in the top 27 pixels of the home screen. I call it the "dockstation" because it lets you dock different plugins at the top. I won't pull it long and get to the details.

As the Neo interface uses both up and down key strokes to explore the different tabs, non-selectable plugins are most useful on the dock. That does not mean selectable plugins are not loadable, but its just that pressing the up key on the D-pad will not take you to the tab above, but to the plugin. The down key is what you will only have at your disposal to move between tabs...tiresome if you are at say the second tab and want to go to the first one!!! Feel free to try it though!

Currently, I have three custom made plugins bundled with the dockstation -
  • The Colored Iconbar - Most of you already know about this. Read this if you don't!
  • A Windows Media Player "Now Playing" status bar
    • displays current track information (Song Title, Album Title, Original Artist), total and elapsed time, and a graphical elapsed status bar.
  • A Weather dock powered by Yahoo! Weather
    • displays temperature, feels like and wind speed for a US Zip Code or Yahoo! Location ID, today and tomorrow forecast with lows and highs, customizable update frequency, color codes and units.
The bundle also includes the required files to incorporate the Shadow default status bar.

Please note the dockstation is made specifically for the Neo interface. If you are using a theme other than Neo, then it would not make much sense to install it. Here's how to get started:

1) Download this zip file - Rinku Neo Dockstation. Inside is a cab installer. Copy it over to your phone and open it. Install to the "Device". Reboot upon completion. No, you will not see any changes as yet!!!

2) Once the device restarts, goto Start>Settings>Home Screen and change over to the NeoDock theme. To begin with, this theme is same as the T-Mobile Default theme, but has some markers inside to make it compatible with the dockstation. Many of you are perhaps using Freddy's themes. Right now they are not compatible with the dockstation. You can start using them as soon as he makes them available. You do not have to go through this setup process again!!

3) The bundle installs the NeoDock Manager and the aforementioned plugins on the system. The NeoDock Manager is the utility that lets you build the Neo Dockstation. So, lets do that next. From the Start menu, open NeoDock Manager.



4) The Manager will search for available plugins (more on this later), and give you the options to add them to the dockstation. Play with it...its a simple utility! Once done adding the plugins, hit Options>Build NeoDock. The Manager will ask what position do you want the dockstation to be placed in on the homescreen. Once done, and everything goes well, the Neo Dockstation will be created. Exit the program to load it on the homescreen. Do not panic if your screen turns white for a second or so!!


5) You should now see the plugins you just added on a tab on the home screen - Neo Dockstation tab. To load one at the top, hit the center button. If there is a configuration utility available for a particular plugin (for e.g. the Weather Dock), then you can access it from the right softkey.

You can now switch back and forth the plugins at any time!!!!

That is it!! Well, it is as far as what I am offering in the bundle. Read "Configuring the Weather Dock" if you have questions on how to configure the weather plugin. As for those who want to add more plugins to the dockstation, read "How to make NeoDock Manager see my Plugins?". To make your custom themes (Neo only) NeoDock compatible, see "How to make a theme NeoDock compatible?".

WMP PLUGIN: The Windows Media Player plugin requires frequent redrawing of the homescreen. This can make the response on the home screen somewhat slower than usual when the plugin is in use (a song is playing). The color of the text is specified in the fontcolor attribute in \Program Files\NeoDock\Plugins\WMP\wmpplugin.xml. The format is 0xBBGGRR - a little different than usual, but helps avoid an extra processing in the plugin. The color is current set to 0xFFFFFF - white.

COLORED ICONBAR: The dockstation bundle includes all files required for the colored iconbar. You can remove earlier installs by deleting all files beginning with CHome_Iconbar_ and the iconbarplugin.dll file in \Windows. If you have made changes to the icons then copy the CHome_Iconbar_*.png files over to \Program Files\NeoDock\Plugins\Rinku Iconbar\Icons before deleting. Do not copy the dll.

PLUGIN BACKGROUND: The background for the plugins bundled with the dockstation is customizable in the xml files. Each plugin has a folder of its own in \Program Files\NeoDock\Plugins. You can see two .xml files in there - one of them is always named setup.xml. The other filename varies. You can edit this other file to specify a background for the corresponding plugin. Just change bgimage to the full path of the image you want to use as the background for the plugin. Currently, all plugins included use \windows\CHome_framework_status_bar_bg.png as the background.

I am very excited with this work since it opens up all the avenues to develop more and more custom plugins for Neo. But as always, this is no professional quality code. So, errors might come up. Please do let me know if you happen to come across a weird situation while using the bundle. It would help me polish things better. Until then, Happy Docking!