cairo-dock-overlay.h File Reference

Enumerations
enum	CairoOverlayPosition
	Available position of an overlay on an icon.
Functions
gboolean	cairo_dock_add_overlay_from_image (Icon *pIcon, const gchar *cImageFile, CairoOverlayPosition iPosition)
void	cairo_dock_add_overlay_from_surface (Icon *pIcon, cairo_surface_t *pSurface, int iWidth, int iHeight, CairoOverlayPosition iPosition)
void	cairo_dock_remove_overlay_at_position (Icon *pIcon, CairoOverlayPosition iPosition)
CairoDockImageBuffer *	cairo_dock_get_overlay_buffer_at_position (Icon *pIcon, CairoOverlayPosition iPosition)
void	cairo_dock_print_overlay_on_icon (Icon *pIcon, CairoContainer *pContainer, const gchar *cImageFile, CairoOverlayPosition iPosition)

---

Detailed Description

This class defines Overlays, that are small images superimposed on the icon at a given position. This means that overlays can be added/removed without modifying the icon's surface/texture, and they will remain even if you erase the icon's surface/texture. Only one overlay can exist 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. To remove an overlay, use cairo_dock_remove_overlay_at_position. If you need to modify an overlay directly, you can get its image buffer with cairo_dock_get_overlay_buffer_at_position. 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. This can avoid to draw it at each refresh.

---

Function Documentation

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

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:

TRUE if the overlay has been successfuly added.

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

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

void cairo_dock_remove_overlay_at_position	(	Icon *	pIcon,
		CairoOverlayPosition	iPosition
	)

Remove an overlay on an icon, given its position (there is only one overlay at a given position).

Parameters:

pIcon	the icon
iPosition	position of the overlay

CairoDockImageBuffer* cairo_dock_get_overlay_buffer_at_position	(	Icon *	pIcon,
		CairoOverlayPosition	iPosition
	)

Get the image buffer of an overlay, given its position (there is only one overlay at a given position).

Parameters:

pIcon	the icon
iPosition	position of the overlay

Returns:

the image-buffer of the overlay, or NULL if there is no overlay at this position.

void cairo_dock_print_overlay_on_icon	(	Icon *	pIcon,
		CairoContainer *	pContainer,
		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 an image).

Parameters:

pIcon	the icon
pContainer	container of 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