+2009-02-02 Alberto Garcia <agarcia@igalia.com>
+
+ 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 <csaavedra@igalia.com>
* configure.ac: post release version bump.
* 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 #HildonBanner<!-- -->s should only be used to display
+ * non-critical pieces of information.
*/
#ifdef HAVE_CONFIG_H
* 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,
* 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,
* 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,
* widget name to allow Hildon specific styling.
*
* Return value: A newly created #GtkMenu widget.
+ *
+ * Since: 2.2
**/
GtkWidget *
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)
* set to %FALSE by default.
*
* Return value: A newly created #GtkToggleButton widget.
+ *
+ * Since: 2.2
**/
GtkWidget *
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,
* 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,
* @mode
*
* Return value: A newly created #GtkTreeView widget.
+ *
+ * Since: 2.2
**/
GtkWidget *
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,
* @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,
* @mode
*
* Return value: A newly created #GtkIconView widget
+ *
+ * Since: 2.2
**/
GtkWidget *
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,
* @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,
/**
* 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,
* 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.
+ *
+ * <example>
+ * <title>Typical <function>main</function> function for a Hildon application</title>
+ * <programlisting>
+ * 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;
+ *}
+ * </programlisting>
+ * </example>
*/
* 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.
+ *
* <example>
* <title>HildonNote example</title>
* <programlisting>
* @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 <math.h>
* 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
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;
/**
* 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
**/
/**
* 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
**/
/**
* 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
**/
/**
* hildon_picker_dialog_get_selector:
- * @dialog:
+ * @dialog: a #HildonPickerDialog
*
- *
+ * Retrieves the #HildonTouchSelector associated to @dialog.
*
- * Returns:
+ * Returns: a #HildonTouchSelector
*
* Since: 2.2
**/
* 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
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.
+ *
+ * <warning>
+ * <para>
+ * HILDON_WIZARD_DIALOG_CANCEL is deprecated and should not be used in newly-written code.
+ * </para>
+ * </warning>
+ **/
+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,
projects / hildon / commitdiff