cairo-dock-applet-facility.h File Reference

Defines
#define	cairo_dock_set_icon_surface(pIconContext, pSurface)
#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_WITH_DEFAULT(cGroupName, cKeyName, pColorBuffer, pDefaultColor)
#define	CD_CONFIG_GET_COLOR(cGroupName, cKeyName, pColorBuffer)
#define	CD_CONFIG_GET_COLOR_RVB_WITH_DEFAULT(cGroupName, cKeyName, pColorBuffer, pDefaultColor)
#define	CD_CONFIG_GET_COLOR_RVB(cGroupName, cKeyName, pColorBuffer)
#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_CREATE_MY_SUB_MENU(...)
#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_ADD_ABOUT_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_REDRAW_MY_ICON
#define	CAIRO_DOCK_REDRAW_MY_CONTAINER
#define	CD_APPLET_UPDATE_REFLECT_ON_MY_ICON
#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_SURFACE_ON_MY_ICON_WITH_ZOOM(pSurface, fScale)
#define	CD_APPLET_SET_SURFACE_ON_MY_ICON_WITH_ALPHA(pSurface, fAlpha)
#define	CD_APPLET_SET_SURFACE_ON_MY_ICON_WITH_BAR(pSurface, fValue)
#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_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_OR_RETURN(...)
#define	CD_APPLET_FINISH_DRAWING_MY_ICON
#define	CD_APPLET_ADD_OVERLAY(cImageFile, iPosition)
#define	CD_APPLET_REMOVE_OVERLAY(iPosition)
#define	CD_APPLET_MAKE_EMBLEM(cImageFile)
#define	CD_APPLET_DRAW_EMBLEM_ON_MY_ICON(pEmblem)
#define	CD_APPLET_ADD_DATA_RENDERER_ON_MY_ICON(pAttr)
#define	CD_APPLET_RELOAD_MY_DATA_RENDERER(pAttr)
#define	CD_APPLET_RENDER_NEW_DATA_ON_MY_ICON(pValues)
#define	CD_APPLET_REMOVE_MY_DATA_RENDERER
#define	CD_APPLET_REFRESH_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, CairoContainer *pContainer)
void	cairo_dock_draw_bar_on_icon (cairo_t *pIconContext, double fValue, Icon *pIcon)
void	cairo_dock_set_icon_surface_with_reflect (cairo_t *pIconContext, cairo_surface_t *pSurface, Icon *pIcon, CairoContainer *pContainer)
gboolean	cairo_dock_set_image_on_icon (cairo_t *pIconContext, const gchar *cIconName, Icon *pIcon, CairoContainer *pContainer)
void	cairo_dock_set_image_on_icon_with_default (cairo_t *pIconContext, const gchar *cImage, Icon *pIcon, CairoContainer *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.

---

Define Documentation

#define cairo_dock_set_icon_surface	(		pIconContext,
			pSurface
	)

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.

#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_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	(		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_RVB_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_RVB	(		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_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).

#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_CREATE_MY_SUB_MENU

(

...

)

Create and add the default sub-menu of an applet to the main menu. This sub-menu is named according to the name of the applet, and is represented by the default icon of the applet.

Returns:

the sub-menu, newly created and attached to the main 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_ADD_ABOUT_IN_MENU

(

pMenu

)

Create and add an entry to a menu for the 'about' function.

Parameters:

pMenu

menu to add the entry to.

#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_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_UPDATE_REFLECT_ON_MY_ICON

Reload the reflect of the applet's icon (do nothing in OpenGL mode).

#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_SURFACE_ON_MY_ICON_WITH_ZOOM	(		pSurface,
			fScale
	)

Apply a surface on the applet's icon, with a zoom factor and centered, and redraw it.

Parameters:

pSurface	the surface to draw on your icon.
fScale	zoom factor (at 1 the surface will fill all the icon).

#define CD_APPLET_SET_SURFACE_ON_MY_ICON_WITH_ALPHA	(		pSurface,
			fAlpha
	)

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

Parameters:

pSurface	the surface to draw on your icon.
fAlpha	transparency (in [0,1]).

#define CD_APPLET_SET_SURFACE_ON_MY_ICON_WITH_BAR	(		pSurface,
			fValue
	)

Apply a surface on the applet's icon with add a bar at the bottom, and redraw it. The bar is drawn at the bottom of the icon with a gradation from red to green and a given length.

Parameters:

pSurface	the surface to draw on your icon.
fValue	the value representing a percentage, in [-1,1]. If negative, the gradation is inverted, and the absolute value is used.

#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_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_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_FINISH_DRAWING_MY_ICON

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

#define CD_APPLET_ADD_OVERLAY	(		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:

TRUE if the overlay has been successfuly added.

#define CD_APPLET_REMOVE_OVERLAY

(

iPosition

)

Remove an overlay the applet's icon, given its position (there is only one overlay at a given position).

Parameters:

iPosition

position of the overlay

#define CD_APPLET_MAKE_EMBLEM

(

cImageFile

)

Make an emblem from an image. If the image is given by its sole name, it is looked up inside the root theme folder. Free it with cairo_dock_free_emblem.

Parameters:

cImageFile

name of an image file.

Returns:

a newly allocated CairoEmblem.

#define CD_APPLET_DRAW_EMBLEM_ON_MY_ICON

(

pEmblem

)

Draw an emblem on the applet's icon. The emblem is drawn directly on the icon, and is erased if the icon is redrawn.

Parameters:

pEmblem

an emblem.

#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

(

pAttr

)

Reload the Data Renderer of the applet's icon. Pass NULL as the attributes to simply reload the current data renderer without changing any of its parameters. Previous values are kept.

Parameters:

pAttr

the attributes of the Data Renderer, or NULL to simply reload the Data Renderer as it it.

#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_REFRESH_MY_DATA_RENDERER

Refresh the Data Renderer of the applet's icon, to redraw it when the applet's size has changed.

#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,
		CairoContainer *	pContainer
	)

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 fastor.
fAlpha	transparency in [0,1].
pIcon	the icon.
pContainer	the container of the icon.

void cairo_dock_draw_bar_on_icon	(	cairo_t *	pIconContext,
		double	fValue,
		Icon *	pIcon
	)

Draw a bar at the bottom of an Icon, with a gradation from red to green and a given length.

Parameters:

pIconContext	the drawing context; is not altered by the function.
fValue	the value representing a percentage, in [-1,1]. if negative, the gradation is inverted, and the absolute value is used.
pIcon	the icon.

void cairo_dock_set_icon_surface_with_reflect	(	cairo_t *	pIconContext,
		cairo_surface_t *	pSurface,
		Icon *	pIcon,
		CairoContainer *	pContainer
	)

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

Parameters:

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

gboolean cairo_dock_set_image_on_icon	(	cairo_t *	pIconContext,
		const gchar *	cIconName,
		Icon *	pIcon,
		CairoContainer *	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.
cImagePath	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,
		CairoContainer *	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.