From 77aa4a93908eb3afa2fe4ea253ad1f16dc25f7ca Mon Sep 17 00:00:00 2001 From: Alberto Garcia Date: Mon, 2 Feb 2009 12:20:29 +0000 Subject: [PATCH] 2009-02-02 Alberto Garcia MIME-Version: 1.0 Content-Type: text/plain; charset=utf8 Content-Transfer-Encoding: 8bit Based on a patch by Iván Gómez (igomez@igalia.com) * src/hildon-banner.c * src/hildon-gtk.c * src/hildon-main.c * src/hildon-note.c * src/hildon-pannable-area.c * src/hildon-picker-dialog.c * src/hildon-wizard-dialog.h * src/hildon-wizard-dialog.c: Documentation updates. * src/hildon-picker-dialog.c (hildon_picker_dialog_init): Use gtk_dialog_add_button() instead of hildon_dialog_add_button(). --- ChangeLog | 16 +++++++++++++ src/hildon-banner.c | 53 ++++++++++++++++++++++++++++++++------------ src/hildon-gtk.c | 31 ++++++++++++++++++++++---- src/hildon-main.c | 38 +++++++++++++++++++++++++++++++ src/hildon-note.c | 24 ++++++++++++++++---- src/hildon-pannable-area.c | 12 +++++++--- src/hildon-picker-dialog.c | 41 +++++++++++++++++++++------------- src/hildon-wizard-dialog.c | 4 ++++ src/hildon-wizard-dialog.h | 22 ++++++++++++++---- 9 files changed, 197 insertions(+), 44 deletions(-) diff --git a/ChangeLog b/ChangeLog index 8fdae00..13542a3 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,19 @@ +2009-02-02 Alberto Garcia + + Based on a patch by Iván Gómez (igomez@igalia.com) + + * src/hildon-banner.c + * src/hildon-gtk.c + * src/hildon-main.c + * src/hildon-note.c + * src/hildon-pannable-area.c + * src/hildon-picker-dialog.c + * src/hildon-wizard-dialog.h + * src/hildon-wizard-dialog.c: Documentation updates. + + * src/hildon-picker-dialog.c (hildon_picker_dialog_init): Use + gtk_dialog_add_button() instead of hildon_dialog_add_button(). + 2009-02-02 Claudio Saavedra * configure.ac: post release version bump. diff --git a/src/hildon-banner.c b/src/hildon-banner.c index 15c4076..9c1207b 100644 --- a/src/hildon-banner.c +++ b/src/hildon-banner.c @@ -26,12 +26,29 @@ * SECTION:hildon-banner * @short_description: A widget used to display timed notifications. * - * #HildonBanner can be used to display a short, timed notification - * or information to the user. It can communicate that a - * task has been finished or the application state has changed. - * Banners should be used only to display non-critical pieces of - * information. + * #HildonBanner is a small, pop-up window that can be used to display + * a short, timed notification or information to the user. It can + * communicate that a task has been finished or that the application + * state has changed. * + * Hildon provides convenient funtions to create and show banners. To + * create and show information banners you can use + * hildon_banner_show_information(), hildon_banner_show_informationf() + * or hildon_banner_show_information_with_markup(). + * + * Two more kinds of banners are maintained for backward compatibility + * but are no longer recommended in Hildon 2.2. These are the animated + * banner (created with hildon_banner_show_animation()) and the + * progress banner (created with hildon_banner_show_progress()). See + * hildon_gtk_window_set_progress_indicator() for the preferred way of + * showing progress notifications in Hildon 2.2. + * + * Information banners dissapear automatically after a certain + * period. This is stored in the #HildonBanner:timeout property (in + * miliseconds), and can be changed using hildon_banner_set_timeout(). + * + * Note that #HildonBanners should only be used to display + * non-critical pieces of information. */ #ifdef HAVE_CONFIG_H @@ -1019,18 +1036,20 @@ hildon_banner_show_information_with_markup (GtkWidget *widget, * located so that you can somehow see both. * * Please note that banners are destroyed automatically once the - * window they are attached to is closed. The pointer that you - * receive with this function do not contain additional references, - * so it can become invalid without warning (this is true for - * all toplevel windows in gtk). To make sure that the banner do not disapear + * window they are attached to is closed. The pointer that you receive + * with this function does not contain additional references, so it + * can become invalid without warning (this is true for all toplevel + * windows in gtk). To make sure that the banner does not disappear * automatically, you can separately ref the return value (this - * doesn't prevent the banner from disappearing, but the object it just - * not finalized). In this case you have to call both #gtk_widget_destroy - * followed by #g_object_unref (in this order). - * - * Returns: a #HildonBanner widget. You must call #gtk_widget_destroy + * doesn't prevent the banner from disappearing, just the object from + * being finalized). In this case you have to call both + * gtk_widget_destroy() followed by g_object_unref() (in this order). + * + * Returns: a #HildonBanner widget. You must call gtk_widget_destroy() * once you are done with the banner. * + * Deprecated: Hildon 2.2: use + * hildon_gtk_window_set_progress_indicator() instead. */ GtkWidget* hildon_banner_show_animation (GtkWidget *widget, @@ -1193,6 +1212,9 @@ hildon_banner_set_markup (HildonBanner *self, * the scale is from 0.0 to 1.0. * Sets the amount of fraction the progressbar has. * + * Note that this method only has effect if @self was created with + * hildon_banner_show_progress() + * */ void hildon_banner_set_fraction (HildonBanner *self, @@ -1218,6 +1240,9 @@ hildon_banner_set_fraction (HildonBanner *self, * sense on the banners that are timed and that have not been yet displayed * on the screen. * + * Note that this method only has effect if @self is an information + * banner (created using hildon_banner_show_information() and + * friends). */ void hildon_banner_set_timeout (HildonBanner *self, diff --git a/src/hildon-gtk.c b/src/hildon-gtk.c index 0a132fb..861c7fc 100644 --- a/src/hildon-gtk.c +++ b/src/hildon-gtk.c @@ -90,6 +90,8 @@ button_common_init (GtkWidget *button, * widget name to allow Hildon specific styling. * * Return value: A newly created #GtkMenu widget. + * + * Since: 2.2 **/ GtkWidget * hildon_gtk_menu_new (void) @@ -114,6 +116,8 @@ hildon_gtk_menu_new (void) * set to %FALSE by default. * * Return value: A newly created #GtkButton widget. + * + * Since: 2.2 **/ GtkWidget * hildon_gtk_button_new (HildonSizeType size) @@ -138,6 +142,8 @@ hildon_gtk_button_new (HildonSizeType size) * set to %FALSE by default. * * Return value: A newly created #GtkToggleButton widget. + * + * Since: 2.2 **/ GtkWidget * hildon_gtk_toggle_button_new (HildonSizeType size) @@ -164,6 +170,8 @@ hildon_gtk_toggle_button_new (HildonSizeType size) * set to %FALSE by default. * * Return value: A newly created #GtkRadioButton widget. + * + * Since: 2.2 **/ GtkWidget * hildon_gtk_radio_button_new (HildonSizeType size, @@ -190,6 +198,8 @@ hildon_gtk_radio_button_new (HildonSizeType size, * set to %FALSE by default. * * Return value: A newly created #GtkRadioButton widget. + * + * Since: 2.2 **/ GtkWidget * hildon_gtk_radio_button_new_from_widget (HildonSizeType size, @@ -209,6 +219,8 @@ hildon_gtk_radio_button_new_from_widget (HildonSizeType size, * @mode * * Return value: A newly created #GtkTreeView widget. + * + * Since: 2.2 **/ GtkWidget * hildon_gtk_tree_view_new (HildonUIMode mode) @@ -226,6 +238,8 @@ hildon_gtk_tree_view_new (HildonUIMode mode) * @mode and the model initialized to @model. * * Return value: A newly created #GtkTreeView widget. + * + * Since: 2.2 **/ GtkWidget * hildon_gtk_tree_view_new_with_model (HildonUIMode mode, @@ -240,6 +254,8 @@ hildon_gtk_tree_view_new_with_model (HildonUIMode mode, * @mode: The new #HildonUIMode * * Sets the UI mode of @treeview to @mode. + * + * Since: 2.2 **/ void hildon_gtk_tree_view_set_ui_mode (GtkTreeView *treeview, @@ -257,6 +273,8 @@ hildon_gtk_tree_view_set_ui_mode (GtkTreeView *treeview, * @mode * * Return value: A newly created #GtkIconView widget + * + * Since: 2.2 **/ GtkWidget * hildon_gtk_icon_view_new (HildonUIMode mode) @@ -273,6 +291,8 @@ hildon_gtk_icon_view_new (HildonUIMode mode) * @mode and the model intitialized to @model. * * Return value: A newly created #GtkIconView widget. + * + * Since: 2.2 **/ GtkWidget * hildon_gtk_icon_view_new_with_model (HildonUIMode mode, @@ -287,6 +307,8 @@ hildon_gtk_icon_view_new_with_model (HildonUIMode mode, * @mode: The new #HildonUIMode * * Sets the UI mode of @iconview to @mode. + * + * Since: 2.2 **/ void hildon_gtk_icon_view_set_ui_mode (GtkIconView *iconview, @@ -299,14 +321,15 @@ hildon_gtk_icon_view_set_ui_mode (GtkIconView *iconview, /** * hildon_gtk_window_set_progress_indicator: - * @window: The window, we want to define its state + * @window: The window * @state: The state we want to set: 1 -> show progress indicator, 0 * -> hide progress indicator. * - * This functions notifies the window manager that it should add a - * progress indicator in the title of the window. It applies to - * #HildonDialog and #HildonWindow. + * This functions tells the window manager to show/hide a progress + * indicator in the window title. It applies to #HildonDialog and + * #HildonWindow (including subclasses). * + * Since: 2.2 **/ void hildon_gtk_window_set_progress_indicator (GtkWindow *window, diff --git a/src/hildon-main.c b/src/hildon-main.c index c9d84e6..652d4aa 100644 --- a/src/hildon-main.c +++ b/src/hildon-main.c @@ -24,6 +24,44 @@ * SECTION:hildon-main * @Short_Description: Library initialization. * + * Before using Hildon, you need to initialize it; initialization connects + * to the window system display, and parses some standard command line + * arguments. See also gtk_init () to know more details on this topic. + * + * Hildon should be initialized by using hildon_gtk_init (). Notice this function + * also initialize gtk by calling gtk_init (). In case you need a customized + * initialization of GTK+ library you could use hildon_init () after the + * customized GTK+ initialization. + * + * + * Typical <function>main</function> function for a Hildon application + * + * int + * main (int argc, char **argv) + * { + * /* Initialize i18n support */ + * gtk_set_locale (); + * + * /* Initialize the widget set */ + * hildon_gtk_init (&argc, &argv); + * + * /* Create the main window */ + * mainwin = hildon_stackable_window_new(); + * + * /* Set up our GUI elements */ + * ... + * + * /* Show the application window */ + * gtk_widget_show_all (mainwin); + * + * /* Enter the main event loop, and wait for user interaction */ + * gtk_main (); + * + * /* The user lost interest */ + * return 0; + *} + * + * */ diff --git a/src/hildon-note.c b/src/hildon-note.c index 1900f75..9325e3f 100644 --- a/src/hildon-note.c +++ b/src/hildon-note.c @@ -26,10 +26,26 @@ * SECTION:hildon-note * @short_description: A widget to ask confirmation from the user. * - * Notes are used to for confirmation (OK/Cancel/etc.) from the user. - * A simple note contains an information text. Additional features - * such as progress bars or animation can also be included. - * + * #HildonNote is a convenient way to prompt users for a small amount of + * input. A simple note contains an information text and, in case of + * confirmation notes, it shows buttons to confirm or cancel. It also can + * include a progress bar. + * + * This widget provides convenient functions to create either + * information notes, confirmation notes or cancel notes, which are + * useful to show the progress of a requested task allowing the user + * to cancel it. + * + * To create information notes you can use + * hildon_note_new_information(). hildon_note_new_confirmation() + * creates a note with a text and two buttons to confirm or + * cancel. Note that it is possible to create a confirmation note with + * customized buttons by using + * hildon_note_new_confirmation_add_buttons(). + * + * To create a note with a text, a progress bar and cancel button, + * hildon_note_new_cancel_with_progress_bar() can be used. + * * * HildonNote example * diff --git a/src/hildon-pannable-area.c b/src/hildon-pannable-area.c index 269bab6..deb9ef5 100644 --- a/src/hildon-pannable-area.c +++ b/src/hildon-pannable-area.c @@ -26,10 +26,16 @@ * @short_description: A scrolling widget designed for touch screens * @see_also: #GtkScrolledWindow * - * #HildonPannableArea implements a scrolled window designed to be used with a - * touch screen interface. The user scrolls the child widget by activating the - * pointing device and dragging it over the widget. + * #HildonPannableArea is a container widget that can be "panned" (scrolled) + * up and down using the touchscreen with fingers. The widget has no scrollbars, + * but it rather shows small scroll indicators to give an idea of the part of the + * content that is visible at a time. The scroll indicators appear when a dragging + * motion is started on the pannable area. * + * The scrolling is "kinetic", meaning the motion can be "flicked" and it will + * continue from the initial motion by gradually slowing down to an eventual stop. + * The motion can also be stopped immediately by pressing the touchscreen over the + * pannable area. */ #include diff --git a/src/hildon-picker-dialog.c b/src/hildon-picker-dialog.c index 9eded72..a92775d 100644 --- a/src/hildon-picker-dialog.c +++ b/src/hildon-picker-dialog.c @@ -22,9 +22,18 @@ * SECTION:hildon-picker-dialog * @short_description: A utility widget that shows a #HildonTouchSelector widget * - * HildonPickerDialog is a utility widget that shows a #HildonTouchSelector widget in - * a new dialog (a #HildonDialog) + * #HildonPickerDialog is a dialog that is used to show a + * #HildonTouchSelector widget and a 'Done' button to allow users to + * finish their selections. * + * The #HildonPickerDialog will show a 'Done' button in case the + * #HildonTouchSelector allows multiple selection. The label of the + * button can be set using hildon_picker_dialog_set_done_label() and + * retrieved using hildon_picker_dialog_get_done_label() + * + * Note that in most cases developers don't need to deal directly with + * this widget. #HildonPickerButton is designed to pop up a + * #HildonPickerDialog and manage the interaction with it. */ #ifdef HAVE_CONFIG_H @@ -198,7 +207,7 @@ hildon_picker_dialog_init (HildonPickerDialog * dialog) dialog->priv->selector = NULL; dialog->priv->button = - hildon_dialog_add_button (HILDON_DIALOG (dialog), "", GTK_RESPONSE_OK); + gtk_dialog_add_button (GTK_DIALOG (dialog), "", GTK_RESPONSE_OK); gtk_widget_grab_default (dialog->priv->button); dialog->priv->signal_changed_id = 0; @@ -326,8 +335,10 @@ on_selector_columns_changed (HildonTouchSelector * selector, gpointer userdata) /** * hildon_picker_dialog_set_done_label: - * @dialog: - * @label: + * @dialog: a #HildonPickerDialog + * @label: a string + * + * Sets a custom string to be used as the 'Done' button label in @dialog. * * Since: 2.2 **/ @@ -347,11 +358,11 @@ hildon_picker_dialog_set_done_label (HildonPickerDialog * dialog, /** * hildon_picker_dialog_get_done_label: - * @dialog: + * @dialog: a #HildonPickerDialog * - * + * Retrieves current 'Done' button label. * - * Returns: + * Returns: the custom string to be used. * * Since: 2.2 **/ @@ -548,12 +559,12 @@ _hildon_picker_dialog_set_selector (HildonPickerDialog * dialog, /** * hildon_picker_dialog_set_selector: - * @dialog: - * @selector: + * @dialog: a #HildonPickerDialog + * @selector: a #HildonTouchSelector * - * + * Sets @selector as the #HildonTouchSelector to be shown in @dialog * - * Returns: + * Returns: %TRUE if @selector was set, %FALSE otherwise * * Since: 2.2 **/ @@ -569,11 +580,11 @@ hildon_picker_dialog_set_selector (HildonPickerDialog * dialog, /** * hildon_picker_dialog_get_selector: - * @dialog: + * @dialog: a #HildonPickerDialog * - * + * Retrieves the #HildonTouchSelector associated to @dialog. * - * Returns: + * Returns: a #HildonTouchSelector * * Since: 2.2 **/ diff --git a/src/hildon-wizard-dialog.c b/src/hildon-wizard-dialog.c index d347081..8a8ee83 100644 --- a/src/hildon-wizard-dialog.c +++ b/src/hildon-wizard-dialog.c @@ -40,6 +40,10 @@ * Also, the response is returned, either cancel or finish. * Next and previous buttons are handled by the wizard dialog it self, by * switching the page either forward or backward in the notebook. + * + * It is possible to determinate whether users can go to the next page + * by setting a #HildonWizardDialogPageFunc function with + * hildon_wizard_dialog_set_forward_page_func() */ #ifdef HAVE_CONFIG_H diff --git a/src/hildon-wizard-dialog.h b/src/hildon-wizard-dialog.h index 5b65ef8..a39abe4 100644 --- a/src/hildon-wizard-dialog.h +++ b/src/hildon-wizard-dialog.h @@ -52,11 +52,25 @@ typedef struct _HildonWizardDialog HildonWizard typedef struct _HildonWizardDialogClass HildonWizardDialogClass; -/* button response IDs */ - -typedef enum +/* HILDON_WIZARD_DIALOG_CANCEL should be marked as deprecated */ + +/** + * HildonWizardDialogResponse: + * @HILDON_WIZARD_DIALOG_CANCEL: Returned by the 'Cancel' button. + * @HILDON_WIZARD_DIALOG_PREVIOUS: Returned by the 'Previous' button. + * @HILDON_WIZARD_DIALOG_NEXT: Returned by the 'Next' button. + * @HILDON_WIZARD_DIALOG_FINISH: Returned by the 'Finish' button. + * + * Predefined values for use as response ids for #HildonWizardDialog. + * + * + * + * HILDON_WIZARD_DIALOG_CANCEL is deprecated and should not be used in newly-written code. + * + * + **/ +typedef enum { - /* HILDON_WIZARD_DIALOG_CANCEL should be marked as deprecated */ HILDON_WIZARD_DIALOG_CANCEL = GTK_RESPONSE_CANCEL, HILDON_WIZARD_DIALOG_PREVIOUS = 0, HILDON_WIZARD_DIALOG_NEXT, -- 1.7.9.5