Stardock ObjectDock Docklet SDK v0.99a
Last Change: 8/21/2003

Note on exportable functions:

ObjectDock plugins use the __stdcall/.def linkage method rather than the __cdecl/EXPORTS method.
To export functions in a DLL for use with ObjectDock, don't forget the 'CALLBACK' in the
declaration of the function.

You must also remember to maintain a .def file which contains a listing of functions exported
by your DLL. Failure to do this will result in undefined behavior, including crashing or general
unexpected behavior by the docklet or ObjectDock. Click here for more information






OnGetInformation
           One of only a few mandatory functions, this function is called when host is looking through a folder of docklet dlls and wants to retrieve information
           about this specific docklet dll. Fill in all information accordingly for accurate reporting. This function, unlike all the others that you can export,
           is not associated with any specific instance of a plugin.

 
void CALLBACK OnGetInformation(
	char *szName, 
	char *szAuthor, 
	int *lpiVersion, 
	char *szNotes
);


	


Parameters

      szName
            Buffer in which the short name of this docklet should be copied to.

      szAuthor
            Buffer in which the name of this docklet's author should be copied to.

      lpiVerson
            Pointer to an integer which represents the version number of this specific plugin.
            Useful for automatic upgrades via packaging, so accurate versioning is recommended.
            The version of the plugin is determined by taking the value placed into lpiVersion
            and dividing by 100. Thus, (*lpiVersion) = 150; says that this is v1.5 of a docklet.

      szNotes
            Buffer in which a more detailed description (including any sidenotes) should be copied to.

Return Value

	no return


Remarks

      Show Sample
      Hide Sample

   
void CALLBACK OnGetInformation(char *szName, char *szAuthor, int *iVersion, char *szNotes)
{
	strcpy(szName, "Sample Docklet");
	strcpy(szAuthor, "Jeff Bargmann");
	(*iVersion) = 120;    //v1.20
	strcpy(szNotes,   "A simple test docklet for use in ObjectDock.");
}








OnCreate
           A mandatory function, this function is called every time a docklet from this dll is created. Provides the handle of the window the docklet will be 
           represented by, along with the instance of the docklet's dll. If the plugin is being loaded for the first time, szIni and szIniGroup will be NULL,
           however otherwise they will specify the ini file and ini section the docklet should load its individual options from.
           
           Since multiple of the same ObjectDock docklets can be added at the same time, to allow each to have their own properties,
           a structure or class pointer should be returned from OnCreate to keep track of this individual plugin's properties.

 
DOCKLET_DATA *CALLBACK OnCreate(
	HWND hwndDocklet, 
	HINSTANCE hInstance, 
	char *szIni, 
	char *szIniGroup
);


	


Parameters

      hwndDocklet
            The handle to the window that owns this docklet and therefore identifies the docklet to the host.
            This handle should be stored as it will be needed to manipulate the docklet when communicating with the host.

      hInstance
            Handle to the instance of this docklet DLL.

      szIni
            Absolute path of an INI file which the plugin should use to load options from.
            Can be NULL. If NULL, then the plugin is a new plugin and default options should be loaded.

      szIniGroup
            The INI Section of an INI file which the plugin should use to load options from.
            Can be NULL. If NULL, then the plugin is a new plugin and default options should be loaded.


Return Value

      You should return a pointer to a location in memory which this plugin will use to store it's personal "per-plugin" settings.
      The pointer returned will be passed with every further call to the plugin as to identify the specific instance of that plugin.
      (Returned datatype is arbitrary)

      Useful examples are returning a pointer to a structure or a class which can store information about this individual plugin,
      information such as owning hwnd and state data.


Remarks

      Show Sample
      Hide Sample

   
DOCKLET_DATA *CALLBACK OnCreate(HWND hwndDocklet, HINSTANCE hInstance, char *szIni, char *szIniGroup)
{
	//Create a plugin personal-data structure and return it. This data will be maintained through the life
	// of the plugin, and will be passed with every function call.
	DOCKLET_DATA *lpData = new DOCKLET_DATA;
	ZeroMemory(lpData, sizeof(DOCKLET_DATA));

	//Remember to store the docklet's window handle in its personal data so we can interact with the host!
	lpData->hwndDocklet = hwndDocklet;
	lpData->hInstanceDll = hInstance;


	/////////

	if(szIni && szIniGroup)
	{
		//If an Ini file and group were passed, load the plugin's data using them
		GetPrivateProfileString(szIniGroup, "MyString", "", lpData->szMyData, MAX_PATH, szIni);
	}
	else
	{
		//otherwise, load the default data and set the title appropriatly.
		strcpy(lpData->szMyData, "new plugin");
		DockletSetLabel(lpData->hwndDocklet, "New Plugin!");
	}

	//////////

	return lpData;
}





OnSave
           Sent to a plugin when it needs to save its individual properties. Since multiple of the same plugins can be in existence
           at any given time, the plugin should save options that are specific to this instance of the plugin to the INI file and section
           given in szIni and szIniGroup and not elsewhere.

 
void CALLBACK OnSave(
	DOCKLET_DATA *lpData, 
	char *szIni, 
	char *szIniGroup, 
	BOOL bIsForExport
);




Parameters

      lpData
            Personal data for this plugin instance returned during OnCreate. Datatype is arbitrary.

      szIni
            Absolute path of an INI file which the plugin should use to save its options to for this specific plugin instance..

      szIniGroup
            The INI Section of an INI file which the plugin should use to save options to.

      bIsForExport
            Specifies whether or not this call to OnSave is the result of the docklet being packaged for distribution.
            While insignificant for most plugins, if TRUE plugins storing passwords and other such personal should not save this data.

Return Value

      no return value


Remarks

      Show Sample
      Hide Sample

   
void CALLBACK OnSave(DOCKLET_DATA *lpData, char *szIni, char *szIniGroup, BOOL bIsForExport)
{
	WritePrivateProfileString(szIniGroup, "WebServer", lpData->szWebServer, szIni);
	WritePrivateProfileInt(szIniGroup, "PortNumber", lpData->iPortNumber, szIni);

	if(!bIsForExport)
	{
		//Only save sensitive data such as passwords if not exporting
		WritePrivateProfileString(szIniGroup, "Password", lpData->szPassword, szIni);
	}
}






OnDestroy
           Sent right before a plugin is finished being destroyed. The plugin should take this opportunity to free
           memory used by it's personal data (lpData), and do whatever other cleaning up operations it requires.

 
void CALLBACK OnDestroy(
	DOCKLET_DATA *lpData, 
	HWND hwndDocklet
);





Parameters

      lpData
            Personal data for this plugin instance returned during OnCreate. Datatype is arbitrary.

      hwndDocklet
            The handle to the window that owns this docklet and therefore identifies the docklet to the host.

Return Value

      no return value


Remarks

      Show Sample
      Hide Sample

   
void CALLBACK OnDestroy(DOCKLET_DATA *lpData, HWND hwndDocklet)
{
	EndTimer(lpData->hwndDocklet, lpData->uTimerID);


	if(lpData->szAllocatedString)
		delete [] lpData->szAllocatedString;
	lpData->szAllocatedString = NULL;


	delete lpData;
	lpData = NULL;
}






OnExportFiles
           Sent to the docklet when the docklet is to be packaged up as part of a theme to redistribute.
           The plugin will recieve a first message with iteration equal to 0. If the plugin is dependant on any file,
           it should copy that file's relative filename into szFileRelativeOut and return TRUE. If TRUE is returned, the host
           will call this function of the docket's again, with the iteration advancing by 1. The docklet should continue listing
           the filenames of files (e.g. images, common ini files, etc) until the host has been notified of all the files that 
           the docklet is dependant upon.

 
BOOL CALLBACK OnExportFiles(
	DOCKLET_DATA *lpData,
	char *szFileRelativeOut,
	int iteration
);





Parameters

      lpData
            Personal data for this plugin instance returned during OnCreate. Datatype is arbitrary.

      szFileRelativeOut
            [in/out] This string should be filled with the relative OR absolute path of a file which this
            docklet depends upon, and which should be included if the plugin is packaged up for redistribution.

      iteration
            Index of the file

Return Value

      Return TRUE to indicate a filename was copied into szFileRelativeOut, and to continue querying for more files.

      Return FALSE (or don't implement at all) to indicate that no more files need to be accounted for and to stop iterating.

      
Remarks

      Show Sample
      Hide Sample

   
BOOL CALLBACK OnExportFiles(DOCKLET_DATA *lpData, char *szFileRelativeOut, int iteration)
{
	switch(iteration)
	{
	case 0:
		strcpy(szFileRelativeOut, lpData->szImage1);
		return TRUE;
	case 1:
		strcpy(szFileRelativeOut, lpData->szImage2);
		return TRUE;
	case 2:
		strcpy(szFileRelativeOut, lpData->szCommonDataFile);
		return TRUE;
	}
	return FALSE;
}






OnLeftButtonClick
           Called by the host when the dock item that represents this docklet is clicked.
           If you choose to implement this function, you should return TRUE to indicate you processed the message.

 
BOOL CALLBACK OnLeftButtonClick(
	DOCKLET_DATA *lpData, 
	POINT *ptCursor, 
	SIZE *sizeDocklet
);





Parameters

      lpData
            Personal data for this plugin instance returned during OnCreate. Datatype is arbitrary.

      ptCursor
            The position of the cursor at the time of the event, in coordinates relative to the top-left of the docklet image.

      sizeDocklet
            The size of the docklet image at the time of the event.


Return Value

      Return TRUE to signify that this event was acted upon.

      Return FALSE or do not implement to signify that this event was NOT acted upon.
      In this case, for OnLeftButtonClick, no default action will be taken.


Remarks

      none






OnDoubleClick
           Called by the host when the dock item that represents this docklet is double left-clicked.
           If you choose to implement this function, you should return TRUE to indicate you processed the message.

 
BOOL CALLBACK OnDoubleClick(
	DOCKLET_DATA *lpData, 
	POINT *ptCursor, 
	SIZE *sizeDocklet
);




Parameters

      lpData
            Personal data for this plugin instance returned during OnCreate. Datatype is arbitrary.

      ptCursor
            The position of the cursor at the time of the event, in coordinates relative to the top-left of the docklet image.

      sizeDocklet
            The size of the docklet image at the time of the event.


Return Value

      Return TRUE to signify that this event was acted upon.

      Return FALSE or do not implement to signify that this event was NOT acted upon.
      In this case, for OnDoubleClick, no default action will be taken.


Remarks

      none






OnLeftButtonHeld
           Called by the host when the dock item that represents this docklet was either control+clicked, or had the mouse button held down on it.
           Typically a plugin will use this message to display an extended/advanced menu if applicable..
           If you choose to implement this function, you should return TRUE to indicate you processed the message.

 
BOOL CALLBACK OnLeftButtonHeld(
	DOCKLET_DATA *lpData, 
	POINT *ptCursor, 
	SIZE *sizeDocklet
);




Parameters

      lpData
            Personal data for this plugin instance returned during OnCreate. Datatype is arbitrary.

      ptCursor
            The position of the cursor at the time of the event, in coordinates relative to the top-left of the docklet image.

      sizeDocklet
            The size of the docklet image at the time of the event.


Return Value

      Return TRUE to signify that this event was acted upon.

      Return FALSE or do not implement to signify that this event was NOT acted upon.
      In this case, for OnLeftButtonHeld, no default action will be taken.


Remarks

      none





OnRightButtonClick
           Called by the host when the dock item that represents this docklet is right-clicked.
           If you choose to implement this function, you should return TRUE to indicate you processed the message.
           If you do not implement this function or return FALSE, ObjectDock will, as a default handler, display a menu
           allowing the user to configure the dock item.
           

 
BOOL CALLBACK OnRightButtonClick(
	DOCKLET_DATA *lpData, 
	POINT *ptCursor, 
	SIZE *sizeDocklet
);




Parameters

      lpData
            Personal data for this plugin instance returned during OnCreate. Datatype is arbitrary.

      ptCursor
            The position of the cursor at the time of the event, in coordinates relative to the top-left of the docklet image.

      sizeDocklet
            The size of the docklet image at the time of the event.


Return Value

      Return TRUE to signify that this event was acted upon.

      Return FALSE or do not implement to signify that this event was NOT acted upon.
      In this case, for OnRightButtonClick, the default action will be to display a simple menu
      giving the user the opportunity to bring up an options dialog for the dock item.
      (This menu item will invoke OnCommand if selected by the user)


Remarks

      none





OnConfigure
           Called by the host in the event OnRightButtonClick returned FALSE or was not impliemtned, and it was selected to configure the dock item.
           If you do not implement this function or return FALSE, ObjectDock will, as a default handler, will open a basic configuration dialog 
           allowing the dock item's text and image to be changed.
           To override this functionality, implement it and return TRUE.

 
void OnConfigure(
	DOCKLET_DATA *lpData
);





Parameters

      lpData
            Personal data for this plugin instance returned during OnCreate. Datatype is arbitrary.

Return Value

      Return TRUE to signify that this event was acted upon.

      Return FALSE or do not implement to signify that this event was NOT acted upon.
      In this case, for OnConfigure, a default configuration dialog will be shown,
      which will allow the user to change the docklet's caption and image.

Remarks

      none





OnAcceptDropFiles
           Gives the opportunity to a docklet to express its ability to accept dropped files.
           implementing this function and returning TRUE will allow for the possibility for files
           to be dropped onto this dock item, and thus a call to OnDropFiles.

 
BOOL OnAcceptDropFiles(
	DOCKLET_DATA *lpData
);





Parameters

      lpData
            Personal data for this plugin instance returned during OnCreate. Datatype is arbitrary.

Return Value

      Return TRUE to signify that this docklet can accept files dropped onto it

      Return FALSE or do not implement to signify that this docklet does not accept dropped files. (Default)

Remarks

      none





OnDropFiles
           Called by the host when a file has been dropped onto this docklet. The files being dropped
           are listed in the HDROP object passed.

 
void OnDropFiles(
	DOCKLET_DATA *lpData, 
	HDROP hDrop
);





Parameters

      lpData
            Personal data for this plugin instance returned during OnCreate. Datatype is arbitrary.

      hDrop
            An HDROP object that represents the file[s] dropped onto the docklet item.
            The docklet should free the hDrop structure accordingly upon returning from this function

Return Value

      no return

Remarks

      none





OnProcessMessage
           The window passed on OnCreate which represents and owns the docklet is the same window
           that is visible and displaying and image. While it is recommended that you do not try to
           manually change the appearance or position of this window due to this, you can watch this window's
           messages and trap any that are important to you, such as timer messages that you can set on the window.
           If implemented, all messages that are processed by the window are passed to this function.

 
void CALLBACK OnProcessMessage(
	DOCKLET_DATA *lpData, 
	HWND hwnd, 
	UINT uMsg, 
	WPARAM wParam, 
	LPARAM lParam
);




Parameters

      lpData
            Personal data for this plugin instance returned during OnCreate. Datatype is arbitrary.

      hwnd
            The handle to the window that owns this docklet and therefore identifies the docklet to the host.
            (Handle to the window that received the message)

      uMsg
            Specifies the received message

      wParam
            Specifies additional message information.
            The content of this parameter depends on the value of the uMsg parameter.

      uMsg
            Specifies additional message information.
            The content of this parameter depends on the value of the uMsg parameter.


Return Value

      no return

Remarks

      Show Sample
      Hide Sample

   
void CALLBACK OnProcessMessage(CMyDockletClass *lpDocklet, HWND hwnd, UINT uMsg, WPARAM wParam, LPARAM lParam)
{
	switch(uMsg)
	{
	case WM_TIMER:
		if(wParam == lpDocklet->GetTimerID())
			lpDocklet->DoTimer();
		break;
	}
	return;
}









.def file information


       In addition to having CALLBACK in all of the exported function declarations, the names of all functions that you wish to 
       export as part of your DLL must be added into a plain text file with a ".def" extension that must be added to your project.

       The format of this file is as follows:


  
EXPORTS
	OnGetInformation
	OnCreate
	OnDestroy

	OnSave
	OnLeftButtonClick
	OnConfigure

	(etc etc, just list all exported functions)




       If the default naming scheme of ObjectDock's Docklet format gets in the way of predefined functions
       resulting in recieving name conflict linkage errors due to some additional library you are using,
       you may name your functions differently in your source but instruct the linker to export them with the
       correct names so that ObjectDock can locate them in your DLL.
       
       If you are experiencing this problem, you may want to try renaming your exported functions in your source
       and having your .def file look like this:


  
EXPORTS
	OnGetInformation=ODOnGetInformation
	OnCreate=ODOnCreate
	OnDestroy=ODOnDestroy
	
	OnSave=ODOnSave
	OnLeftButtonClick=ODOnLeftButtonClick
	OnConfigure=ODOnConfigure







©2003 Stardock Corporation, ©2003 Jeff Bargmann. All rights reserved.