_______________________________________________________________________________

 Systray/WPS plugin reference (revision 1)                             English
_______________________________________________________________________________

Systray/WPS plugin reference

1. Introduction

Well, if you are reading this document, you want to know the mechanism for
Systray/WPS plugins work, we are very gratitude for it. Very first we want
to take your attention to make a notice on plugin format, that significantly
differs comparing to Systray/2 (we hope to the best). However we guess it's
worth for you to accustom yourself with Systray/2 plugins reference to understand
basic principles of its' work.

2. Plugin Attachment
It differs from previous versions, that Systray/WPS automatically attaches all
available plugins. All you need is place plugin DLL into dedicated directory
and on next restart Systray/WPS will use it. Plugins are placed it \PLUGINS
directory that resides in the directory with Systray/WPS installed in (that
one contains WPST.DLL -- a DLL with Systray/WPS code). On WPS startup WPSystray
class will be initialized and during this phase will call DosLoadModule for every
plugin in directory. When Systray/WPS is started via double click on its icon
exported function RegisterPlugin contained in plugin DLL will be called to take
steps to register itself within Systray.

3. Plugin registration.
As was mentioned above, RegisterPlugin function is used to register plugin.
Syntax:

BOOL EXPENTRY RegisterPlugin(HMODULE hmPlugin, // referrer to plugin loaded module
                             HAB habSystray,   // thread's anchor that runs Systray
                             PWCLASS pwc,      // pointer to unit classes structure
                                               // defenition
                             PUSHORT nClasses  // the number of exported classes
                             );
On this call Sytray will pass all data to plugin required for registration of plugin and 
encapsulated classes, contained in it. On this stage plugin must fill key fields of WCLASS
structure, its referrer is passed as a third parameter of RegisterPlugin function, and place
the number of exported classes into nClasses variable to pass its referrer as fourth parameter.

4. Plugin Deregistration
Starting with this version (Systray/WPS) we added registering counterpart that allows
deregister plugin and free resources occupied by plugin. 
Syntax:

BOOL EXPENTRY DeregisterPlugin(HMODULE hmPlugin, // referrer to plugin loaded module
                               HAB habSystray    // thread's anchor that runs Systray
                               );

5. Filling PWCLASS structure
You must fill fields that required for registration.
Syntax:

typedef struct _WCLASS {
PSZ 	pszName;	// referrer to unit's window class
PSZ     pszViewName;	// referrer to unit's class header
PSZ     pszHelpFileName;// referrer to the name (w/o path) of help file
ULONG   ulHelpPanelID;	// the number of topic in help file for current unit

USHORT  usMaxUnits;	// units limit (0=no limit)
USHORT  usFlags;	// flags (see below)

USHORT  usAlignWord;	// reserved
ULONG   ulReserved;	// [...]

ULONG   ulFix;		// copy of cbFix filed from UNIT structure (see below)
ULONG   ulSafeAlloc;	// the full size of UNIT structure (see below)
} WCLASS, *PWCLASS;

Next flags are defined and effective for each class:

#define STUF_FIXED	0x0001 // Unit has fixed width, that can not be changed by user
			       // Unit itself is allowed to change width.

#define STUF_STATIC	0x0002 // Draw optional frame around the units of this class.

#define STUF_MANUAL	0x0004 // Unit has user-adjustable width.
			       // May not be used with STUF_FIXED and STUF_FULLWIDTH

#define STUF_FRAMED	0x0008 // Always draw frame around the unit of this class.

#define STUF_FULLWIDTH	0x0010 // Unit of this class will occupy width equal to free space of Systray.
			       // May not be used with STUF_MANUAL and STUF_FIXED.

#define STUF_NOHINT	0x0020 // Don't show hints for units of this class.

You MUST use one of the following flags: STUF_FIXED, STUF_MANUAL, STUF_FULLWITH.

Example of usage:
   pwc->pszName = "MYPLG_MyClass";
   pwc->pszViewName = "My own unit class";
   pwc->pszHelpFileName = "MYPLG.HLP";
   pwc->ulHelpPanelID = IDH_MYUNITCLASSHELP;
   pwc->usMaxUnits = 1;
   pwc->usFlags = STUF_STATIC | STUF_NOHINT | STUF_MANUAL;
   pwc->ulFix = sizeof(UNITMYCLASS);
   pwc->ulSafeAlloc = sizeof(UNITMYCLASS) + sizeof(MYCLASSPRIVATE);

6. Registering class in OS/2 Presentation Manager.
For the purpose Sytray could use class, that was checked in by plugin into PWCLASS
structure, in future it's necessary to register Unit's window class in PM.
Syntax:

 WinRegisterClass(habSystray,		// Same as in RegisterPlugin
                  pwc->pszName,		// filled above
                  (PFNWP)TaskBarWndProc,// window handle procedure
                  CS_SIZEREDRAW,	// REQUIRED parameter
                  sizeof(PVOID));	// necessary to reserve 4 bytes for Systray needs

7. Units and messages
As was mentioned above Unit itself is a small window and its parent is Systray main
window. Typical window hierarchy in this case looks like:

 HWND_DESKTOP
  |\
  | Desktop
    ... WPS windows...
  |
   \Systray
     |
     |\
     | Unit 1 (SPLG_ToolBar)
     |\
     | Unit 2 (SPGL_SysTray)
       ...

Systray main window and Units' windows interact by means of Messages, described below.

7.0 WM_CREATE
This message is important, as with it Unit receives the referrer to UNIT structure
(that, in fact, defines the contents of class unit) even before Systray set referrer
to it in the null double word of window data (remember about the number of reserved
bytes in registering procedure of Unit window class). The exact contents of this
structure is defined by class of Unit itself, but in all cases this structure has a
common base that could be extended.

typedef struct _UNIT {
ULONG   cbFix;			// Full size of structure
				// (greater of equal to ulFix field of 
				// WCLASS structure)

HWND    hwnd;           	// Unit's window (ONLY valid after WM_CREATE)

HWND    hwnd_Menu;      	// Window of pop-up menu

CHAR    szClass[CBMAXSTRING];	// Unit's Window class name

USHORT  usFlags;        	// Flags, are copied from corresponding field of
				// WCLASS structure

INT     iWidth, iRow;		// Internally used by Systray

BOOL    fGrpNext;		// ...
BOOL    fJustCreated;		// ...

ULONG   ulRefresh;		// Refresh interval, 0 means NO REFRESH
				// see message USTM_REFRESH
ULONG	ulCounter;		// Refresh counter

PVOID   pViewData;		// referrer to data of Systray Main Window

PFNWP   pfnSubclUnitProc;	// Window subclass procedure

PFNWP   pfnOldUnitProc;		// Original Window procedure

ULONG   ulReserved[8];		// Future use reserved
} UNIT, *PUNIT;

7.1 USTM_REFRESHTIMER
Message is sent after expiration of time chunk in Systray-emulated timer.

7.2 USTM_QUERYNBINFO
Used to demand information about current Unit configuration notebook.
mp1 contains referrer to UNTNBINFO structure:

typedef struct _UNITNBINFO
{
PUNIT		pUnit;		// referrer to UNIT structure of currently used Unit.
				// Filled by Unit itself.

PVOID		pUserData;	// User-defined data

PFNTCLRINFO	pfcInfo;	// referrer to structure with 
				// Unit representation parameters

				// See structure definition in header file (systray.h)
				// and source code

PSZ		*ppszfcInfo;	// Headers of presentation parameters.
				// Showed on 'Presentation' page of 
				// Unit's configuration notebook

SHORT		sNumfcInfo;	// The number of presentation parameters

PUNITPGINFO	pupgInfo;	// Refferer to notebook page structure information

				// See definition in header file (systray.h)
				// and source code

ULONG		idTurnTo;	// The ID of current page in configuration notebook

HPOINTER	hptrWindowIcon; // The icon of configuration notebook window

} UNITNBINFO, *PUNITNBINFO;

The pupgInfo field contains referrer to first page of configuration notebook:

typedef struct _UNITPGINFO
{
PSZ	pszTabText;		// Bookmark text
PSZ	pszStatusText;		// Status text 
HMODULE res;			// Descriptor of dialog module
ULONG	id;			// ID of dialog resource
MPARAM  mp2InsertFlags;		// BKM_INSERTPAGE flags
PFNWP	pfnDlgProc;		// Dialog handle procedure
PVOID	pCreateParams;		// Window creation parameters (WinLoadDlg)
HWND	hwnd;			// reserved, should be set to NULLHANDLE value
ULONG   ulNBPageID,		// reserved, should be set to 0L value
	ulPageFlags;		// Flags of current dialog (page) in
				// configuration notebook

#define	NPF_UNDO		0x00000001 // "Undo" button
#define	NPF_DEFAULT		0x00000002 // "Default" button
#define	NPF_HELP		0x00000004 // "Help" button (without sending)
#define	NPF_BYPASSHELP		0x00000008 // Send "Help" to dialog, but do not
					   // handle by itself

#define	NPF_ALL			0x0000000F // All

struct _UNITPGINFO * pupgInfoNext;
} UNITPGINFO, *PUNITPGINFO;

As IDs of buttons are:

#define IDD_DEFAULT	31001
#define IDD_UNDO	31002
#define IDD_HELP	31003

you should not these values in current dialog.

pfcInfo field keeps the referrer to one or more FNTCLRINFO structure(s),
containing separate parameters of representation (may exist the number
of, see POP3 example, for different states):

typedef struct _FNTCLRINFO
{
LONG	lTextColor;		// Text color, RGB
LONG	lBackColor;		// Background color, RGB
CHAR	szFont[56];		// Font, use "Size.FaceName" format
} FNTCLRINFO, *PFNTCLRINFO;

7.3 USTM_QUERYHINT
Used to demand the text of pop-up hint (if STUF_NOHINT is not specified in
class flags). mp1 contains referrer, mp2 contains the maximum text length.

7.4 USTM_QUERYWIDTH
Used to demand Unit's width in pixels. Units should return its current width.
May be sent to any types of Units.

7.6 USTM_GROUPED
Reserved, currently not used 

7.7 USTM_MOVED
Reserved, currently not used 

7.8 USTM_REMOVED
Message is sent on Unit delete by Systray. Deletion may be denied by return TRUE
value (not recommended).

7.9 USTM_FORCEHINT
In contrast with previous messages this one is sent by Unit to its Window
(Systray redefines procedure for all windows of Unit) to show
pop-up hint.

7.10 USTM_RESIZE
Same as previous. This massage may be sent by Unit to itself in a case it want
to change own width. mp1 contains new width (in pixels).

7.11 USTM_FILLGROUPTITLE
Message is used to define Unit's name in a group. Sent to Unit's Window.
mp1 contains referrer to name holder, mp2 contains the maximum length of header.
