diff options
| -rw-r--r-- | e-util/ChangeLog | 5 | ||||
| -rw-r--r-- | e-util/e-dialog-widgets.c | 174 |
2 files changed, 179 insertions, 0 deletions
diff --git a/e-util/ChangeLog b/e-util/ChangeLog index 339b51f879..17066f1fce 100644 --- a/e-util/ChangeLog +++ b/e-util/ChangeLog @@ -1,3 +1,8 @@ +2000-07-06 Federico Mena Quintero <federico@helixcode.com> + + * e-dialog-widgets.c: Added docstrings. This file did not have + them at all. EEEEEEK! + 2000-07-05 Dan Winship <danw@helixcode.com> * e-sexp.c (e_sexp_parse): Kill debugging message diff --git a/e-util/e-dialog-widgets.c b/e-util/e-dialog-widgets.c index d772ed1f35..19c698af02 100644 --- a/e-util/e-dialog-widgets.c +++ b/e-util/e-dialog-widgets.c @@ -332,6 +332,13 @@ get_editable_value (GtkEditable *editable, gpointer value_var, gpointer data) *value = e_dialog_editable_get (GTK_WIDGET (editable)); } +/** + * e_dialog_editable_set: + * @widget: A #GtkEditable widget. + * @value: String value. + * + * Sets the string value inside a #GtkEditable-derived widget. + **/ void e_dialog_editable_set (GtkWidget *widget, char *value) { @@ -348,6 +355,14 @@ e_dialog_editable_set (GtkWidget *widget, char *value) } } +/** + * e_dialog_editable_get: + * @widget: A #GtkEditable widget. + * + * Queries the string value inside a #GtkEditable-derived widget. + * + * Return value: String value. + **/ char * e_dialog_editable_get (GtkWidget *widget) { @@ -357,6 +372,20 @@ e_dialog_editable_get (GtkWidget *widget) return gtk_editable_get_chars (GTK_EDITABLE (widget), 0, -1); } +/** + * e_dialog_radio_set: + * @widget: A #GtkRadioButton in a radio button group. + * @value: Enumerated value. + * @value_map: Map from enumeration values to array indices. + * + * Sets the selected item in a radio group. The specified @widget can be any of + * the #GtkRadioButtons in the group. Each radio button should correspond to an + * enumeration value; the specified @value will be mapped to an integer from + * zero to the number of items in the group minus 1 by using a mapping table + * specified in @value_map. The last element in this table should be -1. Thus + * a table to map three possible interpolation values to integers could be + * specified as { NEAREST_NEIGHBOR, BILINEAR, HYPERBOLIC, -1 }. + **/ void e_dialog_radio_set (GtkWidget *widget, int value, const int *value_map) { @@ -388,6 +417,18 @@ e_dialog_radio_set (GtkWidget *widget, int value, const int *value_map) value); } +/** + * e_dialog_radio_get: + * @widget: A #GtkRadioButton in a radio button group. + * @value_map: Map from enumeration values to array indices. + * + * Queries the selected item in a #GtkRadioButton group. Please read the + * description of e_dialog_radio_set() to see how @value_map maps enumeration + * values to button indices. + * + * Return value: Enumeration value which corresponds to the selected item in the + * radio group. + **/ int e_dialog_radio_get (GtkWidget *widget, const int *value_map) { @@ -426,6 +467,15 @@ e_dialog_radio_get (GtkWidget *widget, const int *value_map) return v; } +/** + * e_dialog_toggle_set: + * @widget: A #GtkToggleButton. + * @value: Toggle value. + * + * Sets the value of a #GtkToggleButton-derived widget. This should not be used + * for radio buttons; it is more convenient to use use e_dialog_radio_set() + * instead. + **/ void e_dialog_toggle_set (GtkWidget *widget, gboolean value) { @@ -435,6 +485,16 @@ e_dialog_toggle_set (GtkWidget *widget, gboolean value) gtk_toggle_button_set_active (GTK_TOGGLE_BUTTON (widget), value); } +/** + * e_dialog_toggle_get: + * @widget: A #GtkToggleButton. + * + * Queries the value of a #GtkToggleButton-derived widget. This should not be + * used for radio buttons; it is more convenient to use e_dialog_radio_get() + * instead. + * + * Return value: Toggle value. + **/ gboolean e_dialog_toggle_get (GtkWidget *widget) { @@ -444,6 +504,13 @@ e_dialog_toggle_get (GtkWidget *widget) return GTK_TOGGLE_BUTTON (widget)->active; } +/** + * e_dialog_spin_set: + * @widget: A #GtkSpinButton. + * @value: Numeric value. + * + * Sets the value of a #GtkSpinButton widget. + **/ void e_dialog_spin_set (GtkWidget *widget, double value) { @@ -458,6 +525,14 @@ e_dialog_spin_set (GtkWidget *widget, double value) gtk_signal_emit_by_name (GTK_OBJECT (adj), "value_changed"); } +/** + * e_dialog_spin_get_double: + * @widget: A #GtkSpinButton. + * + * Queries the floating-point value of a #GtkSpinButton widget. + * + * Return value: Numeric value. + **/ double e_dialog_spin_get_double (GtkWidget *widget) { @@ -470,6 +545,14 @@ e_dialog_spin_get_double (GtkWidget *widget) return adj->value; } +/** + * e_dialog_spin_get_int: + * @widget: A #GtkSpinButton. + * + * Queries the integer value of a #GtkSpinButton widget. + * + * Return value: Numeric value. + **/ int e_dialog_spin_get_int (GtkWidget *widget) { @@ -482,6 +565,16 @@ e_dialog_spin_get_int (GtkWidget *widget) return (int) floor (value); } +/** + * e_dialog_option_menu_set: + * @widget: A #GtkOptionMenu. + * @value: Enumerated value. + * @value_map: Map from enumeration values to array indices. + * + * Sets the selected item in a #GtkOptionMenu. Please read the description of + * e_dialog_radio_set() to see how @value_map maps enumeration values to item + * indices. + **/ void e_dialog_option_menu_set (GtkWidget *widget, int value, const int *value_map) { @@ -500,6 +593,18 @@ e_dialog_option_menu_set (GtkWidget *widget, int value, const int *value_map) value); } +/** + * e_dialog_option_menu_get: + * @widget: A #GtkOptionMenu. + * @value_map: Map from enumeration values to array indices. + * + * Queries the selected item in a #GtkOptionMenu. Please read the description + * of e_dialog_radio_set() to see how @value_map maps enumeration values to item + * indices. + * + * Return value: Enumeration value which corresponds to the selected item in the + * option menu. + **/ int e_dialog_option_menu_get (GtkWidget *widget, const int *value_map) { @@ -538,6 +643,13 @@ e_dialog_option_menu_get (GtkWidget *widget, const int *value_map) return v; } +/** + * e_dialog_dateedit_set: + * @widget: A #GnomeDateEdit widget. + * @t: Date/time value. + * + * Sets the value of a #GnomeDateEdit widget. + **/ void e_dialog_dateedit_set (GtkWidget *widget, time_t t) { @@ -547,6 +659,14 @@ e_dialog_dateedit_set (GtkWidget *widget, time_t t) gnome_date_edit_set_time (GNOME_DATE_EDIT (widget), t); } +/** + * e_dialog_dateedit_get: + * @widget: A #GnomeDateEdit widget. + * + * Queries the value of a #GnomeDateEdit widget. + * + * Return value: Date/time value. + **/ time_t e_dialog_dateedit_get (GtkWidget *widget) { @@ -556,6 +676,35 @@ e_dialog_dateedit_get (GtkWidget *widget) return gnome_date_edit_get_date (GNOME_DATE_EDIT (widget)); } +/** + * e_dialog_widget_hook_value: + * @dialog: Dialog box in which the @widget lives in. + * @widget: A widget that will control a variable. + * @value_var: Pointer to the variable that the @widget will control. + * @info: NULL for most widgets, or an integer value map array (see + * e_dialog_radio_set() for details). + * + * Hooks a widget from a dialog box to the variable it will modify. Supported + * widgets are: #GtkEditable (char *), #GtkRadioButton (int/value_map pair; see + * e_dialog_radio_set() for more information), #GtkTogglebutton (gboolean), + * #GtkSpinButton (double), #GtkOptionMenu (int/value_map pair), and + * #GnomeDateEdit (time_t). + * + * A pointer to the appropriate variable to modify should be passed in @value_var. + * For values that take a value_map array as well, it should be passed in @info. + * + * The widgets within a dialog that are hooked with this function will set their + * respective variables only when e_dialog_get_values() is called. The typical + * use is to call that function in the handler for the "OK" button of a dialog + * box. + * + * In addition, if the specified @dialog is a #GnomePropertyBox, the widgets wil + * automatically turn on the "Apply" button of the property box when they are + * modified by the user. + * + * Return value: TRUE if the type of the specified @widget is supported, FALSE + * otherwise. + **/ gboolean e_dialog_widget_hook_value (GtkWidget *dialog, GtkWidget *widget, gpointer value_var, gpointer info) @@ -597,6 +746,16 @@ e_dialog_widget_hook_value (GtkWidget *dialog, GtkWidget *widget, return TRUE; } +/** + * e_dialog_get_values: + * @dialog: A dialog box whose widgets have been hooked to the appropriate + * variables with e_dialog_widget_hook_value(). + * + * Makes every widget in a @dialog that was hooked with + * e_dialog_widget_hook_value() apply its value to its corresponding variable. + * The typical usage is to call this function in the handler for the "OK" button + * of a dialog box. + **/ void e_dialog_get_values (GtkWidget *dialog) { @@ -627,6 +786,21 @@ e_dialog_get_values (GtkWidget *dialog) } } +/** + * e_dialog_xml_widget_hook_value: + * @xml: Glade XML description of a dialog box. + * @dialog: Dialog box in which the widget lives in. + * @widget_name: Name of the widget in the Glade XML data. + * @value_var: Pointer to the variable that the widget will control. + * @info: NULL for most widgets, or an integer value map array (see + * e_dialog_radio_set() for details). + * + * Similar to e_dialog_widget_hook_value(), but uses the widget from a #GladeXML + * data structure. + * + * Return value: TRUE if the type of the specified widget is supported, FALSE + * otherwise. + **/ gboolean e_dialog_xml_widget_hook_value (GladeXML *xml, GtkWidget *dialog, const char *widget_name, gpointer value_var, gpointer info) |