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

Note on ObjectDock Docklet SDK functions:

The included SDK functions allow the docklet to interact with the host, ObjectDock. To uniquely
identify the plugin, you should always remember to record the "hwndDocklet" parameter given in
"OnCreate", as it will be needed for the host to identify what dock item you are trying to reference
when making changes or querying for information. Remember to always pass the hwndDocklet when it is asked for!






DockletIsVisible
           Querys for whether or not the specified docklet is currently visible.

 
BOOL DockletIsVisible(
	HWND hwndDocklet
);


	


Parameters

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

Return Value

      TRUE if the docklet specified is currently visible.

      FALSE if the docklet specified is currently hidden.


Remarks

      none






DockletGetRect
           Retrieves the bounding rectangle of a given docklet in screen coordinates.

 
BOOL DockletGetRect(
	HWND hwndDocklet, 
	RECT *rcDocklet
);


	


Parameters

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

      rcDocklet
            [out] Pointer to a RECT struct to receive the bounding rectangle of the given docklet's image in screen coordinates.

Return Value

      TRUE if the docklet specified is currently visible.

      FALSE if the docklet specified is currently hidden.


Remarks

      none




DockletGetLabel
           Retrieves the current label of the specified docklet.

 
int DockletGetLabel(
	HWND hwndDocklet, 
	char *szLabel
);


	


Parameters

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

      szLabel
            [out] Pointer to a string to receive the label of the string.
                  Can be NULL - if NULL, no information is copied but the length of the string required will still be returned.

Return Value

      Returns the length of the string that either was or would be copied to szLabel including the null character.


Remarks

      none




DockletSetLabel
           Changes the current label of the specified docklet.

 
int DockletSetLabel(
	HWND hwndDocklet, 
	char *szLabel
);


	


Parameters

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

      szLabel
            [in] Pointer to a string with a new label for the specified docklet.

Return Value

      Returns the length of the string that either was or would be copied to szLabel including the null character.


Remarks

      none




DockletLoadGDIPlusImage
           Loads an GDI+ image based on a relative path given.

 
Bitmap *DockletLoadGDIPlusImage(
	char *szImage
);


	


Parameters

      szImage
            [in] The relative (or absolute) path of the image to load.
            (Png, tga, and ico formats are supported explicitly. Other formats such as .psd are supported on a per-system basis.)


Return Value

      Returns a pointer to the Bitmap*  GDI+ image loaded for the image file passed.


Remarks

      This method is much preferred to loading the image into a Bitmap* GDI+ plus object manually, for the reasons that
      DockletLoadGDIPlusImage can load an image based on a relative path which makes for more reliable saving,
      and in addition DockletLoadGDIPlusImage can load from images not supported by GDI+ such as from 32bit Icons.




DockletSetImage
           Allows a docklet to manually set its image to a given GDI+ Image.

 
void DockletSetImage(
	HWND hwndDocklet, 
	Image *lpImageNew, 
	BOOL bAutomaticallyDeleteImage = TRUE
);


	


Parameters

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

      lpImageNew
            [in] Specifies the new base image for the docklet.

      bAutomaticallyDeleteImage
            Upon the next call to DockletSetImage, DockletSetImageFile, etc, ObjectDock would by default delete the image set to it by
            this function. Set this flag to FALSE to prevent ObjectDock from deleting this image, thus allowing this image to be reused
            after it is no longer being displayed. By default, set to TRUE - yes delete the image after no longer in use.

Return Value

      no return


Remarks

      none




DockletSetImageFile
           Changes the specified docklet's image to that of the given file.

 
void DockletSetImageFile(
	HWND hwndDocklet, 
	char *szImage
);


	


Parameters

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

      szImage
            [in] Specifies the relative (or absolute) path of an image to set as the image for the specified docklet.

Return Value

      no return


Remarks

      none




DockletSetImageOverlay
           In ObjectDock, instead of dealing with Paint messages, ObjectDock allows you to set an image for
           your docklet at any time, as well as setting an 'overlay' image over to top of this base image.
           This allows for such things as a base background image to be constantly loaded, and then for details to
           be added on top of this image, for example a CPU meter on top of a holder, or a mail notification icon
           with a number on top of a mail icon loaded from a file, which will not have to be
           reloaded when mail arrives and the overlay image needs to be changed.

 
void DockletSetImageOverlay(
	HWND hwndDocklet, 
	Image *imageOverlay, 
	BOOL bAutomaticallyDeleteImage = TRUE
);


	


Parameters

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

      imageOverlay
            [in] Specifies the new overlay image for the docklet, which will draw directly and seamlessly over any image set using DockletSetImage or DockletSetImageFile.

      bAutomaticallyDeleteImage
            Upon the next call to DockletSetImageOverlay, etc, ObjectDock would by default delete the image set to it by
            this function. Set this flag to FALSE to prevent ObjectDock from deleting this image, thus allowing this image to be reused
            after it is no longer being displayed. By default, set to TRUE - yes delete the image after no longer in use.

Return Value

      no return


Remarks

      none




DockletBrowseForImage
           Allows a docklet to quickly and easily browse for a new image.
           Shows the standard ObjectDock "Choose Image" dialog template, and allows you to select an image file.
           for any purpose you wish, including choosing images for different states a docklet might have.

 
BOOL DockletBrowseForImage(
	HWND hwndParent, 
	char *szImage, 
	char *szAlternateRelativeRoot = NULL
);


	


Parameters

      hwndParent
            The handle to a window to be a parent window to the "Choose Image" that will be created.
            (e.g. a configuration dialog window)

      szImage
            [in/out] Specifies the current image, and is filled with the image that the user selects from the
            "Choose Image" dialog.


      szAlternateRelativeRoot
            [optional] If you would only like to show images from a specific subfolder of ObjectDock's folder,
            for example if you only want the user to pick an image from your docklet's folder, you can pass
            a string with a relative path with the folder you want to start browsing from, for example, a folder
            obtained by using the DockletGetRelativeFolder function.


Return Value

      Returns TRUE if the image was changed.

      Returns FALSE if the image was not changed.

Remarks

      It is highly recommended you use all relative paths when dealing with images, as it saves a considerable
      amount of work to changing absolute paths to relative paths and back again. Dealing with relative paths
      just generally makes docklets be much more distributable and practical.




DockletLockMouseEffect
           Allows a docklet to lock the mouse effect (e.g. zooming, etc) of its owning dock,
           something useful when trying to display a right-click menu or otherwise from a docklet.

 
void DockletLockMouseEffect(
	HWND hwndDocklet, 
	BOOL bLock
);


	


Parameters

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

      bLock
            TRUE to lock the mouseover effect (zooming, etc) of the dock.
            FALSE to unlock the mouseover effect (zooming, etc) of the dock.

Return Value

      no return


Remarks

      The mouseover effect lock is done via a counter, so that if multiple docklets are locking at the same time
      the effect will stay locked until the last docklet unlocks. The counter does not check to make sure one docklet
      is not continually unlocking however, so do not do this as it will interfere with other docklets.
      Only lock and unlock the mouse effect when needed.




DockletDoAttentionAnimation
           Causes the specified docklet to animate in the dock to try to get the user's attention.

 
void DockletDoAttentionAnimation(
	HWND hwndDocklet
);


	


Parameters

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

Return Value

      no return


Remarks

      none




DockletGetRelativeFolder
           Retrieves the relative path of the folder that contains the specified docklet's DLL.

 
void DockletGetRelativeFolder(
	HWND hwndDocklet,
	char *szFolder
);


	


Parameters

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

      szFolder
            [out] Pointer to a string that will receive the relative location of folder that contains the specified docklet's DLL.

Return Value

      no return


Remarks

      The path returned includes a final backslash.

      You can use this path returned to create a private INI file to store settings common to all docklets of this same type
      that might be added to a dock, e.g. language or regional settings, which would be constant from instance to instance of 
      a given plugin.

      In addition, you can limit the user to only picking images for this plugin from this plugin's folder by use with DockletBrowseForImage.



DockletGetRootFolder
           Returns the absolute location of the ObjectDock root folder, from which all things are relative.

 
void DockletGetRootFolder(
	HWND hwndDocklet, 
	char *szFolder
);


	


Parameters

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

      szFolder
            [out] Pointer to a string that will receive the absolute location of the ObjectDock root folder.

Return Value

      no return


Remarks

      The path returned includes a final backslash.

      To turn any relative path given anywhere into an absolute path, simply copy the relative 
      path you want to make absolute onto the end of the the path returned by this function.





DockletDefaultConfigDialog
           Opens up the default configuration dialog for a given dock item,
           thus providing a simple way for the user to adjust a docklet's 
           title and image.

 
void DockletDefaultConfigDialog(
	HWND hwndDocklet
);


	


Parameters

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

Return Value

      no return


Remarks

      The default config dialog configures a plugin's text and image only, but can be useful as a method of configuring for simple docklets.






DockletQueryDockEdge
           Retrieves which edge of the screen the dock with the given docklet is located on.

 
int DockletQueryDockEdge(
	HWND hwndDocklet
);


	

Parameters

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

Return Value

      Returns which edge of the screen that the dock containing the given docklet is on.


      The return values for this function are as follows:
		
      0 = Bottom Edge of the screen
      1 = Top Edge of the screen
      2 = Left Edge of the screen
      3 = Right Edge of the screen

Remarks

      none





DockletSetDockEdge
           Changes which edge of the screen the dock with the given docklet is located on.

 
int DockletSetDockEdge(
	HWND hwndDocklet,
	int iNewEdge
);


	

Parameters

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

      iNewEdge
            Defines the new edge of the screen the dock should be docked to.
            
            Possible values are as follows:

            0 = Bottom Edge of the screen
            1 = Top Edge of the screen
            2 = Left Edge of the screen
            3 = Right Edge of the screen

Return Value

      Returns new position of the given dock on the screen.

Remarks

      none





DockletQueryDockAlign
           Retrieves the alignment of the dock with the given docklet.

 
int DockletQueryDockAlign(
	HWND hwndDocklet
);


	

Parameters

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

Return Value

      Returns the alignment of the dock containing the given docklet.


      The return values for this function are as follows:
		
      0 = Align left (or top, if dock is vertical)
      1 = Align middle
      2 = Align right (or bottom, if dock is vertical)

Remarks

      none





DockletSetDockAlign
           Changes the alignment of the dock with the given docklet.

 
int DockletSetDockAlign(
	HWND hwndDocklet,
	int iNewAlign
);


	

Parameters

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

      iNewAlign
            Defines the new alignment of the dock with the specified docklet.
            
            Possible values are as follows:

            0 = Align left (or top, if dock is vertical)
            1 = Align middle
            2 = Align right (or bottom, if dock is vertical)

Return Value

      Returns new position of the given dock on the screen.

Remarks

      none






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