From d2370d354e567edddc529a627b01bbd4672c5477 Mon Sep 17 00:00:00 2001 From: joncruz Date: Mon, 23 Apr 2007 18:30:34 +0000 Subject: [PATCH] Doc updates --- src/ege-adjustment-action.h | 66 ++++++++++++++++++++++++++- src/ege-output-action.h | 37 +++++++++++++++ src/ege-select-one-action.h | 91 +++++++++++++++++++++++++++++++++++++ 3 files changed, 192 insertions(+), 2 deletions(-) diff --git a/src/ege-adjustment-action.h b/src/ege-adjustment-action.h index 7462448ff..0fa896879 100644 --- a/src/ege-adjustment-action.h +++ b/src/ege-adjustment-action.h @@ -39,6 +39,10 @@ * * ***** END LICENSE BLOCK ***** */ +/** \file + * GtkAction subclass that represents a GtkAdjustment value. + */ + /* Note: this file should be kept compilable as both .cpp and .c */ #include @@ -59,34 +63,92 @@ typedef struct _EgeAdjustmentAction EgeAdjustmentAction; typedef struct _EgeAdjustmentActionClass EgeAdjustmentActionClass; typedef struct _EgeAdjustmentActionPrivate EgeAdjustmentActionPrivate; +/** + * Instance structure of EgeAdjustmentAction. + */ struct _EgeAdjustmentAction { + /** Parent instance structure. */ GtkAction action; + + /** Pointer to private instance data. */ EgeAdjustmentActionPrivate *private_data; }; +/** + * Class structure of EgeAdjustmentAction. + */ struct _EgeAdjustmentActionClass { + /** Parent class structure. */ GtkActionClass parent_class; }; +/** Standard Gtk type function */ GType ege_adjustment_action_get_type( void ); +/** + * Creates a new EgeAdjustmentAction instance. + * This is a GtkAction subclass that manages a value stored in a + * GtkAdjustment. + * + * @param adjustment The GtkAdjustment to manage. + * @param name Functional name for the action. + * @param label Display label for the action. + * @param tooltip Tooltip for the action. + * @param stock_id Icon id to use. + * @param climb_rate Used for created widgets. + * @param digits Used for created widgets. + */ EgeAdjustmentAction* ege_adjustment_action_new( GtkAdjustment* adjustment, const gchar *name, const gchar *label, const gchar *tooltip, const gchar *stock_id, gdouble climb_rate, - guint digits ); - + guint digits + ); +/** + * Returns a pointer to the GtkAdjustment represented by the given + * EgeAdjustmentAction. + * + * @param action The action to fetch the GtkAdjustment for. + */ GtkAdjustment* ege_adjustment_action_get_adjustment( EgeAdjustmentAction* action ); +/** + * Sets the GtkWidget to return focus to. + * This is used to be able to transfer focus back out of a toolbar. + * + * @param action The action to set the widget for. + * @param widget The widget to return focus to after editing. + * @see ege_adjustment_action_get_focuswidget + */ void ege_adjustment_action_set_focuswidget( EgeAdjustmentAction* action, GtkWidget* widget ); + +/** + * Returns a pointer to the GtkWidget to return focus to after changing + * the value. + * + * @param action The action to fetch the focus widget for. + * @returns A pointer to the widget to return focus to, NULL if none set. + * @see ege_adjustment_action_set_focuswidget + */ GtkWidget* ege_adjustment_action_get_focuswidget( EgeAdjustmentAction* action ); +/** + * Set a list of values with labels to explicitly include in menus. + * + * @param action The action to set explicit entries for. + * @param descriptions Array of descriptions to include. + * Descriptions will be matched one-for-one with numbers in the 'values' array. + * @param values Array of values to include. + * Values will be matched one-for-one with numbers in the 'descriptions' array. + * @param count Number of items in the 'descriptions' and 'values' arrays. + */ void ege_adjustment_action_set_descriptions( EgeAdjustmentAction* action, gchar const** descriptions, gdouble const* values, guint count ); +/** Callback type for post-creation 'fixup' pass on generated widgets */ typedef void (*EgeWidgetFixup)(GtkWidget *widget); diff --git a/src/ege-output-action.h b/src/ege-output-action.h index 4a8b47b12..e626ccd8c 100644 --- a/src/ege-output-action.h +++ b/src/ege-output-action.h @@ -39,6 +39,10 @@ * * ***** END LICENSE BLOCK ***** */ +/** \file + * GtkAction subclass that represents a string for output. + */ + /* Note: this file should be kept compilable as both .cpp and .c */ #include @@ -59,25 +63,58 @@ typedef struct _EgeOutputAction EgeOutputAction; typedef struct _EgeOutputActionClass EgeOutputActionClass; typedef struct _EgeOutputActionPrivate EgeOutputActionPrivate; +/** + * Instance structure of EgeOutputAction. + */ struct _EgeOutputAction { + /** Parent instance structure. */ GtkAction action; + + /** Pointer to private instance data. */ EgeOutputActionPrivate *private_data; }; +/** + * Class structure of EgeOutputAction. + */ struct _EgeOutputActionClass { + /** Parent class structure. */ GtkActionClass parent_class; }; +/** Standard Gtk type function */ GType ege_output_action_get_type( void ); +/** + * Creates a new EgeOutputAction instance. + * This is a GtkAction subclass that displays a string. + * + * @param name Functional name for the action. + * @param label Display label for the action. + * @param tooltip Tooltip for the action. + * @param stock_id Icon id to use. + */ EgeOutputAction* ege_output_action_new( const gchar *name, const gchar *label, const gchar *tooltip, const gchar *stock_id ); +/** + * Return whether or not the displayed text is interpreted as markup. + * + * @param action The action to fetch the markup state for. + * @return True if the text is to be interpreted as markup, false otherwise. + */ gboolean ege_output_action_get_use_markup( EgeOutputAction* action ); + +/** + * Sets whether or not the displayed text is interpreted as markup. + * + * @param action The action to set the markup state for. + * @param setting True if the text is to be interpreted as markup, false otherwise. + */ void ege_output_action_set_use_markup( EgeOutputAction* action, gboolean setting ); G_END_DECLS diff --git a/src/ege-select-one-action.h b/src/ege-select-one-action.h index 787a2c171..f3da195d1 100644 --- a/src/ege-select-one-action.h +++ b/src/ege-select-one-action.h @@ -39,6 +39,13 @@ * * ***** END LICENSE BLOCK ***** */ +/** \file + * GtkAction subclass that represents a set of values the user may select + * one from at a given time. + * This can manifest as a popup menu, a ComboBox, a set of toggle buttons, + * etc. + */ + /* Note: this file should be kept compilable as both .cpp and .c */ #include @@ -60,38 +67,122 @@ typedef struct _EgeSelectOneAction EgeSelectOneAction; typedef struct _EgeSelectOneActionClass EgeSelectOneActionClass; typedef struct _EgeSelectOneActionPrivate EgeSelectOneActionPrivate; +/** + * Instance structure of EgeSelectOneAction. + */ struct _EgeSelectOneAction { + /** Parent instance structure. */ GtkAction action; + + /** Pointer to private instance data. */ EgeSelectOneActionPrivate *private_data; }; +/** + * Class structure of EgeSelectOneAction. + */ struct _EgeSelectOneActionClass { + /** Parent class structure. */ GtkActionClass parent_class; + void (*changed) (EgeSelectOneAction* action); }; +/** Standard Gtk type function */ GType ege_select_one_action_get_type( void ); +/** + * Creates a new EgeSelectOneAction instance. + * This is a GtkAction subclass that represents a set of values the user + * may select one from at a given time. + * This can manifest as a popup menu, a ComboBox, a set of toggle buttons, + * etc. + * + * @param name Functional name for the action. + * @param label Display label for the action. + * @param tooltip Tooltip for the action. + * @param stock_id Icon id to use. + * @param model the source of choices to present. + */ EgeSelectOneAction* ege_select_one_action_new( const gchar *name, const gchar *label, const gchar *tooltip, const gchar *stock_id, GtkTreeModel* model ); +/** + * Returns the index of the currently selected item. + * + * @param action The action to fetch the selected index for. + */ gint ege_select_one_action_get_active( EgeSelectOneAction* action ); + +/** + * Sets the currently selected item. + * + * @param action The action to fetch the selected index for. + * @param val index of the item to make selected. + */ void ege_select_one_action_set_active( EgeSelectOneAction* action, gint val ); + +/** + * Returns the column used for the display label. + * + * @param action The action to fetch the label column for. + */ gint ege_select_one_action_get_label_column( EgeSelectOneAction* action ); + +/** + * Sets the column used for the display label. + * + * @param action The action to set the label column for. + * @param col column to use. + */ void ege_select_one_action_set_label_column( EgeSelectOneAction* action, gint col ); + +/** + * Returns the column used for the display icon. + * + * @param action The action to fetch the icon column for. + */ gint ege_select_one_action_get_icon_column( EgeSelectOneAction* action ); + +/** + * Sets the column used for the display icon. + * + * @param action The action to set the icon column for. + * @param col column to use. + */ void ege_select_one_action_set_icon_column( EgeSelectOneAction* action, gint col ); + +/** + * Returns the column used for the tooltip. + * + * @param action The action to fetch the tooltip column for. + */ gint ege_select_one_action_get_tooltip_column( EgeSelectOneAction* action ); + +/** + * Sets the column used for the tooltip. + * + * @param action The action to set the tooltip column for. + * @param col column to use. + */ void ege_select_one_action_set_tooltip_column( EgeSelectOneAction* action, gint col ); + +/** + * Sets a hint to be used in determining the display form. + * This is the XForms style 'appearance' hint: "full", "compact", "minimal". + * + * @param action The action to set the tooltip column for. + * @param val The value of the appearance hint. + */ void ege_select_one_action_set_appearance( EgeSelectOneAction* action, gchar const* val ); -- 2.30.2