Tray Helper SDK

With this document there are suppiled two examples of plugins. One wtitten by author of Tray Helper in VC++ 6.0 and another one written by Andrew Cumming in DELPHI. You can use those plugins as a base for your own Tray Helper extension!

This document contains information about creating plugins for Tray Helper.
Plugins can be created in ANY language that is capable of creating DLL files (dynamic link libraries). For sure plugins can be created in Visual C++ (MFC and pure API), Delphi, Visual Basic and many other....

All you have to do it's to create a DLL library and EXPORT (it's a word used in C++, could have different name in other languages) some functions. By EXPORTING I mean enabling other applications to use those functions.

In case of any problem please email me at: irekz@yahoo.com
VC++ template project is attached to this file. You can easily create a plugin based on this template - just extend it's functionality !

Introduction
Required funtions you have to implement
Optional functions you can implement
Very optional functions - you would rather not implement
Language notes
User interface
What next ?

INTRODUCTION:

If you want to store data of your plugin in registry create it in:
HKEY_CURRENT_USER\\Software\\IrekZielinskiSoft\\TrayHelper\\PLUGINS\\YOUR_PLUGIN_FILENAME
this will assure that when user will uninstall TH your plugin will be removed also.
Also you're free to create subdirectory with any files in Plugins subdirectory of Tray Helper - this directory and all files will be removed on uninstall.

In order to test your plugin - copy it to "Plugins" subdirectory of Tray Helper - go to Plugins section , enable it
and restart application.

Not all functions have to be implemented - in fact you can implement only those functions that are necessary for you.

I'm aware that you don't have to know C++. Since all functions are described in C++ way there is short description of C++ grammar:

void - means no argument (no value returned or wanted on input of function).
int - integer value (signed digit, no floating point)
float - floating point digit (f/e: 1.55)
char* - pointer to NULL terminated string (or string in general)
POINT - it's a often used in Windows API structure with two int members x & y. Used to described position on the screen.
HWND - it's another API variable. It's a handle to a window. In such way: HWND* - means give me pointer to handle.
LPVOID - it's a long pointer to void. In C++ you can use such thing when you have to implement something for future use and you don't know. Since this parameter is used only in functions that ARE NOT used - you can skip implementing those functions.
const - in C++ means: I promise do not modify it. So if there is const char* it means - give me a pointer to a string, I promise only read it.
NULL - it's 0, nothing, pointer to nothing

LIST OF REQUIRED FUNCTIONS:

void CreatePP(POINT pt, HWND* pWnd);
This function has to CREATE MODELESS dialog box (in Tray Helper's working area).

pt - it's POINT structure used only for compability with older plugins. It contains screen coordinates of left-top corner of the new plugin (please do not use this value).

pWnd - it's pointer to Tray helper's HWND handle.
It's recommended to create your window with WS_POPUP flag clear and set WS_CHILD flag.
Then use SetParent WinAPI function to set parent of your window to window of Tray Helper.

Since this function is the most important one here is a C++ (MFC) example of it with some extra information:

//line used for code that removes WinXP theme from main daialog - see bellow
typedef HRESULT (__stdcall *PFNSETWINDOWTHEME)(HWND hwnd, LPCWSTR pszSubAppName, LPCWSTR pszSubIdList );

CDialog dlg; //global variable of dialog

void CreatePP(POINT pt, HWND* pWnd)
{
	
	ASSERT(*pWnd);

	AFX_MANAGE_STATE(AfxGetStaticModuleState());
	dlg.Create(IDD_DIALOG1); //creation of dialog
	dlg.ShowWindow(SW_SHOWNORMAL);
	
	dlg.ModifyStyle(WS_POPUP, WS_CHILD); //let's remove WS_POPUP style and add WS_CHILD

	//set parent for our window to main window of Tray Helper
	//you can skip this - but it this is not recommended - read OnMovePP, OnKillActivatePP and OnSetActivatePP functions descriptions for more info
	::SetParent(dlg.m_hWnd, *pWnd);

	dlg.SetWindowPos(NULL,0,0,0,0,SWP_NOSIZE|SWP_NOZORDER); //move our window to left top corner of window of Tray Helper (0,0)
	
	//Tray Helper has some error messages that are displayed when plugin is failed to create it's own window
	//here we get HWND to those 3 static controls and hide them !
	HWND hwndErrorControl = ::GetDlgItem(*pWnd, 1029);
	if(::IsWindow(hwndErrorControl))
	{
		::ShowWindow(hwndErrorControl, SW_HIDE);
	}
	
	hwndErrorControl = ::GetDlgItem(*pWnd, 1030);
	if(::IsWindow(hwndErrorControl))
	{
		::ShowWindow(hwndErrorControl, SW_HIDE);
	}
	
	hwndErrorControl = ::GetDlgItem(*pWnd, 1369);
	if(::IsWindow(hwndErrorControl))
	{
		::ShowWindow(hwndErrorControl, SW_HIDE);
	}

	//Under windows XP - near all dialogs of Tray Helper use Windows XP visual styles (themes)
	//But main window that contain tabs (Property Sheet) has those themes disabled (it just looks better that way).
	//Since your window is now a child of main window of Tray Helper - it will inherit a "property sheet" theme.
	//It's recommended to disable this theme. You have to do this in a way that will still works on Window 95 and 98
	//This code does the job and is fully portable (will work on old windows either).

	HINSTANCE m_hDll = ::LoadLibrary(_T("UxTheme.dll")); //Load theme DLL - it will fail on systems other than Windows XP
	if(m_hDll != NULL)
	{
		//Get address of SetWindowTheme function located in this DLL:
		PFNSETWINDOWTHEME pfnSetWindowTheme = (PFNSETWINDOWTHEME)GetProcAddress(m_hDll, "SetWindowTheme");
		if(pfnSetWindowTheme != NULL)
		{
			//Set a theme of our dialog to NULL and name to empty string "" (L - it means that this empty string is a Unicode sting)
			(*pfnSetWindowTheme)(dlg.m_hWnd,NULL,L"");
		}
		FreeLibrary(m_hDll); //Let's free library
	}
	
}

It's good idea to keep object of dialog window in global variable. It will be used in other functions.
Remember also to check every time you call a method of your dialog to check if it's not NULL
(sorry for such "for-beginners" note).
This function is called only once - just after user click for the first time on tab of your plugin. If user don't click at all - it won't be called. Also remember that usually you should start background activity of plugin (if any) BEFORE dialog of application will be created.

const char* OnGetYourNamePP(void);
Return a pointer to string with name of your plugin. It will be used to name a tab. (Please read about functions: OnGetYourName_LineInTxtFile & OnGetYourShortName_LineInTxtFile below).

LIST OF OPTIONAL BUT RECOMMENDED FUNCTIONS:

void OnSizePP(int cx, int cy);
This functions is fired when user changes the size of main window of Tray Helper. It's a good moment to reposition controls on your own dialog.

HICON OnGetYourIconPP(void);
In this function return WinAPI handle to "official" icon of your plugin. It will be placed on tab of Tray Helper.

void OnExitPP(void);
Called just before exiting application. Can be use to do some cleaning.
Please note that dialog could be destroyed before this function call (by for example destructor).

It's a good place to stop all threads, release memory etc.

void OnStartYourBackgroundActivityPP(void);
Very important function. If your plugin lunches separate threads do it now.
It's called before window creation.

void OnPauseAllBackgroundActivityPP(void);
void OnResumeAllBackgroundActivityPP(void);
If your dialog lunches timers, threads you have to pause/resume them according to those function
Remember that those functions can be called before dialog is created. Check if it isn't NULL if you're going to use it's methods or variables.
It's recommended to implement those functions - since most of users expect Tray Helper to pause/resume ALL background activity on demand.

LIST OF NOT TOO IMPORTANT FUNCTIONS:

void OnMovePP(POINT pt);
This function informs your plugin that window of Tray Helper was just moved.
If you DON'T set window of Tray Helper a parent for your window (in CreatePP function) you have to MOVE window of your plugin here to screen coordinates provided by pt parameter.

void OnKillActivatePP(void);
This function is fired when user minimizes Tray Helper or clicks on other tab.
If you DON'T set window of Tray Helper a parent for your window (in CreatePP function) you have to HIDE your window (don't kill just hide). Remember to check if your dialog exists before trying to do it.

void OnSetActivatePP(void);
Fired when user clicks on tab of your plugin or when window of Tray Helper is restoring.
If you DON'T set window of Tray Helper a parent for your window (in CreatePP function) you have to SHOW your window. Remember to check if your dialog exists before trying to do it.

int OnGetYourName_LineInTxtFile(void);
If name of your plugin is written in language file - please specify line number - enter 0 if name of this plugin is not in language file
Use this function only with prior acceptation of author. Read language notes below.

int OnGetYourShortName_LineInTxtFile(void);
If SHORT name of this plugin is in language file - please specify line number - enter 0 if SHORT name of this plugin is not in language file.
Use this function only with prior acceptation of author. Read langauage notes below.

float OnGetYour_Version(void);
Return a version of plugin (a floating point value). For example: return (float)1.7;

LPVOID DoSomething_1PP(LPVOID); LPVOID DoSomething_2PP(LPVOID); LPVOID DoSomething_3PP(LPVOID); Those functions are for future use. Leave bodies empty or don't implement at all.

LANGUAGE NOTES:

You plugin can load a langage file of Tray Helper. Path to currently used language file is stored in registry value:
HKEY_CURRENT_USER\\Software\\IrekZielinskiSoft\\TrayHelper\\szLanguagePath

You can load, read and use this file but please DON'T open it to write and don't modify it in any way.
If you want your plugin to be translated into langauges supported by Tray Helper - please contact me before.

USER INTERFACE:

As you know - Tray Helper has some common user interface elements among all plugins and main application. For example at the top of each property page there is gradient label with text (name of plugin / page). It's recommended that your application would also have such label. If you use VC++ just visit this page and download a control that is being actually used in Tray Helper (and is written by author of Tray Helper).

To make your life easier here is a code snippet that creates a font for this label: 
CFont m_fBoldFont; // member in dialog class
m_fBoldFont.CreateFont(25,0,0,0,900,0,0,0,0,0,0,ANTIALIASED_QUALITY,0,LT(878)); 
//LT(878) means line 878 from language file of Tray Helper - you can use "Arial" instead.

WHAT NEXT ?

Just create your plugin, test it and let me know about it !
If you reated just a working template project under Delphi , VBasic or any other language - let me know about also ! :-D

GOOD LUCK !
Irek Zielinski, POLAND

file revised: 14,VI,2004