cairo-dock-overlay.h File Reference

Data Structures
struct	_CairoOverlay
	Definition of an Icon Overlay. More...

Macros
#define	cairo_dock_set_overlay_scale(pOverlay, _fScale)
#define	cairo_dock_get_overlay_image_buffer(pOverlay)

Enumerations
enum	CairoOverlayPosition
	Available position of an overlay on an icon.

Functions
CairoOverlay *	cairo_dock_add_overlay_from_image (Icon *pIcon, const gchar *cImageFile, CairoOverlayPosition iPosition, gpointer data)
CairoOverlay *	cairo_dock_add_overlay_from_surface (Icon *pIcon, cairo_surface_t *pSurface, int iWidth, int iHeight, CairoOverlayPosition iPosition, gpointer data)
CairoOverlay *	cairo_dock_add_overlay_from_texture (Icon *pIcon, GLuint iTexture, CairoOverlayPosition iPosition, gpointer data)
void	cairo_dock_remove_overlay_at_position (Icon *pIcon, CairoOverlayPosition iPosition, gpointer data)
gboolean	cairo_dock_print_overlay_on_icon_from_image (Icon *pIcon, const gchar *cImageFile, CairoOverlayPosition iPosition)
void	cairo_dock_print_overlay_on_icon_from_surface (Icon *pIcon, cairo_surface_t *pSurface, int iWidth, int iHeight, CairoOverlayPosition iPosition)

Detailed Description

This class defines Overlays, that are small images superimposed on the icon at a given position.

To add an overlay to an icon, use cairo_dock_add_overlay_from_image or cairo_dock_add_overlay_from_surface. The overlay can then be removed from the icon by simply destroying it with gldi_object_unref

A common feature is to have only 1 overlay at a given position. This can be achieved by passing a non-NULL data to the creation functions. This data will identify all of your overlays. You can then remove an overlay simply from its position with cairo_dock_remove_overlay_at_position, and adding an overlay at a position will automatically remove any previous overlay at this position with the same data.

If you're never going to update nor remove an overlay, you can choose to print it directly onto the icon with cairo_dock_print_overlay_on_icon_from_image or cairo_dock_print_overlay_on_icon_from_surface, which is slightly faster.

Overlays are drawn at 1/2 of the icon size by default, but this can be set up with cairo_dock_set_overlay_scale. If you need to modify an overlay directly, you can get its image buffer with cairo_dock_get_overlay_image_buffer.

Macro Definition Documentation

#define cairo_dock_set_overlay_scale	(		pOverlay,
			_fScale
	)

Set the scale of an overlay; by default it's 0.5

Parameters

pOverlay	the overlay
_fScale	the scale

#define cairo_dock_get_overlay_image_buffer

(

pOverlay

)

Get the image buffer of an overlay (only useful if you need to redraw the overlay).

Parameters

pOverlay

the overlay

Function Documentation

CairoOverlay* cairo_dock_add_overlay_from_image	(	Icon *	pIcon,
		const gchar *	cImageFile,
		CairoOverlayPosition	iPosition,
		gpointer	data
	)

Add an overlay on an icon from an image.

Parameters

pIcon	the icon
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.

Parameters

data	data that will be used to look for the overlay in cairo_dock_remove_overlay_at_position; if NULL, then this function can't be used

CairoOverlay* cairo_dock_add_overlay_from_surface	(	Icon *	pIcon,
		cairo_surface_t *	pSurface,
		int	iWidth,
		int	iHeight,
		CairoOverlayPosition	iPosition,
		gpointer	data
	)

Add an overlay on an icon from a surface.

Parameters

pIcon	the icon
pSurface	a cairo surface
iWidth	width of the surface
iHeight	height of the surface
iPosition	position where to display the overlay
data	data that will be used to look for the overlay in cairo_dock_remove_overlay_at_position; if NULL, then this function can't be used

Returns

the overlay.

CairoOverlay* cairo_dock_add_overlay_from_texture	(	Icon *	pIcon,
		GLuint	iTexture,
		CairoOverlayPosition	iPosition,
		gpointer	data
	)

Add an overlay on an icon from a texture.

Parameters

pIcon	the icon
iTexture	a texture
iPosition	position where to display the overlay
data	data that will be used to look for the overlay in cairo_dock_remove_overlay_at_position; if NULL, then this function can't be used

Returns

the overlay.

void cairo_dock_remove_overlay_at_position	(	Icon *	pIcon,
		CairoOverlayPosition	iPosition,
		gpointer	data
	)

Remove an overlay from an icon, given its position and data.

Parameters

pIcon	the icon
iPosition	the position of the overlay
data	data that was set on the overlay when created; a NULL pointer is not valid.

gboolean cairo_dock_print_overlay_on_icon_from_image	(	Icon *	pIcon,
		const gchar *	cImageFile,
		CairoOverlayPosition	iPosition
	)

Print an overlay onto an icon from an image at a given position. You can't remove/modify the overlay then. The overlay will be displayed until you modify the icon directly (for instance by setting a new image).

Parameters

pIcon	the icon
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.

void cairo_dock_print_overlay_on_icon_from_surface	(	Icon *	pIcon,
		cairo_surface_t *	pSurface,
		int	iWidth,
		int	iHeight,
		CairoOverlayPosition	iPosition
	)

Print an overlay onto an icon from a surface at a given position. You can't remove/modify the overlay then. The overlay will be displayed until you modify the icon directly (for instance by setting a new image).

Parameters

pIcon	the icon
pSurface	a cairo surface
iWidth	width of the surface
iHeight	height of the surface
iPosition	position where to display the overlay

Returns

TRUE if the overlay has been successfuly printed.