Macros
#define	cairo_dock_set_icon_surface(pIconContext, pSurface, pIcon)

#define	CD_CONFIG_GET_BOOLEAN_WITH_DEFAULT(cGroupName, cKeyName, bDefaultValue)

#define	CD_CONFIG_GET_BOOLEAN(cGroupName, cKeyName)

#define	CD_CONFIG_GET_INTEGER_WITH_DEFAULT(cGroupName, cKeyName, iDefaultValue)

#define	CD_CONFIG_GET_INTEGER(cGroupName, cKeyName)

#define	CD_CONFIG_GET_DOUBLE_WITH_DEFAULT(cGroupName, cKeyName, fDefaultValue)

#define	CD_CONFIG_GET_DOUBLE(cGroupName, cKeyName)

#define	CD_CONFIG_GET_INTEGER_LIST(cGroupName, cKeyName, iNbElements, iValueBuffer)

#define	CD_CONFIG_GET_STRING_WITH_DEFAULT(cGroupName, cKeyName, cDefaultValue)

#define	CD_CONFIG_GET_STRING(cGroupName, cKeyName)

#define	CD_CONFIG_GET_FILE_PATH(cGroupName, cKeyName, cDefaultFileName)

#define	CD_CONFIG_GET_STRING_LIST_WITH_DEFAULT(cGroupName, cKeyName, length, cDefaultValues)

#define	CD_CONFIG_GET_STRING_LIST(cGroupName, cKeyName, length)

#define	CD_CONFIG_GET_COLOR_RGBA_WITH_DEFAULT(cGroupName, cKeyName, pColorBuffer, pDefaultColor)

#define	CD_CONFIG_GET_COLOR_RGBA(cGroupName, cKeyName, pColorBuffer)

#define	CD_CONFIG_GET_COLOR_RGB_WITH_DEFAULT(cGroupName, cKeyName, pColorBuffer, pDefaultColor)

#define	CD_CONFIG_GET_COLOR_RGB(cGroupName, cKeyName, pColorBuffer)

#define	CD_CONFIG_GET_COLOR(cGroupName, cKeyName, pColor)

#define	CD_CONFIG_GET_THEME_PATH(cGroupName, cKeyName, cThemeDirName, cDefaultThemeName)

#define	CD_CONFIG_GET_GAUGE_THEME(cGroupName, cKeyName)

#define	CD_CONFIG_RENAME_GROUP(cGroupName, cNewGroupName)

#define	CD_APPLET_ADD_SUB_MENU_WITH_IMAGE(cLabel, pMenu, cImage)

#define	CD_APPLET_ADD_SUB_MENU(cLabel, pMenu)

#define	CD_APPLET_ADD_IN_MENU_WITH_STOCK_AND_DATA(cLabel, gtkStock, pCallBack, pMenu, pData)

#define	CD_APPLET_ADD_IN_MENU_WITH_DATA(cLabel, pCallBack, pMenu, pData)

#define	CD_APPLET_ADD_IN_MENU(cLabel, pCallBack, pMenu)

#define	CD_APPLET_ADD_IN_MENU_WITH_STOCK(cLabel, gtkStock, pCallBack, pMenu)

#define	CD_APPLET_ADD_SEPARATOR_IN_MENU(pMenu)

#define	CD_APPLET_POPUP_MENU_ON_MY_ICON(pMenu)

#define	CD_APPLET_RELOAD_CONFIG_PANEL

#define	CD_APPLET_RELOAD_CONFIG_PANEL_WITH_PAGE(iNumPage)

#define	CD_APPLET_MY_CONF_FILE

#define	CD_APPLET_MY_KEY_FILE

#define	CD_APPLET_MY_CONFIG_CHANGED

#define	CD_APPLET_MY_CONTAINER_TYPE_CHANGED

#define	CD_APPLET_MY_OLD_CONTAINER

#define	CD_APPLET_CLICKED_ICON

#define	CD_APPLET_CLICKED_CONTAINER

#define	CD_APPLET_SHIFT_CLICK

#define	CD_APPLET_CTRL_CLICK

#define	CD_APPLET_ALT_CLICK

#define	CD_APPLET_MY_MENU

#define	CD_APPLET_RECEIVED_DATA

#define	CD_APPLET_SCROLL_UP

#define	CD_APPLET_SCROLL_DOWN

#define	CD_APPLET_BIND_KEY(cShortKey, cDescription, cGroupName, cKeyName, handler)

#define	CD_APPLET_REDRAW_MY_ICON

#define	CAIRO_DOCK_REDRAW_MY_CONTAINER

#define	CD_APPLET_LOAD_SURFACE_FOR_MY_APPLET(cImagePath)

#define	CD_APPLET_LOAD_SURFACE_FOR_MY_APPLET_WITH_DEFAULT(cUserImageName, cDefaultLocalImageName)

#define	CD_APPLET_SET_SURFACE_ON_MY_ICON(pSurface)

#define	CD_APPLET_SET_IMAGE_ON_MY_ICON(cIconName)

#define	CD_APPLET_SET_USER_IMAGE_ON_MY_ICON(cIconName, cDefaultLocalImageName)

#define	CD_APPLET_SET_DEFAULT_IMAGE_ON_MY_ICON_IF_NONE

#define	CD_APPLET_SET_NAME_FOR_MY_ICON(cIconName)

#define	CD_APPLET_SET_NAME_FOR_MY_ICON_PRINTF(cIconNameFormat,...)

#define	CD_APPLET_SET_QUICK_INFO_ON_MY_ICON(cQuickInfo)

#define	CD_APPLET_SET_QUICK_INFO_ON_MY_ICON_PRINTF(cQuickInfoFormat,...)

#define	CD_APPLET_SET_HOURS_MINUTES_AS_QUICK_INFO(iTimeInSeconds)

#define	CD_APPLET_SET_MINUTES_SECONDES_AS_QUICK_INFO(iTimeInSeconds)

#define	CD_APPLET_SET_SIZE_AS_QUICK_INFO(iSizeInBytes)

#define	CD_APPLET_SET_STATIC_ICON

#define	CD_APPLET_UNSET_STATIC_ICON

#define	CD_APPLET_SET_ALWAYS_VISIBLE_ICON(bAlwaysVisible)

#define	CD_APPLET_ANIMATE_MY_ICON(cAnimationName, iAnimationLength)

#define	CD_APPLET_STOP_ANIMATING_MY_ICON

#define	CD_APPLET_DEMANDS_ATTENTION(cAnimationName, iAnimationLength)

#define	CD_APPLET_STOP_DEMANDING_ATTENTION

#define	CD_APPLET_GET_MY_ICON_EXTENT(iWidthPtr, iHeightPtr)

#define	CD_APPLET_START_DRAWING_MY_ICON

#define	CD_APPLET_START_DRAWING_MY_ICON_CAIRO

#define	CD_APPLET_START_DRAWING_MY_ICON_OR_RETURN(...)

#define	CD_APPLET_START_DRAWING_MY_ICON_OR_RETURN_CAIRO(...)

#define	CD_APPLET_FINISH_DRAWING_MY_ICON

#define	CD_APPLET_FINISH_DRAWING_MY_ICON_CAIRO

#define	CD_APPLET_ADD_OVERLAY_ON_MY_ICON(cImageFile, iPosition)

#define	CD_APPLET_PRINT_OVERLAY_ON_MY_ICON(cImageFile, iPosition)

#define	CD_APPLET_REMOVE_OVERLAY_ON_MY_ICON(iPosition)

#define	CD_APPLET_ADD_DATA_RENDERER_ON_MY_ICON(pAttr)

#define	CD_APPLET_RELOAD_MY_DATA_RENDERER(...)

#define	CD_APPLET_RENDER_NEW_DATA_ON_MY_ICON(pValues)

#define	CD_APPLET_REMOVE_MY_DATA_RENDERER

#define	CD_APPLET_SET_MY_DATA_RENDERER_HISTORY_TO_MAX

#define	CD_APPLET_MY_CONTAINER_IS_OPENGL

#define	CD_APPLET_SET_DESKLET_RENDERER_WITH_DATA(cRendererName, pConfig)

#define	CD_APPLET_SET_DESKLET_RENDERER(cRendererName)

#define	CD_APPLET_SET_STATIC_DESKLET

#define	CD_APPLET_ALLOW_NO_CLICKABLE_DESKLET

#define	CD_APPLET_DELETE_MY_ICONS_LIST

#define	CD_APPLET_REMOVE_ICON_FROM_MY_ICONS_LIST(pIcon)

#define	CD_APPLET_DETACH_ICON_FROM_MY_ICONS_LIST(pIcon)

#define	CD_APPLET_LOAD_MY_ICONS_LIST(pIconList, cDockRendererName, cDeskletRendererName, pDeskletRendererConfig)

#define	CD_APPLET_ADD_ICON_IN_MY_ICONS_LIST(pIcon)

#define	CD_APPLET_MY_ICONS_LIST

#define	CD_APPLET_MY_ICONS_LIST_CONTAINER

#define	CD_APPLET_MANAGE_APPLICATION(cApplicationClass)

#define	D_(message)

Enumerations
enum	CairoDockInfoDisplay { CAIRO_DOCK_INFO_NONE, CAIRO_DOCK_INFO_ON_ICON, CAIRO_DOCK_INFO_ON_LABEL }
	type of possible display on a Icon. More...

Functions
void	cairo_dock_set_icon_surface_full (cairo_t pIconContext, cairo_surface_t pSurface, double fScale, double fAlpha, Icon *pIcon)

gboolean	cairo_dock_set_image_on_icon (cairo_t pIconContext, const gchar cIconName, Icon pIcon, GldiContainer pContainer)

void	cairo_dock_set_image_on_icon_with_default (cairo_t pIconContext, const gchar cImage, Icon pIcon, GldiContainer pContainer, const gchar *cDefaultImagePath)

gchar *	cairo_dock_get_human_readable_size (long long int iSizeInBytes)

void	cairo_dock_play_sound (const gchar *cSoundPath)

Detailed Description

A collection of useful macros for applets. Macros provides a normalized API that will :

lets you perform complex operations with a minimum amount of code
ensures a bug-free functioning
masks the internal complexity
allows a normalized and easy-to-maintain code amongst all the applets.

Macro Definition Documentation

#define cairo_dock_set_icon_surface	(	pIconContext,
		pSurface,
		pIcon
	)

Apply a surface on a context. The context is cleared beforehand with the default icon background..

Parameters

pIconContext	the drawing context; is not altered by the function.
pSurface	the surface to apply.
pIcon	the icon.

#define CD_CONFIG_GET_BOOLEAN_WITH_DEFAULT	(	cGroupName,
		cKeyName,
		bDefaultValue
	)

Get the value of a 'boolean' from the conf file.

Parameters

cGroupName	name of the group in the conf file.
cKeyName	name of the key in the conf file.
bDefaultValue	default value if the group/key is not found (typically if the key is new).

Returns: a gboolean.

#define CD_CONFIG_GET_BOOLEAN	(	cGroupName,
		cKeyName
	)

Get the value of a 'boolean' from the conf file, with TRUE as default value.

Parameters

cGroupName	name of the group in the conf file.
cKeyName	name of the key in the conf file.

Returns: a gboolean.

#define CD_CONFIG_GET_INTEGER_WITH_DEFAULT	(	cGroupName,
		cKeyName,
		iDefaultValue
	)

Get the value of an 'integer' from the conf file.

Parameters

cGroupName	name of the group in the conf file.
cKeyName	name of the key in the conf file.
iDefaultValue	default value if the group/key is not found (typically if the key is new).

Returns: an integer.

#define CD_CONFIG_GET_INTEGER	(	cGroupName,
		cKeyName
	)

Get the value of a 'entier' from the conf file, with 0 as default value.

Parameters

cGroupName	name of the group in the conf file.
cKeyName	name of the key in the conf file.

Returns: an integer.

#define CD_CONFIG_GET_DOUBLE_WITH_DEFAULT	(	cGroupName,
		cKeyName,
		fDefaultValue
	)

Get the value of a 'double' from the conf file.

Parameters

cGroupName	name of the group in the conf file.
cKeyName	name of the key in the conf file.
fDefaultValue	default value if the group/key is not found (typically if the key is new).

Returns: a double.

#define CD_CONFIG_GET_DOUBLE	(	cGroupName,
		cKeyName
	)

Get the value of a 'double' from the conf file, with 0. as default value.

Parameters

cGroupName	name of the group in the conf file.
cKeyName	name of the key in the conf file.

Returns: a double.

#define CD_CONFIG_GET_INTEGER_LIST	(	cGroupName,
		cKeyName,
		iNbElements,
		iValueBuffer
	)

Get the value of an 'integers list' from the conf file.

Parameters

cGroupName	name of the group in the conf file.
cKeyName	name of the key in the conf file.
iNbElements	number of elements to get from the conf file.
iValueBuffer	buffer to fill with the values.

#define CD_CONFIG_GET_STRING_WITH_DEFAULT	(	cGroupName,
		cKeyName,
		cDefaultValue
	)

Get the value of a 'string' from the conf file.

Parameters

cGroupName	name of the group in the conf file.
cKeyName	name of the key in the conf file.
cDefaultValue	default value if the group/key is not found (typically if the key is new). can be NULL.

Returns: a newly allocated string.

#define CD_CONFIG_GET_STRING	(	cGroupName,
		cKeyName
	)

Get the value of a 'string' from the conf file, with NULL as default value.

Parameters

cGroupName	name of the group in the conf file.
cKeyName	name of the key in the conf file.

Returns: a newly allocated string.

#define CD_CONFIG_GET_FILE_PATH	(	cGroupName,
		cKeyName,
		cDefaultFileName
	)

Get the value of a 'file' from the conf file, with NULL as default value. If the value is a file name (not a path), it is supposed to be in the Cairo-Dock's current theme folder. If the value is NULL, the default file is used, taken at the applet's data folder, but the conf file is not updated with this value.

Parameters

cGroupName	name of the group in the conf file.
cKeyName	name of the key in the conf file.
cDefaultFileName	defaul tfile if none is specified in the conf file.

Returns: a newly allocated string giving the complete path of the file.

#define CD_CONFIG_GET_STRING_LIST_WITH_DEFAULT	(	cGroupName,
		cKeyName,
		length,
		cDefaultValues
	)

Get the value of a 'strings list' from the conf file.

Parameters

cGroupName	name of the group in the conf file.
cKeyName	name of the key in the conf file.
length	pointer to the number of strings that were extracted from the conf file.
cDefaultValues	default value if the group/key is not found (typically if the key is new). It is a string with words separated by ';'. It can be NULL.

Returns: a table of strings, to be freeed with 'g_strfreev'.

#define CD_CONFIG_GET_STRING_LIST	(	cGroupName,
		cKeyName,
		length
	)

Get the value of a 'strings list' from the conf file, with NULL as default value.

Parameters

cGroupName	name of the group in the conf file.
cKeyName	name of the key in the conf file.
length	pointer to the number of strings that were extracted from the conf file.

Returns: a table of strings, to be freeed with 'g_strfreev'.

#define CD_CONFIG_GET_COLOR_RGBA_WITH_DEFAULT	(	cGroupName,
		cKeyName,
		pColorBuffer,
		pDefaultColor
	)

Get the value of a 'color' in the RGBA format from the conf file.

Parameters

cGroupName	name of the group in the conf file.
cKeyName	name of the key in the conf file.
pColorBuffer	a table of 4 'double' already allocated, that will be filled with the color components.
pDefaultColor	default value if the group/key is not found (typically if the key is new). It is a table of 4 'double'. It can be NULL.

#define CD_CONFIG_GET_COLOR_RGBA	(	cGroupName,
		cKeyName,
		pColorBuffer
	)

Get the value of a 'color' in the RGBA format from the conf file, with NULL as default value.

Parameters

cGroupName	name of the group in the conf file.
cKeyName	name of the key in the conf file.
pColorBuffer	a table of 4 'double' already allocated, that will be filled with the color components.

#define CD_CONFIG_GET_COLOR_RGB_WITH_DEFAULT	(	cGroupName,
		cKeyName,
		pColorBuffer,
		pDefaultColor
	)

Get the value of a 'color' in the RGB format from the conf file.

Parameters

cGroupName	name of the group in the conf file.
cKeyName	name of the key in the conf file.
pColorBuffer	a table of 3 'double' already allocated, that will be filled with the color components.
pDefaultColor	default value if the group/key is not found (typically if the key is new). It is a table of 3 'double'. It can be NULL.

#define CD_CONFIG_GET_COLOR_RGB	(	cGroupName,
		cKeyName,
		pColorBuffer
	)

Get the value of a 'color' in the RGB format from the conf file, with NULL as default value.

Parameters

cGroupName	name of the group in the conf file.
cKeyName	name of the key in the conf file.
pColorBuffer	a table of 3 'double' already allocated, that will be filled with the color components.

#define CD_CONFIG_GET_COLOR	(	cGroupName,
		cKeyName,
		pColor
	)

Get the value of a 'color' in a GldiColor from the conf file, with NULL as default value.

Parameters

cGroupName	name of the group in the conf file.
cKeyName	name of the key in the conf file.
pColor	a GldiColor already allocated, that will be filled with the color components.

#define CD_CONFIG_GET_THEME_PATH	(	cGroupName,
		cKeyName,
		cThemeDirName,
		cDefaultThemeName
	)

Get the complete path of a theme in the conf file.

Parameters

cGroupName	name of the group (in the conf file).
cKeyName	name of the key (in the conf file).
cThemeDirName	name of the folder containing the local, user, and distant themes.
cDefaultThemeName	default value, if the key/group/theme doesn't exist.

Returns: Path to the folder of the theme, in a newly allocated string.

#define CD_CONFIG_GET_GAUGE_THEME	(	cGroupName,
		cKeyName
	)

Get the complete path of a Gauge theme in the conf file.

Parameters

cGroupName	name of the group (in the conf file).
cKeyName	name of the key (in the conf file).

Returns: Path to the theme, in a newly allocated string.

#define CD_CONFIG_RENAME_GROUP	(	cGroupName,
		cNewGroupName
	)

Rename a group in the conf file, in case you had to change it. Do nothing if the old group no more exists in the conf file.

Parameters

cGroupName	name of the group.
cNewGroupName	new name of the group.

#define CD_APPLET_ADD_SUB_MENU_WITH_IMAGE	(	cLabel,
		pMenu,
		cImage
	)

Create and add a sub-menu to a given menu.

Parameters

cLabel	name of the sub-menu.
pMenu	GtkWidget of the menu we will add the sub-menu to..
cImage	name of an image (can be a path or a GtkStock).

Returns: the sub-menu, newly created and attached to the menu.

#define CD_APPLET_ADD_SUB_MENU	(	cLabel,
		pMenu
	)

Create and add a sub-menu to a given menu.

Parameters

cLabel	name of the sub-menu.
pMenu	GtkWidget of the menu we will add the sub-menu to..

Returns: the sub-menu, newly created and attached to the menu.

#define CD_APPLET_ADD_IN_MENU_WITH_STOCK_AND_DATA	(	cLabel,
		gtkStock,
		pCallBack,
		pMenu,
		pData
	)

Create and add an entry to a menu, with an icon.

Parameters

cLabel	name of the entry.
gtkStock	name of a GTK icon or path to an image.
pCallBack	function called when the user selects this entry.
pMenu	menu to add the entry to.
pData	data passed as parameter of the callback.

#define CD_APPLET_ADD_IN_MENU_WITH_DATA	(	cLabel,
		pCallBack,
		pMenu,
		pData
	)

Create and add an entry to a menu.

Parameters

cLabel	name of the entry.
pCallBack	function called when the user selects this entry.
pMenu	menu to add the entry to.
pData	data passed as parameter of the callback.

#define CD_APPLET_ADD_IN_MENU	(	cLabel,
		pCallBack,
		pMenu
	)

Create and add an entry to a menu. 'myApplet' will be passed to the callback.

Parameters

cLabel	name of the entry.
pCallBack	function called when the user selects this entry.
pMenu	menu to add the entry to.

#define CD_APPLET_ADD_IN_MENU_WITH_STOCK	(	cLabel,
		gtkStock,
		pCallBack,
		pMenu
	)

Create and add an entry to a menu, with an icon. 'myApplet' will be passed to the callback.

Parameters

cLabel	name of the entry.
gtkStock	name of a GTK icon or path to an image.
pCallBack	function called when the user selects this entry.
pMenu	menu to add the entry to.

#define CD_APPLET_ADD_SEPARATOR_IN_MENU ( pMenu )

Create and add a separator to a menu.

#define CD_APPLET_POPUP_MENU_ON_MY_ICON ( pMenu )

Pop-up a menu on the applet's icon.

Parameters

pMenu menu to show

#define CD_APPLET_RELOAD_CONFIG_PANEL

Reload the config panel of the applet. This is useful if you have custom widgets inside your conf file, and need to reload them.

#define CD_APPLET_RELOAD_CONFIG_PANEL_WITH_PAGE ( iNumPage )

Reload the config panel of the applet and jump to the given page. This is useful if you have custom widgets inside your conf file, and need to reload them.

#define CD_APPLET_MY_CONF_FILE

Path of the applet's instance's conf file.

#define CD_APPLET_MY_KEY_FILE

Key file of the applet instance, availale during the init, config, and reload.

#define CD_APPLET_MY_CONFIG_CHANGED

TRUE if the conf file has changed before the reload.

#define CD_APPLET_MY_CONTAINER_TYPE_CHANGED

TRUE if the container type has changed (which can only happen if the config has changed).

#define CD_APPLET_MY_OLD_CONTAINER

The previous Container.

#define CD_APPLET_CLICKED_ICON

The clicked Icon.

#define CD_APPLET_CLICKED_CONTAINER

The clicked Container.

#define CD_APPLET_SHIFT_CLICK

TRUE if the 'SHIFT' key was pressed during the click.

#define CD_APPLET_CTRL_CLICK

TRUE if the 'CTRL' key was pressed during the click.

#define CD_APPLET_ALT_CLICK

TRUE if the 'ALT' key was pressed during the click.

#define CD_APPLET_MY_MENU

Main menu of the applet.

#define CD_APPLET_RECEIVED_DATA

Data received after a drop occured (string).

#define CD_APPLET_SCROLL_UP

TRUE if the user scrolled up.

#define CD_APPLET_SCROLL_DOWN

TRUE if the user scrolled down.

#define CD_APPLET_BIND_KEY	(	cShortKey,
		cDescription,
		cGroupName,
		cKeyName,
		handler
	)

Bind a shortkey to an action. Unref it when you don't want it anymore. 'myApplet' is passed as the callback data.

Parameters

cShortKey	a keyboard shortcut.
cDescription	a short description of the action
cGroupName	group name where it's stored in the applet's conf file
cKeyName	key name where it's stored in the applet's conf file
handler	function called when the shortkey is pressed by the user

Returns: the shortkey.

#define CD_APPLET_REDRAW_MY_ICON

Redraw the applet's icon (as soon as the main loop is available).

#define CAIRO_DOCK_REDRAW_MY_CONTAINER

Redraw the applet's container (as soon as the main loop is available).

#define CD_APPLET_LOAD_SURFACE_FOR_MY_APPLET ( cImagePath )

Load an image into a surface, at the same size as the applet's icon. If the image is given by its sole name, it is searched inside the current theme root folder.

Parameters

cImagePath path or name of an image.

Returns: the newly allocated surface.

#define CD_APPLET_LOAD_SURFACE_FOR_MY_APPLET_WITH_DEFAULT	(	cUserImageName,
		cDefaultLocalImageName
	)

Load a user image into a surface, at the same size as the applet's icon, or a default image taken in the installed folder of the applet if the first one is NULL. If the user image is given by its sole name, it is searched inside the current theme root folder.

Parameters

cUserImageName	name or path of an user image.
cDefaultLocalImageName	default image

Returns: the newly allocated surface.

#define CD_APPLET_SET_SURFACE_ON_MY_ICON ( pSurface )

Apply a surface on the applet's icon, and redraw it.

Parameters

pSurface the surface to draw on your icon.

#define CD_APPLET_SET_IMAGE_ON_MY_ICON ( cIconName )

Apply an image on the applet's icon. The image is resized at the same size as the icon. Does not trigger the icon refresh.

Parameters

cIconName name of an icon or path to an image.

#define CD_APPLET_SET_USER_IMAGE_ON_MY_ICON	(	cIconName,
		cDefaultLocalImageName
	)

Apply an image on the applet's icon, clearing it beforehand, and adding the reflect. The image is searched in any possible locations, and the default image provided is used if the search was fruitless (taken in the installation folder of the applet).

Parameters

cIconName	name of an icon or path to an image.
cDefaultLocalImageName	name of an image to use as a fallback (taken in the applet's installation folder).

#define CD_APPLET_SET_DEFAULT_IMAGE_ON_MY_ICON_IF_NONE

Apply the default icon on the applet's icon if there is no image yet.

#define CD_APPLET_SET_NAME_FOR_MY_ICON ( cIconName )

Set a new label on the applet's icon.

Parameters

cIconName the label.

#define CD_APPLET_SET_NAME_FOR_MY_ICON_PRINTF	(	cIconNameFormat,
		...
	)

Set a new label on the applet's icon.

Parameters

cIconNameFormat	the label, in a 'printf'-like format.
...	values to be written in the string.

#define CD_APPLET_SET_QUICK_INFO_ON_MY_ICON ( cQuickInfo )

Set a quick-info on the applet's icon.

Parameters

cQuickInfo the quick-info. This is a small text (a few characters) that is superimposed on the icon.

#define CD_APPLET_SET_QUICK_INFO_ON_MY_ICON_PRINTF	(	cQuickInfoFormat,
		...
	)

Set a quick-info on the applet's icon.

Parameters

cQuickInfoFormat	the label, in a 'printf'-like format.
...	values to be written in the string.

#define CD_APPLET_SET_HOURS_MINUTES_AS_QUICK_INFO ( iTimeInSeconds )

Write the time in hours-minutes as a quick-info on the applet's icon.

Parameters

iTimeInSeconds the time in seconds.

#define CD_APPLET_SET_MINUTES_SECONDES_AS_QUICK_INFO ( iTimeInSeconds )

Write the time in minutes-secondes as a quick-info on the applet's icon.

Parameters

iTimeInSeconds the time in seconds.

#define CD_APPLET_SET_SIZE_AS_QUICK_INFO ( iSizeInBytes )

Write a size in bytes as a quick-info on the applet's icon.

Parameters

iSizeInBytes the size in bytes, converted into a readable format.

#define CD_APPLET_SET_STATIC_ICON

Prevent the applet's icon to be animated when the mouse hovers it (call it once at init).

#define CD_APPLET_UNSET_STATIC_ICON

Prevent the applet's icon to be animated when the mouse hovers it (call it once at init).

#define CD_APPLET_SET_ALWAYS_VISIBLE_ICON ( bAlwaysVisible )

Make the applet's icon always visible, even when the dock is hidden.

#define CD_APPLET_ANIMATE_MY_ICON	(	cAnimationName,
		iAnimationLength
	)

Launch an animation on the applet's icon.

Parameters

cAnimationName	name of the animation.
iAnimationLength	number of rounds the animation should be played.

#define CD_APPLET_STOP_ANIMATING_MY_ICON

Stop any animation on the applet's icon.

#define CD_APPLET_DEMANDS_ATTENTION	(	cAnimationName,
		iAnimationLength
	)

Make applet's icon demanding the attention : it will launch the given animation, and the icon will be visible even if the dock is hidden.

Parameters

cAnimationName	name of the animation.
iAnimationLength	number of rounds the animation should be played, or 0 for an endless animation.

#define CD_APPLET_STOP_DEMANDING_ATTENTION

Stop the demand of attention on the applet's icon.

#define CD_APPLET_GET_MY_ICON_EXTENT	(	iWidthPtr,
		iHeightPtr
	)

Get the dimension allocated to the surface/texture of the applet's icon.

Parameters

iWidthPtr	pointer to the width.
iHeightPtr	pointer to the height.

#define CD_APPLET_START_DRAWING_MY_ICON

Initiate an OpenGL drawing session on the applet's icon.

#define CD_APPLET_START_DRAWING_MY_ICON_CAIRO

Initiate a Cairo drawing session on the applet's icon.

#define CD_APPLET_START_DRAWING_MY_ICON_OR_RETURN ( ... )

Initiate an OpenGL drawing session on the applet's icon, or quit the function if failed.

Parameters

...	value to return in case of failure.

#define CD_APPLET_START_DRAWING_MY_ICON_OR_RETURN_CAIRO ( ... )

Initiate a Cairo drawing session on the applet's icon, or quit the function if failed.

Parameters

...	value to return in case of failure.

#define CD_APPLET_FINISH_DRAWING_MY_ICON

Terminate an OpenGL drawing session on the applet's icon. Does not trigger the icon's redraw.

#define CD_APPLET_FINISH_DRAWING_MY_ICON_CAIRO

Terminate an OpenGL drawing session on the applet's icon. Does not trigger the icon's redraw.

#define CD_APPLET_ADD_OVERLAY_ON_MY_ICON	(	cImageFile,
		iPosition
	)

Add an overlay from an image on the applet's icon.

Parameters

cImageFile	an image (if it's not a path, it is searched amongst the current theme's images)
iPosition	position where to display the overlay

Returns: the overlay, or NULL if the image couldn't be loaded.

#define CD_APPLET_PRINT_OVERLAY_ON_MY_ICON	(	cImageFile,
		iPosition
	)

Print an overlay from an image on the applet's icon (it can't be removed without erasing the icon).

Parameters

cImageFile	an image (if it's not a path, it is searched amongst the current theme's images)
iPosition	position where to display the overlay

Returns: TRUE if the overlay has been successfuly printed.

#define CD_APPLET_REMOVE_OVERLAY_ON_MY_ICON ( iPosition )

Remove an overlay from the applet's icon. The overlay is destroyed.

Parameters

iPosition position of the overlay

#define CD_APPLET_ADD_DATA_RENDERER_ON_MY_ICON ( pAttr )

Add a Data Renderer the applet's icon.

Parameters

pAttr the attributes of the Data Renderer. They allow you to define its properties.

#define CD_APPLET_RELOAD_MY_DATA_RENDERER ( ... )

Reload the Data Renderer of the applet's icon, without changing any of its parameters. Previous values are kept.

#define CD_APPLET_RENDER_NEW_DATA_ON_MY_ICON ( pValues )

Add new values to the Data Renderer of the applet's icon. Values are a table of 'double', having the same size as defined when the data renderer was created (1 by default). It also triggers the redraw of the icon.

Parameters

pValues the values, a table of double of the correct size.

#define CD_APPLET_REMOVE_MY_DATA_RENDERER

Completely remove the Data Renderer of the applet's icon, including the values associated with.

#define CD_APPLET_SET_MY_DATA_RENDERER_HISTORY_TO_MAX

Set the history size of the Data Renderer of the applet's icon to the maximum size, that is to say 1 value per pixel.

#define CD_APPLET_MY_CONTAINER_IS_OPENGL

Say if the applet's container currently supports OpenGL.

#define CD_APPLET_SET_DESKLET_RENDERER_WITH_DATA	(	cRendererName,
		pConfig
	)

Set a renderer to the applet's desklet and create myDrawContext. Call it at the beginning of init and also reload, to take into account the desklet's resizing.

Parameters

cRendererName	name of the renderer.
pConfig	configuration data for the renderer, or NULL.

#define CD_APPLET_SET_DESKLET_RENDERER ( cRendererName )

Set a renderer to the applet's desklet and create myDrawContext. Call it at the beginning of init and also reload, to take into account the desklet's resizing.

Parameters

cRendererName name of the renderer.

#define CD_APPLET_SET_STATIC_DESKLET

Prevent the desklet from being rotated. Use it if your desklet has some static GtkWidget inside.

#define CD_APPLET_ALLOW_NO_CLICKABLE_DESKLET

Prevent the desklet from being transparent to click. Use it if your desklet has no meaning in being unclickable.

#define CD_APPLET_DELETE_MY_ICONS_LIST

Delete the list of icons of an applet (keep the subdock in dock mode).

#define CD_APPLET_REMOVE_ICON_FROM_MY_ICONS_LIST ( pIcon )

Remove an icon from the list of icons of an applet. The icon is destroyed and should not be used after that.

Parameters

pIcon the icon to remove.

Returns: whether the icon has been removed or not. In any case, the icon is freed.

#define CD_APPLET_DETACH_ICON_FROM_MY_ICONS_LIST ( pIcon )

Detach an icon from the list of icons of an applet. The icon is not destroyed.

Parameters

pIcon the icon to remove.

Returns: whether the icon has been removed or not.

#define CD_APPLET_LOAD_MY_ICONS_LIST	(	pIconList,
		cDockRendererName,
		cDeskletRendererName,
		pDeskletRendererConfig
	)

Load a list of icons into an applet, with the given renderer for the sub-dock or the desklet. The icons will be loaded automatically in an idle process.

Parameters

pIconList	a list of icons. It will belong to the applet's container after that.
cDockRendererName	name of a renderer in case the applet is in dock mode.
cDeskletRendererName	name of a renderer in case the applet is in desklet mode.
pDeskletRendererConfig	possible configuration parameters for the desklet renderer.

#define CD_APPLET_ADD_ICON_IN_MY_ICONS_LIST ( pIcon )

Add an icon into an applet. The view previously set by CD_APPLET_LOAD_MY_ICONS_LIST will be used. The icon will be loaded automatically in an idle process.

Parameters

pIcon an icon.

#define CD_APPLET_MY_ICONS_LIST

Get the list of icons of your applet. It is either the icons of your sub-dock or of your desklet.

#define CD_APPLET_MY_ICONS_LIST_CONTAINER

Get the container of the icons of your applet. It is either your sub-dock or your desklet.

#define CD_APPLET_MANAGE_APPLICATION ( cApplicationClass )

Let your applet control the window of an external program, instead of the Taskbar.

Parameters

cApplicationClass the class of the application you wish to control (in lower case), or NULL to stop controling any appli.

#define D_ ( message )

Macro for gettext, similar to _() et N_(), but with the domain of the applet. Surround all your strings with this, so that 'xgettext' can find them and automatically include them in the translation files.

Enumeration Type Documentation

enum CairoDockInfoDisplay

type of possible display on a Icon.

Enumerator
CAIRO_DOCK_INFO_NONE	don't display anything.
CAIRO_DOCK_INFO_ON_ICON	display info on the icon (as quick-info).
CAIRO_DOCK_INFO_ON_LABEL	display on the label of the icon.

Function Documentation

void cairo_dock_set_icon_surface_full	(	cairo_t *	pIconContext,
		cairo_surface_t *	pSurface,
		double	fScale,
		double	fAlpha,
		Icon *	pIcon
	)

Apply a surface on a context, with a zoom and a transparency factor. The context is cleared beforehand with the default icon background.

Parameters

pIconContext	the drawing context; is not altered by the function.
pSurface	the surface to apply.
fScale	zoom factor.
fAlpha	transparency in [0,1].
pIcon	the icon.

gboolean cairo_dock_set_image_on_icon	(	cairo_t *	pIconContext,
		const gchar *	cIconName,
		Icon *	pIcon,
		GldiContainer *	pContainer
	)

Apply an image on the context of an icon, clearing it beforehand, and adding the reflect.

Parameters

pIconContext	the drawing context; is not altered by the function.
cIconName	name or path to an icon image.
pIcon	the icon.
pContainer	the container of the icon.

Returns: TRUE if everything went smoothly.

void cairo_dock_set_image_on_icon_with_default	(	cairo_t *	pIconContext,
		const gchar *	cImage,
		Icon *	pIcon,
		GldiContainer *	pContainer,
		const gchar *	cDefaultImagePath
	)

Apply an image on the context of an icon, clearing it beforehand, and adding the reflect. The image is searched in any possible locations, and the default image provided is used if the search was fruitless.

Parameters

pIconContext	the drawing context; is not altered by the function.
cImage	name of an image to apply on the icon.
pIcon	the icon.
pContainer	the container of the icon.
cDefaultImagePath	path to a default image.

gchar* cairo_dock_get_human_readable_size ( long long int iSizeInBytes )

Convert a size in bytes into a readable format.

Parameters

iSizeInBytes size in bytes.

Returns: a newly allocated string.

void cairo_dock_play_sound ( const gchar * cSoundPath )

Play a sound, through Alsa or PulseAudio.

Parameters

cSoundPath path to an audio file.

Macros

Enumerations

Functions

Detailed Description

Macro Definition Documentation

Enumeration Type Documentation

Function Documentation