diff options
Diffstat (limited to 'lib')
| -rw-r--r-- | lib/ephy-dialog.c | 191 | ||||
| -rw-r--r-- | lib/ephy-dialog.h | 8 |
2 files changed, 182 insertions, 17 deletions
diff --git a/lib/ephy-dialog.c b/lib/ephy-dialog.c index 7eddc3a87..210283699 100644 --- a/lib/ephy-dialog.c +++ b/lib/ephy-dialog.c @@ -30,6 +30,13 @@ #include <string.h> #include <gtk/gtk.h> +/** + * SECTION:ephy-dialog + * @short_description: A customized #GtkDialog for Epiphany + * + * A customized #GtkDialog for Epiphany. + */ + enum { PROP_0, @@ -1126,6 +1133,13 @@ impl_show (EphyDialog *dialog) gtk_window_present (GTK_WINDOW (dialog->priv->dialog)); } +/** + * ephy_dialog_set_modal: + * @dialog: an #EphyDialog + * @is_modal: %TRUE to make @dialog modal + * + * Sets @dialog to be modal or not. + **/ void ephy_dialog_set_modal (EphyDialog *dialog, gboolean is_modal) @@ -1135,9 +1149,20 @@ ephy_dialog_set_modal (EphyDialog *dialog, gtk_window_set_modal (GTK_WINDOW(dialog->priv->dialog), is_modal); } +/** + * ephy_dialog_add_enum: + * @dialog: an #EphyDialog + * @property_id: string identifier of the property to modify + * @n_items: length of @items array + * @items: array of items to add to @property_id + * + * Modifies the property identified by @property_id in @dialog to have its + * string_enum member set to a #GList constructed with the elements given as + * @items. + **/ void ephy_dialog_add_enum (EphyDialog *dialog, - const char *id, + const char *property_id, guint n_items, const char *const *items) { @@ -1145,7 +1170,7 @@ ephy_dialog_add_enum (EphyDialog *dialog, int i = 0; GList *l = NULL; - info = lookup_info (dialog, id); + info = lookup_info (dialog, property_id); g_return_if_fail (info != NULL); for (i = 0; i < n_items; i++) @@ -1156,19 +1181,37 @@ ephy_dialog_add_enum (EphyDialog *dialog, info->string_enum = g_list_reverse (l); } +/** + * ephy_dialog_set_data_column: + * @dialog: an #EphyDialog + * @property_id: string identifier of the property to modify + * @column: value for the data_col member of @property_id + * + * Sets the data_col member of the property identified by @property_id in @dialog + * to @column. + **/ void ephy_dialog_set_data_column (EphyDialog *dialog, - const char *id, + const char *property_id, int column) { PropertyInfo *info; - info = lookup_info (dialog, id); + info = lookup_info (dialog, property_id); g_return_if_fail (info != NULL); info->data_col = column; } +/** + * ephy_dialog_set_pref: + * @dialog: an #EphyDialog + * @property_id: string identifier of the property to modify + * @pref: preference value of the property identified by @property_id + * + * Sets the pref member of the property of @dialog identified by @property_id + * to @pref. + **/ void ephy_dialog_set_pref (EphyDialog *dialog, const char *property_id, @@ -1194,6 +1237,15 @@ ephy_dialog_set_pref (EphyDialog *dialog, } } +/** + * ephy_dialog_set_size_group: + * @dialog: an #EphyDialog + * @first_id: id of a widget in @dialog + * @Varargs: a %NULL-terminated list of widget ids + * + * Put @first_id and @Varargs widgets into the same #GtkSizeGroup. + * Note that this are all widgets inside @dialog. + **/ void ephy_dialog_set_size_group (EphyDialog *dialog, const char *first_id, @@ -1225,6 +1277,18 @@ ephy_dialog_set_size_group (EphyDialog *dialog, g_object_unref (size_group); } +/** + * ephy_dialog_construct: + * @dialog: an #EphyDialog + * @properties: an array of #EphyDialogProperty elements + * @file: the path to a #GtkBuilder file + * @name: name of the widget to use for @dialog, found in @file + * @domain: translation domain to set for @dialog + * + * Constructs the widget part of @dialog using the widget identified by @name + * in the #GtkBuilder file found at @file. Fills the dialog properties with + * @properties and sets translation domain to @domain. + **/ void ephy_dialog_construct (EphyDialog *dialog, const EphyDialogProperty *properties, @@ -1236,6 +1300,12 @@ ephy_dialog_construct (EphyDialog *dialog, klass->construct (dialog, properties, file, name, domain); } +/** + * ephy_dialog_show: + * @dialog: an #EphyDialog + * + * Shows @dialog on screen. + **/ void ephy_dialog_show (EphyDialog *dialog) { @@ -1243,6 +1313,12 @@ ephy_dialog_show (EphyDialog *dialog) klass->show (dialog); } +/** + * ephy_dialog_hide: + * @dialog: an #EphyDialog + * + * Calls gtk_widget_hide on @dialog. + **/ void ephy_dialog_hide (EphyDialog *dialog) { @@ -1252,6 +1328,14 @@ ephy_dialog_hide (EphyDialog *dialog) gtk_widget_hide (dialog->priv->dialog); } +/** + * ephy_dialog_run: + * @dialog: an #EphyDialog + * + * Runs gtk_dialog_run on @dialog and waits for a response. + * + * Returns: the user response to gtk_dialog_run + **/ int ephy_dialog_run (EphyDialog *dialog) { @@ -1265,8 +1349,11 @@ ephy_dialog_run (EphyDialog *dialog) /** * ephy_dialog_get_control: + * @dialog: an #EphyDialog + * @property_id: the string identifier of the requested control * - * Return value: (transfer none): + * Gets the internal widget corresponding to @property_id from @dialog. + * Return value: (transfer none): the #GtkWidget corresponding to @property_id **/ GtkWidget * ephy_dialog_get_control (EphyDialog *dialog, @@ -1282,29 +1369,36 @@ ephy_dialog_get_control (EphyDialog *dialog, /** * ephy_dialog_get_controls: + * @dialog: an #EphyDialog + * @first_id: identifier of the requested control + * @Varargs: a %NULL terminated list of extra pairs of properties as const char + * and store locations as #GtkWidgets. * + * Gets the requested controls according to given property-store_location pairs. + * Properties are given as strings (const char *), controls are returned as + * #GtkWidget elements. * Rename to: ephy_dialog_get_controls **/ void ephy_dialog_get_controls (EphyDialog *dialog, - const char *property_id, + const char *first_id, ...) { PropertyInfo *info; GtkWidget **wptr; va_list varargs; - va_start (varargs, property_id); + va_start (varargs, first_id); - while (property_id != NULL) + while (first_id != NULL) { - info = lookup_info (dialog, property_id); + info = lookup_info (dialog, first_id); g_return_if_fail (info != NULL); wptr = va_arg (varargs, GtkWidget **); *wptr = info->widget; - property_id = va_arg (varargs, const char *); + first_id = va_arg (varargs, const char *); } va_end (varargs); @@ -1312,8 +1406,13 @@ ephy_dialog_get_controls (EphyDialog *dialog, /** * ephy_dialog_get_value: + * @dialog: an #EphyDialog + * @property_id: property name + * @value: (out): location to store the value of @property_id * - * @value: (out): + * Gets the value of @property_id and stores it in @value. + * + * Returns: %TRUE if the operation was successful */ gboolean ephy_dialog_get_value (EphyDialog *dialog, @@ -1328,6 +1427,14 @@ ephy_dialog_get_value (EphyDialog *dialog, return set_value_from_info (info, value); } +/** + * ephy_dialog_set_value: + * @dialog: an #EphyDialog + * @property_id: @dialog property to set + * @value: value to set @property_id to + * + * Sets the property identified by @property_id to @value in @dialog. + **/ void ephy_dialog_set_value (EphyDialog *dialog, const char *property_id, @@ -1396,8 +1503,11 @@ ephy_dialog_finalize (GObject *object) /** * ephy_dialog_get_parent: + * @dialog: an #EphyDialog + * + * Gets @dialog's parent-window. * - * Return value: (transfer none): + * Returns: (transfer none): the parent-window of @dialog **/ GtkWidget * ephy_dialog_get_parent (EphyDialog *dialog) @@ -1407,6 +1517,13 @@ ephy_dialog_get_parent (EphyDialog *dialog) return dialog->priv->parent; } +/** + * ephy_dialog_set_parent: + * @dialog: an #EphyDialog + * @parent: new parent for @dialog + * + * Sets @parent as the parent-window of @dialog. + **/ void ephy_dialog_set_parent (EphyDialog *dialog, GtkWidget *parent) @@ -1487,6 +1604,14 @@ ephy_dialog_class_init (EphyDialogClass *klass) klass->construct = impl_construct; klass->show = impl_show; + /** + * EphyDialog::changed: + * @dialog: the object on which the signal is emitted + * @value: new value of the modified widget, as a #GValue + * + * Emitted everytime a child widget of the dialog has its changed or + * clicked signal emitted. + */ signals[CHANGED] = g_signal_new ("changed", EPHY_TYPE_DIALOG, @@ -1498,6 +1623,11 @@ ephy_dialog_class_init (EphyDialogClass *klass) 1, G_TYPE_POINTER); + /** + * EphyDialog:parent-window: + * + * Dialog's parent window. + */ g_object_class_install_property (object_class, PROP_PARENT_WINDOW, g_param_spec_object ("parent-window", @@ -1506,14 +1636,24 @@ ephy_dialog_class_init (EphyDialogClass *klass) GTK_TYPE_WINDOW, G_PARAM_READWRITE | G_PARAM_STATIC_NAME | G_PARAM_STATIC_NICK | G_PARAM_STATIC_BLURB)); + /** + * EphyDialog:modal: + * + * Whether the dialog is or not modal. + */ g_object_class_install_property (object_class, PROP_MODAL, - g_param_spec_boolean ("Modal", + g_param_spec_boolean ("modal", "Modal", "Modal dialog", FALSE, G_PARAM_READWRITE | G_PARAM_STATIC_NAME | G_PARAM_STATIC_NICK | G_PARAM_STATIC_BLURB)); + /** + * EphyDialog:persist-position: + * + * If dialog position should be persistent. + */ g_object_class_install_property (object_class, PROP_PERSIST_POSITION, g_param_spec_boolean ("persist-position", @@ -1523,6 +1663,11 @@ ephy_dialog_class_init (EphyDialogClass *klass) G_PARAM_READWRITE | G_PARAM_STATIC_NAME | G_PARAM_STATIC_NICK | G_PARAM_STATIC_BLURB | G_PARAM_CONSTRUCT_ONLY)); + /** + * EphyDialog:default-width: + * + * The dialog default width. + */ g_object_class_install_property (object_class, PROP_DEFAULT_WIDTH, g_param_spec_int ("default-width", @@ -1534,6 +1679,11 @@ ephy_dialog_class_init (EphyDialogClass *klass) G_PARAM_READWRITE | G_PARAM_STATIC_NAME | G_PARAM_STATIC_NICK | G_PARAM_STATIC_BLURB | G_PARAM_CONSTRUCT_ONLY)); + /** + * EphyDialog:default-height: + * + * The dialog default height. + */ g_object_class_install_property (object_class, PROP_DEFAULT_HEIGHT, g_param_spec_int ("default-height", @@ -1548,12 +1698,27 @@ ephy_dialog_class_init (EphyDialogClass *klass) g_type_class_add_private (object_class, sizeof (EphyDialogPrivate)); } +/** + * ephy_dialog_new: + * + * Creates a new #EphyDialog. + * + * Returns: a new #EphyDialog + **/ EphyDialog * ephy_dialog_new (void) { return EPHY_DIALOG (g_object_new (EPHY_TYPE_DIALOG, NULL)); } +/** + * ephy_dialog_new_with_parent: + * @parent_window: a window to be parent of the new dialog + * + * Creates a new #EphyDialog with @parent_window as its parent. + * + * Returns: a new #EphyDialog + **/ EphyDialog * ephy_dialog_new_with_parent (GtkWidget *parent_window) { diff --git a/lib/ephy-dialog.h b/lib/ephy-dialog.h index 343eed0c2..40d7f4e5e 100644 --- a/lib/ephy-dialog.h +++ b/lib/ephy-dialog.h @@ -96,13 +96,13 @@ void ephy_dialog_construct (EphyDialog *dialog, const char *domain); void ephy_dialog_add_enum (EphyDialog *dialog, - const char *id, + const char *property_id, guint n_items, const char * const *items); void ephy_dialog_set_data_column (EphyDialog *dialog, - const char *id, - int col); + const char *property_id, + int column); void ephy_dialog_set_size_group (EphyDialog *dialog, const char *first_id, @@ -126,7 +126,7 @@ GtkWidget *ephy_dialog_get_control (EphyDialog *dialog, const char *property_id); void ephy_dialog_get_controls (EphyDialog *dialog, - const char *first_property_id, + const char *first_id, ...); gboolean ephy_dialog_get_value (EphyDialog *dialog, |