Defines
#define	cairo_dock_remove_dialog_if_any(icon)
Enumerations
enum	CairoDialogNotifications { NOTIFICATION_UPDATE_DIALOG, NOTIFICATION_UPDATE_DIALOG_SLOW, NOTIFICATION_RENDER_DIALOG }
	signals More...
Functions
gboolean	cairo_dock_dialog_reference (CairoDialog *pDialog)
gboolean	cairo_dock_dialog_unreference (CairoDialog *pDialog)
gboolean	cairo_dock_remove_dialog_if_any_full (Icon *icon, gboolean bAll)
CairoDialog *	cairo_dock_build_dialog (CairoDialogAttribute pAttribute, Icon pIcon, CairoContainer *pContainer)
CairoDialog *	cairo_dock_show_dialog_full (const gchar cText, Icon pIcon, CairoContainer pContainer, double fTimeLength, const gchar cIconPath, GtkWidget *pInteractiveWidget, CairoDockActionOnAnswerFunc pActionFunc, gpointer data, GFreeFunc pFreeDataFunc)
CairoDialog *	cairo_dock_show_temporary_dialog_with_icon_printf (const gchar cText, Icon pIcon, CairoContainer pContainer, double fTimeLength, const gchar cIconPath,...) G_GNUC_PRINTF(1
CairoDialog *CairoDialog	cairo_dock_show_temporary_dialog_with_icon (const gchar cText, Icon pIcon, CairoContainer pContainer, double fTimeLength, const gchar cIconPath)
CairoDialog *	cairo_dock_show_temporary_dialog (const gchar cText, Icon pIcon, CairoContainer *pContainer, double fTimeLength)
CairoDialog *	cairo_dock_show_temporary_dialog_with_default_icon (const gchar cText, Icon pIcon, CairoContainer *pContainer, double fTimeLength)
CairoDialog *	cairo_dock_show_dialog_with_question (const gchar cText, Icon pIcon, CairoContainer pContainer, const gchar cIconPath, CairoDockActionOnAnswerFunc pActionFunc, gpointer data, GFreeFunc pFreeDataFunc)
CairoDialog *	cairo_dock_show_dialog_with_entry (const gchar cText, Icon pIcon, CairoContainer pContainer, const gchar cIconPath, const gchar *cTextForEntry, CairoDockActionOnAnswerFunc pActionFunc, gpointer data, GFreeFunc pFreeDataFunc)
CairoDialog *	cairo_dock_show_dialog_with_value (const gchar cText, Icon pIcon, CairoContainer pContainer, const gchar cIconPath, double fValue, double fMaxValue, CairoDockActionOnAnswerFunc pActionFunc, gpointer data, GFreeFunc pFreeDataFunc)
int	cairo_dock_show_dialog_and_wait (const gchar cText, Icon pIcon, CairoContainer pContainer, double fTimeLength, const gchar cIconPath, GtkWidget *pInteractiveWidget)
gchar *	cairo_dock_show_demand_and_wait (const gchar cMessage, Icon pIcon, CairoContainer pContainer, const gchar cInitialAnswer)
double	cairo_dock_show_value_and_wait (const gchar cMessage, Icon pIcon, CairoContainer *pContainer, double fInitialValue, double fMaxValue)
int	cairo_dock_ask_question_and_wait (const gchar cQuestion, Icon pIcon, CairoContainer *pContainer)
gboolean	cairo_dock_icon_has_dialog (Icon *pIcon)
Icon *	cairo_dock_get_dialogless_icon_full (CairoDock *pDock)
CairoDialog *	cairo_dock_show_general_message (const gchar *cMessage, double fTimeLength)
int	cairo_dock_ask_general_question_and_wait (const gchar *cQuestion)
void	cairo_dock_hide_dialog (CairoDialog *pDialog)
void	cairo_dock_unhide_dialog (CairoDialog *pDialog)
void	cairo_dock_toggle_dialog_visibility (CairoDialog *pDialog)

Detailed Description

This class manages the Dialogs, that are useful to bring interaction with the user.

With dialogs, you can pop-up messages, ask for question, etc. Any GTK widget can be embedded inside a dialog, giving you any possible interaction with the user.

Dialogs are constructed with a set of attributes grouped inside a _CairoDialogAttribute. See cairo-dock-dialog-factory.h for the list of available attributes.

The most generic way to build a Dialog is to fill a _CairoDialogAttribute and pass it to cairo_dock_build_dialog.

But in most of case, you can just use one of the following convenient functions, that will do the job for you.

to show a message, you can use cairo_dock_show_temporary_dialog_with_icon
to ask the user a choice, a value or a text, you can use cairo_dock_show_dialog_with_question, cairo_dock_show_dialog_with_value or cairo_dock_show_dialog_with_entry.
if you need to block while waiting for the user, use the xxx_and_wait version of these functions.
if you want to pop up only 1 dialog at once on a given icon, use cairo_dock_remove_dialog_if_any before you pop up your dialog.

Define Documentation

#define cairo_dock_remove_dialog_if_any ( icon )

Unreference all the dialogs pointing on an icon.

Parameters:

icon	the icon you want to delete all dialogs from.

Returns:: TRUE if at least one dialog has been unreferenced.

Enumeration Type Documentation

enum CairoDialogNotifications

signals

Enumerator:

NOTIFICATION_UPDATE_DIALOG	notification called when a Dialog is updated in the fast rendering loop.
NOTIFICATION_UPDATE_DIALOG_SLOW	notification called when a Dialog is updated in the slow rendering loop.
NOTIFICATION_RENDER_DIALOG	notification called when a Dialog is rendered.

Function Documentation

gboolean cairo_dock_dialog_reference ( CairoDialog * pDialog )

Increase by 1 the reference of a dialog. Use cairo_dock_dialog_unreference when you're done, so that the dialog can be destroyed.

Parameters:

pDialog the dialog.

Returns:: TRUE if the reference was not nul, otherwise you must not use it.

gboolean cairo_dock_dialog_unreference ( CairoDialog * pDialog )

Decrease by 1 the reference of a dialog. If the reference becomes nul, the dialog is destroyed.

Parameters:

pDialog the dialog.

Returns:: TRUE if the reference became nul, in which case the dialog must not be used anymore.

gboolean cairo_dock_remove_dialog_if_any_full	(	Icon *	icon,
		gboolean	bAll
	)

Unreference the dialogs pointing on an icon.

Parameters:

icon	the icon you want to delete all dialogs from.
bAll	whether all dialogs should be removed or only the one that don't have interaction with the user.

Returns:: TRUE if at least one dialog has been unreferenced.

CairoDialog* cairo_dock_build_dialog	(	CairoDialogAttribute *	pAttribute,
		Icon *	pIcon,
		CairoContainer *	pContainer
	)

Generic function to pop up a dialog.

Parameters:

pAttribute	attributes of the dialog.
pIcon	the icon that will hold the dialog.
pContainer	the container of the icon.

Returns:: a newly created dialog, visible, with a reference of 1.

CairoDialog* cairo_dock_show_dialog_full	(	const gchar *	cText,
		Icon *	pIcon,
		CairoContainer *	pContainer,
		double	fTimeLength,
		const gchar *	cIconPath,
		GtkWidget *	pInteractiveWidget,
		CairoDockActionOnAnswerFunc	pActionFunc,
		gpointer	data,
		GFreeFunc	pFreeDataFunc
	)

Pop up a dialog with a message, a widget, 2 buttons ok/cancel and an icon, all optionnal.

Parameters:

cText	the message to display.
pIcon	the icon that will hold the dialog.
pContainer	the container of the icon.
fTimeLength	the duration of the dialog (in ms), or 0 for an unlimited dialog.
cIconPath	path to an icon to display in the margin.
pInteractiveWidget	a GTK widget; It is destroyed with the dialog. Use 'gtk_widget_reparent()' before if you want to keep it alive, or use cairo_dock_show_dialog_and_wait.
pActionFunc	the callback called when the user makes its choice. NULL means there will be no buttons.
data	data passed as a parameter of the callback.
pFreeDataFunc	function used to free the data when the dialog is destroyed, or NULL if unnecessary.

Returns:: the newly created dialog, visible, with a reference of 1.

CairoDialog* cairo_dock_show_temporary_dialog_with_icon_printf	(	const gchar *	cText,
		Icon *	pIcon,
		CairoContainer *	pContainer,
		double	fTimeLength,
		const gchar *	cIconPath,
			...
	)

Pop up a dialog with a message, and a limited duration, and an icon in the margin.

Parameters:

cText	the message to display.
pIcon	the icon that will hold the dialog.
pContainer	the container of the icon.
fTimeLength	the duration of the dialog (in ms), or 0 for an unlimited dialog.
cIconPath	path to an icon.
...	arguments to insert in the message, in a printf way.

Returns:: the newly created dialog, visible, with a reference of 1.

CairoDialog* CairoDialog cairo_dock_show_temporary_dialog_with_icon	(	const gchar *	cText,
		Icon *	pIcon,
		CairoContainer *	pContainer,
		double	fTimeLength,
		const gchar *	cIconPath
	)

Pop up a dialog with a message, and a limited duration, and an icon in the margin.

Parameters:

cText	the message to display.
pIcon	the icon that will hold the dialog.
pContainer	the container of the icon.
fTimeLength	the duration of the dialog (in ms), or 0 for an unlimited dialog.
cIconPath	path to an icon.

Returns:: the newly created dialog, visible, with a reference of 1.

CairoDialog* cairo_dock_show_temporary_dialog	(	const gchar *	cText,
		Icon *	pIcon,
		CairoContainer *	pContainer,
		double	fTimeLength
	)

Pop up a dialog with a message, and a limited duration, with no icon.

Parameters:

cText	the message to display.
pIcon	the icon that will hold the dialog.
pContainer	the container of the icon.
fTimeLength	the duration of the dialog (in ms), or 0 for an unlimited dialog.

Returns:: the newly created dialog, visible, with a reference of 1 et visible, avec une reference a 1.

CairoDialog* cairo_dock_show_temporary_dialog_with_default_icon	(	const gchar *	cText,
		Icon *	pIcon,
		CairoContainer *	pContainer,
		double	fTimeLength
	)

Pop up a dialog with a message, and a limited duration, and a default icon.

Parameters:

cText	the format of the message to display.
pIcon	the icon that will hold the dialog.
pContainer	the container of the icon.
fTimeLength	the duration of the dialog (in ms), or 0 for an unlimited dialog.

Returns:: the newly created dialog, visible, with a reference of 1 et visible, avec une reference a 1.

CairoDialog* cairo_dock_show_dialog_with_question	(	const gchar *	cText,
		Icon *	pIcon,
		CairoContainer *	pContainer,
		const gchar *	cIconPath,
		CairoDockActionOnAnswerFunc	pActionFunc,
		gpointer	data,
		GFreeFunc	pFreeDataFunc
	)

Pop up a dialog with a question and 2 buttons ok/cancel. The dialog is unreferenced after the user has answered, so if you want to keep it alive, you have to reference it in the callback.

Parameters:

cText	the message to display.
pIcon	the icon that will hold the dialog.
pContainer	the container of the icon.
cIconPath	path to an icon to display in the margin.
pActionFunc	the callback.
data	data passed as a parameter of the callback.
pFreeDataFunc	function used to free the data.

Returns:: the newly created dialog, visible, with a reference of 1 et visible, avec une reference a 1.

CairoDialog* cairo_dock_show_dialog_with_entry	(	const gchar *	cText,
		Icon *	pIcon,
		CairoContainer *	pContainer,
		const gchar *	cIconPath,
		const gchar *	cTextForEntry,
		CairoDockActionOnAnswerFunc	pActionFunc,
		gpointer	data,
		GFreeFunc	pFreeDataFunc
	)

Pop up a dialog with a text entry and 2 buttons ok/cancel. The dialog is unreferenced after the user has answered, so if you want to keep it alive, you have to reference it in the callback.

Parameters:

cText	the message to display.
pIcon	the icon that will hold the dialog.
pContainer	the container of the icon.
cIconPath	path to an icon to display in the margin.
cTextForEntry	text to display initially in the entry.
pActionFunc	the callback.
data	data passed as a parameter of the callback.
pFreeDataFunc	function used to free the data.

Returns:: the newly created dialog, visible, with a reference of 1.

CairoDialog* cairo_dock_show_dialog_with_value	(	const gchar *	cText,
		Icon *	pIcon,
		CairoContainer *	pContainer,
		const gchar *	cIconPath,
		double	fValue,
		double	fMaxValue,
		CairoDockActionOnAnswerFunc	pActionFunc,
		gpointer	data,
		GFreeFunc	pFreeDataFunc
	)

Pop up a dialog with an horizontal scale between 0 and fMaxValue and 2 buttons ok/cancel. The dialog is unreferenced after the user has answered, so if you want to keep it alive, you have to reference it in the callback.

Parameters:

cText	the message to display.
pIcon	the icon that will hold the dialog.
pContainer	the container of the icon.
cIconPath	path to an icon to display in the margin.
fValue	initial value of the scale.
fMaxValue	maximum value of the scale.
pActionFunc	the callback.
data	data passed as a parameter of the callback.
pFreeDataFunc	function used to free the data.

Returns:: the newly created dialog, visible, with a reference of 1.

int cairo_dock_show_dialog_and_wait	(	const gchar *	cText,
		Icon *	pIcon,
		CairoContainer *	pContainer,
		double	fTimeLength,
		const gchar *	cIconPath,
		GtkWidget *	pInteractiveWidget
	)

Pop up a dialog with GTK widget and 2 buttons ok/cancel, and block until the user makes its choice.

Parameters:

cText	the message to display.
pIcon	the icon that will hold the dialog.
pContainer	the container of the icon.
fTimeLength	time length of the dialog, or 0 for an unlimited dialog.
cIconPath	path to an icon to display in the margin.
pInteractiveWidget	an interactive widget.

Returns:: the number of the button that was clicked : 0 or -1 for OK, 1 or -2 for CANCEL, -3 if the dialog has been destroyed before. The dialog is destroyed after the user choosed, but the interactive widget is not destroyed, which allows to retrieve the changes made by the user. Destroy it with 'gtk_widget_destroy' when you're done with it.

gchar* cairo_dock_show_demand_and_wait	(	const gchar *	cMessage,
		Icon *	pIcon,
		CairoContainer *	pContainer,
		const gchar *	cInitialAnswer
	)

Pop up a dialog with a text entry, and 2 buttons ok/cancel, and block until the user makes its choice.

Parameters:

cMessage	the message to display.
pIcon	the icon that will hold the dialog.
pContainer	the container of the icon.
cInitialAnswer	the initial value of the entry (can be NULL).

Returns:: the text entered by the user, or NULL if he cancelled or if the dialog has been destroyed before.

double cairo_dock_show_value_and_wait	(	const gchar *	cMessage,
		Icon *	pIcon,
		CairoContainer *	pContainer,
		double	fInitialValue,
		double	fMaxValue
	)

Pop up a dialog with an horizontal scale between 0 and fMaxValue, and 2 buttons ok/cancel, and block until the user makes its choice.

Parameters:

cMessage	the message to display.
pIcon	the icon that will hold the dialog.
pContainer	the container of the icon.
fInitialValue	the initial value of the scale.
fMaxValue	the maximum value of the scale.

Returns:: the value choosed by the user, or -1 if he cancelled or if the dialog has been destroyed before.

int cairo_dock_ask_question_and_wait	(	const gchar *	cQuestion,
		Icon *	pIcon,
		CairoContainer *	pContainer
	)

Pop up a dialog with a question and 2 buttons yes/no, and block until the user makes its choice.

Parameters:

cQuestion	the question to ask.
pIcon	the icon that will hold the dialog.
pContainer	the container of the icon.

Returns:: GTK_RESPONSE_YES ou GTK_RESPONSE_NO according to the user's choice, or GTK_RESPONSE_NONE if the dialog has been destroyed before.

gboolean cairo_dock_icon_has_dialog ( Icon * pIcon )

Test if an icon has at least one dialog.

Parameters:

pIcon the icon.

Returns:: TRUE if the icon has one or more dialog(s).

Icon* cairo_dock_get_dialogless_icon_full ( CairoDock * pDock )

Search the "the best icon possible" for a Dock to hold a general dialog.

Parameters:

pDock a dock (NULL to search inside the main dock).

Returns:: an Icon, or NULL if the dock is empty.

CairoDialog* cairo_dock_show_general_message	(	const gchar *	cMessage,
		double	fTimeLength
	)

Pop up a dialog, pointing on "the best icon possible". This allows to display a general message.

Parameters:

cMessage	the message.
fTimeLength	life time of the dialog, in ms.

Returns:: the newly created dialog, visible and with a reference of 1.

int cairo_dock_ask_general_question_and_wait ( const gchar * cQuestion )

Pop up a dialog, pointing on "the best icon possible", and wait. This allows to display a general message.

Parameters:

cQuestion the message.

Returns:: GTK_RESPONSE_YES ou GTK_RESPONSE_NO according to the user's choice, or GTK_RESPONSE_NONE if the dialog has been destroyed before.

void cairo_dock_hide_dialog ( CairoDialog * pDialog )

Hide a dialog.

Parameters:

pDialog the dialog.

void cairo_dock_unhide_dialog ( CairoDialog * pDialog )

Show a dialog and give it focus.

Parameters:

pDialog the dialog.

void cairo_dock_toggle_dialog_visibility ( CairoDialog * pDialog )

Toggle the visibility of a dialog.

Parameters:

pDialog the dialog.

Defines

Enumerations

Functions

Detailed Description

Define Documentation

Enumeration Type Documentation

Function Documentation