SnoopSoft Inc.

SnoopSoft Dashboard Manual - Module Specifications Page

SnoopSoft Dashboard is a skinnable Today Page plug-in for your PocketPC. If you would like more information on our SnoopSoft Dashboard product, please check out our SnoopSoft Dashboard Product Page.

This page will help you get started developing plugin modules for the MyDash view on the product. With the instructions on this page and the sample MyDash Quote module provided, you should be creating your own skins in no time at all!

Also, be sure to read the comments inside the module source code files. Each file is very thoroughly commented and most of the information on this page is taked directly from the source file comments.

Let's get Started...

The reason I chose to require SnoopSoft Dashboard modules to be coded to another API set rather than just use the existing Today plugin API is mainly because of the transparency that is required for the skins. The other reason is that it will take more work to get the scrolling to work like it does with the Today API, so for starters, I decided to require DLL's be coded to the MyDash module specification listed out below.

Naming Conventions

Initially, SnoopSoft Dashboard required that all MyDash modules be named "MyDash_*.DLL" where you plug in whatever you want for the * in the name above. For instance, the Quote module is "MyDash_Quote.DLL". This makes it easy for the program to load in the appropriate DLL's. At startup, it will look for all DLL's in the \Windows\ folder that match the search string of: "\Windows\MyDash_*.dll". SnoopSoft Dashboard loads these up, calls into the GetInfo() function to retrive a module name for display in the Options dialog.

Now, modules can be placed on any view within SnoopSoft Dashboard and the naming requirements have been expanded to allow modules to be named "Dashboard_*.DLL" where you plug in whatever you want for the * in the name. SnoopSoft Dashboard will look for all Dashboard_*.DLL modules and when loading the MyDash modules, the program will also look for any MyDash_*.DLL modules for backward compatibility. The modules can now specify what view they will end up in by handling the new MyDashSendMessage function (see details below).

One and only one Module can be active in the any view at any given time. The user can change modules through the Options dialog or directly from the main SnoopSoft Dashboard screen by tapping on the current View's toolbar icon a second time.

The SnoopSoft Dashboard Module API

There are not many functions for modules, here's a quick glance of the functions required to make a SnoopSoft Dashboard module work. I've tried to make this as extensible as possible so that in the future, users can plugin these modules over any view, but for now they can only be used for the MyDash view.

bool MyDashInitializeItem(HINSTANCE hInstDLL, RECT rMyDashArea, SMyDashSkin* pMyDashSkin);
void MyDashUninitializeItem(void);

void MyDashGetInfo(SMyDashInfo* pMyDashInfo);
bool MyDashOptionsDlg(HINSTANCE hInstDLL, HWND hWnd);
bool MyDashGetToolbarImages(SMyDashImages* pMyDashImages);

void MyDashOnPaintToolbar(SMyDashPaint* pMyDashPaint);
void MyDashOnPaintPageIcons(SMyDashPaint* pMyDashPaint);
void MyDashOnPaint(SMyDashPaint* pMyDashPaint);
bool MyDashOnTap(HWND hWnd, POINT& ptTap, bool& bRefreshDisplay);
LRESULT MyDashSendMessage(SMyDashPaint* pMyDashPaint, UINT uMessage, WPARAM wParam, LPARAM lParam);

void MyDashOnTimer(HWND hWnd, bool& bRefreshDisplay, SMyDashSkin* pMyDashSkin);

SnoopSoft Dashboard will load the DLL and go after these functions by ordinal number rather than name, so make sure that you properly define them to the DLL. If you use the sample as a template then you should have no problems since it contains the following .DEF file.

EXPORTS

MyDashInitializeItem @ 200 NONAME
MyDashUninitializeItem @ 201 NONAME

MyDashGetInfo @ 202 NONAME
MyDashOptionsDlg @ 203 NONAME
MyDashGetToolbarImages @ 204 NONAME

MyDashOnPaintToolbar @ 205 NONAME
MyDashOnPaintPageIcons @ 206 NONAME
MyDashOnPaint @ 207 NONAME
MyDashOnTap @ 208 NONAME
MyDashOnTimer @ 209 NONAME
MyDashSendMessage @ 210 NONAME

I've tried to keep the number of functions to an absolute minimum, but there may be more functions than you initially might have been expecting due to the inherent flexibility of the program. Before you complain too loudly :) - I've provided a fully-functional MyDash module complete with source code that has all of these functions coded and working for you to take and use as a template!

There are quite a few changes and enhancements over the initial spec - although, I've tried hard to maintain as much backward compatibility as possible. I've also enhanced the Quote module to demonstrate much of this new functionality.

Some of the biggest differences are:

Modules can now appear on *any* SnoopSoft Dashboard view
Removed built-in spacing around main rect - module must now pad as appropriate
Tap and Hold support
Drag support
Enter/Leave notification
Actual icon rects are now predefined - do not use the old methodology anymore
Timer has finer resolution (2.5 secs.) - do not call long-running functions in Timer code
New SendMessage function for future expandability

Here's a quick rundown of all the functions that need to be coded.

MyDashInitializeItem()

Module Initialization function.
Called by SnoopSoft Dashboard when user selects this item as the current Module for a view. Your module must perform any module specific initialization here. You have the opportunity to override the default skin image file and colors here and in the OnTimer function.

MyDashUninitializeItem()

Module Uninitialization function.
Called by the program when user selects another item (or None) as the current Module for a view. Your Module must perform all module specific cleanup here (i.e. Free memory allocated, close connections, etc...)

MyDashGetInfo()

Returns structure with information for display within Options dialog.
Called by the program when user selects a module in the Options dialog listbox. Fill in the structure with all pertinent information to display to the user.

MyDashOptionsDlg()

Display the Options dialog for the Module
I thought that it would be easier if each module took control of its own Options dialog instead of having SnoopSoft Dashboard invoke the dialog directly as the Today API does. This way, the program doesn't need to know anything about your resources - you handle it all yourself.

Note:
This section of your code must be callable outside the normal Init/Uninit processes. In other words, SnoopSoft Dashboard could invoke this function from the Options dialog which means that your module would not be initialized. You must insure that this section of code reads and sets all pertinent registry settings and does not depend on any other section of your module being active for functionality.

MyDashGetToolbarImages()

Specify Main Toolbar image to use for the Module.
Called by the program when its about to draw the main view toolbar image.
I'm changing the way this works and will allow Skin designers to code in extra icons and this function will allow the module designer the flexibility of choosing a different icon (if it exists) for use.

MyDashOnPaintToolbar()

View-Specific Toolbar (Font Size / Refresh / Run) paint function.
Called by the program when its time to repaint the view-specific Toolbar.
Your module can paint anything here that it wants, but is limited in size by the rect of the toolbar as specified in the currently selected skin file. SnoopSoft Dashboard will pass in the HIMAGELIST handle for the Toolbar icons and the module can use that or ignore it.

Note:
Your Module must set the m_eFontSize member if it is different than what the Module thinks that it should be since the program tracks this setting in the Registry and creates the Fonts that will be used for drawing.

MyDashOnPaintPageIcons()

SnoopSoft Dashboard Page Icons (Prev Pg. / Pg. Number / Next Pg.) paint function.
Called by the program when its time to repaint the Page Icons.
Your Module can paint anything here that it wants, but is limited in size by the rect of the toolbar as specified in the currently selected skin file. SnoopSoft Dashboard will pass in the HIMAGELIST handle for the Page icons and the module can use that or ignore it. If you do not use the page icons you gain 3 new icon positions for whatever you want.

Paging vs. Scrolling:

There is no real reason that you must use a Page metaphor as SnoopSoft Dashboard does. For us, this was by design, but for your module, you can implement some form of scrolling mechanism. In the future, we will use a scrolling mechanism for certain views and to do so, I plan to use the predefined Up/Down arrows in the POOM Icons (i.e. POOMICON_DOWNARROW). If you implement true scrolling, please be considerate of left-handed users and allow the scrolling mechanism to be positioned on either side of the display. Also, this is not the place where the scrolling stuff should be drawn - that should be handled in the OnPaint function since you don't yet have access to the main rect.

Note 1:
At this point the drawing area is already setup and the background wallpaper has been painted.

Note 2:
SnoopSoft Dashboard only contains page numbers up to 9 although that doesn't preclude you from going higher (since a zero is provided). The program was always designed as a simple, easy, quick way to get to information and therefore page numbers higher than 9 are not made available to the user - this is by design. Plugins don't have to follow this rule, but you must insure that there is enough room to list out more page numbers (i.e. 2 digit numbers).

MyDashOnPaint()

Module paint function.
Called by the program when its time to repaint the main display area.
Your Module can paint anything here that it wants, but is limited in size by the rect of the area as specified in the currently selected skin file. In the past, Skin files have had some padding around this rect, but in an effort to give Module designers greater flexibility I'm going to have the Skin designers (and helper software) do away with that notion. What this means to you though is that if you're displaying some form of textual information, you should give yourself a little cushion around the perimeter. See the Quotes sample for an example of this.

Note 1:
At this point the drawing area is already setup and the background wallpaper has been painted.

Note 2:
ASSUME NOTHING!! As you read this, SnoopSoft Dashboard is being ported to other devices, other resolutions, other things!! Do not assume that this rectangle is anything but what it is defined to be. Your Module *MUST* conform to the rect, not the rect to the module, or your stuff will look "different" than everyone else's.

MyDashOnTap()

Module Tap event notification function.
Called by the program when a Tap notification is detected on the MyDash view, but is outside the Options area and the View selection toolbar.

Note 1:
Your Module should hang onto the Toolbar RECTs passed into the OnPaint functions and use those to determine where a tap event has been detected.

MyDashOnTimer()

MyDash Timer event notification function. You have the opportunity to override the default skin image file and colors here and in the InitializeItem function.

This function is called by the program when the internal Timer message is posted. I've currently coded this to post a timer event to your Module every second (2.5 seconds) whether or not your module is on display. Therefore, do not do any Painting from this function as you may not be in focus on SnoopSoft Dashboard. If for some reason your data is dirty, set the RefreshDisplay boolean to 'true' and if your module is active, we will send a Paint message through.

Perform whatever refresh actions are necessary for your module. For SnoopSoft Dashboard, it waits until 5 minutes have passed before refreshing the data on the screen.

MyDashSendMessage()

Generic event notification function.
Called by the program when a message other than the currently defined functions needs to be executed. This was added after the initial release of the MyDash specifications which is why all messages do not move through this function. For the sake of backwards compatibility, it was easier to just leave things as they were, but build in the expandability for the future.

Listed below are the current set of defined messages and their descriptions:

DM_QUERY_VIEW_SUPPORT

This message is sent to your Module before ever loading/initializing it to determine which View to place your Module into. Return as the LRESULT the appropriate view(s) - can be OR'd (|) together to appear in more than one.

DM_KEYDOWN

This message is sent when a KeyDown event is captured. The wParam and lParam parameters are the same ones sent to the program for the event.

DM_TAP_N_HOLD

This message is sent when a Tap and Hold event is captured. SnoopSoft Dashboard manually determines when a Tap and Hold event is triggered and that's why your module will never see a LBUTTONDOWN message. The wParam is the POINT where tap and hold event occurred and the lParam is always 0.

DM_LBUTTONUP

This message is sent when a LButtonUp event is captured. The wParam and lParam parameters are the same ones sent to the program for the event.

DM_MOUSEMOVE

This message is sent when a MouseMove event is captured. The wParam and lParam parameters are the same ones sent to the program for the event.

DM_ENTERVIEW

This message will be sent as SnoopSoft Dashboard changes views to your Module. This is different than the Initialize function in that it is not loading your Module, just switching back to it from another view. There should be no need to do anything special in this function unless you are doing something on-screen and need to know when your Module becomes active.

DM_LEAVEVIEW

This message will be sent as SnoopSoft Dashboard changes views away from your Module. This is different than the Uninitialize function in that it is not unloading your Module, just switching away from it to another view. There should be no need to do anything special in this function unless you are doing something on-screen and need to know when your Module is no longer visible.

Profile • Dashboard • Skins • Other Products • Links • Contact
Main • MyDash • Manual • FAQ • Buy