Billboard is a simple today plugin that allows you to display custom information, bitmaps and menus on your today screen. Billboard is designed to operate with Mortscript, so that the complexity of coding to the today screen API in C++ can be avoided, literally you can put together your own today plugin in minutes if you can handle simple scripting.
This post is broken into 3 sections, a
simple example for beginners, an
advanced example, and a
reference section.
SIMPLE EXAMPLE
-------------------
1) Install MortScript.
2) Install Billboard.CAB.
3) Create a script that updates the registry value:
HKLM\Software\Microsoft\Today\Items\Billboard\Item1\Line1 (STRING)
For example:
RegWriteString("HKLM", "Software\Microsoft\Today\Items\Billboard\Item1", "Line1", "Custom text")
4) Go to Start Menu->Settings->Today->Items->Billboard and enable it.
That's it. Obviously, your script should loop or reschedule itself to update the
registry setting. For example, a simple script to display the battery percentage in this custom
today plugin would be:
Code:
While (1)
Battery = RegRead( "HKLM", "System\State\Battery", "Percentage" )
RegWriteString("HKLM", "Software\Microsoft\Today\Items\Billboard\Item1",\
"Line1", "Battery: " & Battery & "%" )
Sleep(60000)
EndWhile
ADVANCED EXAMPLE
----------------------
The attachment "DLLExample.zip" is a fully-functioning today plugin that should illustrate how to create your own.
1) Install MortScript.
2) Download and unzip DLLExample.zip
3) Copy the folder to your Treo, doesn't matter where.
4) Use your favorite file explorer and execute:
"DLL_Install.mscr" under the DLLExample folder.
5) On the today screen you should now have a "[MyClock disabled]" line,
tap-and-hold on that line to try the various options presented.
6) Check out the registry entries that are created by DLL_Install.mscr and the scripts in that directory to see how it works.
REFERENCE
--------------------
The following registry settings show a typical billboard-based today plugin:
HKLM\Software\Microsoft\Today\Items\Billboard\Refresh = 10
HKLM\Software\Microsoft\Today\Items\Billboard\Selectability = 0
HKLM\Software\Microsoft\Today\Items\Billboard\Item1\Bold = 1
HKLM\Software\Microsoft\Today\Items\Billboard\Item1\Fontsize = 8
HKLM\Software\Microsoft\Today\Items\Billboard\Item1\Color = 255
HKLM\Software\Microsoft\Today\Items\Billboard\Item1\bmp = "\Myscript\battery.bmp"
HKLM\Software\Microsoft\Today\Items\Billboard\Item1\Script = "\Myscript\batteryplugin.mscr"
HKLM\Software\Microsoft\Today\Items\Billboard\Item1\Exe = "\Myscript\MortScript.exe"
HKLM\Software\Microsoft\Today\Items\Billboard\Item1\Param1 = "Display battery"
HKLM\Software\Microsoft\Today\Items\Billboard\Item1\Param2 = "Display hours left"
HKLM\Software\Microsoft\Today\Items\Billboard\Item1\Line1 = "Battery: 95%"
1) REGISTRY VALUES
Refresh (DWORD)
- Interval in seconds to reread the registry settings and refresh the plugin, the default is 15.
If Refresh=0, changes to Line1 setting or bmp setting will be immediately visible on the today plugin.
This is compatible with existing carrier line functionality. Note that Refresh must be set to 0 BEFORE
the plugin is loaded to take effect.
Selectability (DWORD)
- Indicates whether to use one-handed navigation for the plugin. If Selectability=2, the popup
menu can be issued by a single-click or using the DPAD center key. If Selectability=0, a
tap-and-hold action must be used to bring up the popup menu. The default value is 2.
Bold (DWORD)
- Show text in bold, 0 = normal, 1 = bold, default is 1
Fontsize (DWORD)
- Specifies the fontsize to use, default is 8; realistically you can only
increase/decrease this a notch or two, since I haven't implemented
dynamic resizing of the plugin window.
Color (DWORD)
- Specifies the text color to use, take the RGB hex value and convert to decimal,
then write the dword. i.e., Choose an RGB hex value from here:
http://web.njit.edu/~kevin/rgb.txt.html
... and use any hex converter. Note that you color selection is probably better
left to the user because you have no idea what their theme looks like. The default
color is the "today text" color
bmp (STRING)
Specifies the fully-qualified pathname of a 16x16 transparent bitmap to use as an icon.
The transparent color value is magenta, RGB(255,0,255). For some examples,
download the Icons_BMP.zip file found here:
http://www.thevbzone.com/d_IcoCur.htm
Script (STRING)
This is the fully-qualified pathname of the script that handles the tap-and-hold action
on the plugin.
Exe (STRING)
This is the fully-qualified pathname of MortScript.exe
Param1 (STRING)
Specifies the first string in the popup/context menu that the user sees when they
tap-and-hold on your plugin. Param2..Param10 specifies the other strings.
Line1 (STRING)
Specifies the text to display in the plugin. Line2..Line5 specifies the other
display strings. If more than one text is found, the text will rotate to the next
string at the next refresh interval.
InitScript (STRING)
This is the fully-qualified pathname of the script that handles the start and
stop action of the plugin. If this is set, the specified script will be invoked
with PARAM=START or PARAM=STOP when the plugin is loaded/unloaded.
This eliminates the need for having a script in \Windows\Startup and allows
the script to properly start/stop itself in tandem with the plugin.
One final note, when creating your registry entries, make sure that the name of the DLL matches the name of the plugin in the registry:
HKLM\Software\Microsoft\Today\Items\{Plugin Name}
2) PARAM SCRIPTS
To handle tap-and-hold selections, the specified script is executed once the user chooses
a selection. The selection is passed in the MortScript variable "PARAM".
i.e. in your script)
If ( PARAM eq "LED" )
# do whatever
EndIf
If you want to completely handle the settings yourself, you can (1) omit the Script and Exe
registry settings OR (2) you can create a single Param1 such as:
HKLM\Software\Microsoft\Today\Items\Billboard\Item1\Param1 = "Settings"
and when your script is launched you can present your own UI to modify the settings.
3) MULTI-LINE SUPPORT
To display multiple lines in your plugin, set up "Item2" .. "ItemN" in the registry, and initialize "Nitems" to the number of items. For example, the following entries define a 3-line display:
HKLM\Software\Microsoft\Today\Items\Billboard\Nitems = 3 (DWORD, default value is 1)
HKLM\Software\Microsoft\Today\Items\Billboard\Item1\Line1 = "Battery: 95%"
HKLM\Software\Microsoft\Today\Items\Billboard\Item2\Line1 = "Program Memory: 28MB free"
HKLM\Software\Microsoft\Today\Items\Billboard\Item3\Line1 = "Storage: 13MB free"
Additionally you can set Bold, Fontsize, or bmp per item, but the Script, Exe and Param registry entries are only valid in Item1.
(yeah I know the terminology between Item and Line is a bit confusing, but originally the design did something else. If there is a v2.0, I'll probably have to redo the registry structure anyways).
4) PLUGIN RESIZING BASED ON FONT SIZE
You now have greater freedom to change your font size, as Billboard will automatically resize the plugin to make room for it. I have tested font sizes 7 through 25 for the default font. Note that if you use multiple lines, you should keep the font sizes the same for all items. Currently there may be formatting issues if you mix large font sizes with small font sizes.
HKLM\Software\Microsoft\Today\Items\Billboard\Item1\Line1 = "8:25 PM"
HKLM\Software\Microsoft\Today\Items\Billboard\Item1\Fontsize = 25 (DWORD, default value is 8)
HKLM\Software\Microsoft\Today\Items\Billboard\Item1\Bold = 1
5) D-PAD MENU CYCLING
This allows you to implement a next/previous feature that will automatically advance and select next menu item. This is useful if you set up different "views" of your plugin, which the user can cycle through by pressing the DPAD left or right. To enable this feature, set the following registry entry to a non-zero value.
HKLM\Software\Microsoft\Today\Items\Billboard\MenuCycle = 1 (DWORD, default value is 0)
Note that this value should reflect the active menu state at the time the plugin is loaded. For example, if the default state (view) at the time your plugin is loaded corresponds to the first menu item, you can simply leave the value as 1.
If however, you save the user's view such that the next time the plugin is loaded, the state is not equal to the first menu item, you should update the MenuCycle value to the appropriate index into the menu. For example, lets say in you menu you allow the user to choose between:
1) Battery
2) Memory
3) Storage
4) Signal
And let's say the current view is "Storage". If your plugin saves this choice and the next time your plugin is loaded you display a "Storage" view, then the MenuCycle value should be initialized to 3. Note, this value is only read at the time the plugin is loaded, from then on Billboard will maintain the menu state internally.
6) SUBMENUS
To define submenus, add registry entries of the following format:
HKLM\Software\Microsoft\Today\Items\{Plugin}\Param#,# = "Submenu string"
For example, if you wanted to define a "File" menu item, with submenu items of "Open", "Save", "Print", you would define the following:
HKLM\Software\Microsoft\Today\Items\{Plugin}\Param1 = "File"
HKLM\Software\Microsoft\Today\Items\{Plugin}\Param1,1 = "Open"
HKLM\Software\Microsoft\Today\Items\{Plugin}\Param1,2 = "Save"
HKLM\Software\Microsoft\Today\Items\{Plugin}\Param1,3 = "Print"
There is currently a limit of 10 top-level menu items and 20 items per sub-menu.
6.1) Checked items
You can create checkmarks next to a menu item to indicate the state of a particular menu item. This is indicated by prefixing a "c:" to the menu item text, as shown here.
HKLM\Software\Microsoft\Today\Items\{Plugin}\Param1 = "Bluetooth"
HKLM\Software\Microsoft\Today\Items\{Plugin}\Param1,1 = "c:On"
HKLM\Software\Microsoft\Today\Items\{Plugin}\Param1,2 = "Off"
This effect can be used in the top-level menu or the submenus. Note: it is the responsibility of the script writer to make sure the state shown in the menus is consistent with the state of their plugin.
6.2) Grayed-out items
You can temporarily disable menu items to indicate that they cannot be selected by graying them out. This is indicated by prefixing a "g:" in front of the menu text.
HKLM\Software\Microsoft\Today\Items\{Plugin}\Param3 = "g:GPS"
6.3) Separators
You can add horizontal separators to logically separate parts of the menu (this can be done with either top-level menus or submenus). This is indicated by adding a menu item with text that begins with "s:" (any text after that is ignored).
HKLM\Software\Microsoft\Today\Items\{Plugin}\Param4 = "s:"
Once the menu item is selected by the user, you script is invoked with the variables PARAM and SUBPARAM with the value chosen. If no submenu is used in the selection, SUBPARAM is set to an empty string "". Note, the value passed will include the "c:" designator if it is currently checkmarked.
The following screenshots show an mock weather plugin menu utilizing these features:
And these are the corresponding registry entries for those menus:
ITEM = "Software\Microsoft\Today\Items\MockWeather\Item1"
RegWriteString( "HKLM", ITEM, "bmp", DIR \ "sun.bmp" )
RegWriteString( "HKLM", ITEM, "Line1", "59°F Sunny 10mph NE" )
RegWriteString( "HKLM", ITEM, "Param1", "Display" )
RegWriteString( "HKLM", ITEM, "Param1,1", "c:Temperature" )
RegWriteString( "HKLM", ITEM, "Param1,2", "c:Forecast" )
RegWriteString( "HKLM", ITEM, "Param1,3", "Wind" )
RegWriteString( "HKLM", ITEM, "Param1,4", "Barometric" )
RegWriteString( "HKLM", ITEM, "Param1,5", "c:Visibility" )
RegWriteString( "HKLM", ITEM, "Param2", "Location" )
RegWriteString( "HKLM", ITEM, "Param3", "Interval" )
RegWriteString( "HKLM", ITEM, "Param4", "g:Radar" )
RegWriteString( "HKLM", ITEM, "Param5", "Settings" )
RegWriteString( "HKLM", ITEM, "Param6", "s:" )
RegWriteString( "HKLM", ITEM, "Param7", "About" )
Note: if you define submenus, it will automatically disable the menu-cycling feature. I just couldn't find a scenario where it made sense.
Attachments
Billboard.CAB (use for the simple example)
DLLExample.zip (use for the advanced example)
Billboard.zip (use to update your DLL to the latest)
Carrier wars *LOL*
Linear Mode
