+2007-01-29 Michael Dominic Kostrzewa <michael.kostrzewa@nokia.com>
+
+ * doc/Makefile.am:
+ * src/hildon-calendar-popup.c:
+ * src/hildon-color-button.c:
+ * src/hildon-color-chooser-dialog.h:
+ * src/hildon-controlbar.c:
+ * src/hildon-date-editor.c:
+ * src/hildon-get-password-dialog.c:
+ * src/hildon-login-dialog.c:
+ * src/hildon-login-dialog.h:
+ * src/hildon-note.c:
+ * src/hildon-program.c:
+ * src/hildon-sort-dialog.c:
+ * src/hildon-time-editor.c:
+ * src/hildon-time-picker.c:
+ * src/hildon-vvolumebar.c:
+ * src/hildon-weekday-picker.c:
+ * src/hildon-window.c:
+ * src/hildon-wizard-dialog.c: Moving the sgml documentation to code.
+
2007-01-25 Michael Dominic Kostrzewa <michael.kostrzewa@nokia.com>
* ./: Big documentation fix mess continued.
-MAINTAINERCLEANFILES = Makefile.in
+MAINTAINERCLEANFILES = Makefile.in \
+ hildon-sections.txt \
+ hildon-undocumented.txt \
+ version.xml
+
+CLEANFILES = version.xml
+
+
DOC_MODULE = hildon
GTKDOC_LIBS = $(GTK_LIBS) ../src/libhildon_@PACKAGE_VERSION_MAJOR@.la
-MKDB_OPTIONS =--sgml-mode --ignore-files=parse
+MKDB_OPTIONS =--sgml-mode
content_files = version.xml
version.xml: ../configure.ac
@echo $(VERSION) > version.xml
+html: html-build.stamp
+
HTML_IMAGES =
FIXXREF_OPTIONS =
* HildonCalendarPopup is a dialog which contains a GtkCalendar. It
* also contains arrow buttons for changing the month/year. If an
* entered date is invalid, an information message will be shown.
+ *
+ * ...
+ * gint y, m, d;
+ * GtkWidget *parent, *popup;
+ * <!-- -->
+ * // get current date into &y, &m, &d...
+ * <!-- -->
+ * gtk_widget_get_ancestor (GTK_WIDGET (data), GTK_TYPE_WINDOW);
+ * popup = hildon_calendar_popup_new (GTK_WINDOW (parent), y, m, d);
+ * <!-- -->
+ * result = gtk_dialog_run (GTK_DIALOG (popup));
+ * switch (result)
+ * {
+ * case GTK_RESPONSE_OK:
+ * case GTK_RESPONSE_ACCEPT:
+ * <!-- -->
+ * hildon_calendar_popup_get_date (HILDON_CALENDAR_POPUP (popup), &y, &m, &d);
+ * <!-- -->
+ * // here set the new date
+ * }
+ * gtk_widget_destroy(popup);
+ * ...
*/
#ifdef HAVE_CONFIG_H
* The selected color is shown in the button.
* The selected color is a property of the button.
* The property name is "color" and its type is GtkColor.
+ *
+ * <example>
+ * <title>HildonColorButton example</title>
+ * <programlisting>
+ * HildonColorButton *cbutton;
+ * GtkColor *color;
+ * <!-- -->
+ * cbutton = hildon_color_button_new();
+ * gtk_object_get( GTK_OBJECT(cbutton), "color", color );
+ * </programlisting>
+ * </example>
+ *
*/
#ifdef HAVE_CONFIG_H
GdkColor *color);
void
-hildon_color_chooser_dialog_get_color (HildonColorChooserDialog *chooser,
+hildon_color_chooser_dialog_get_color (HildonColorChooserDialog *dialog,
GdkColor *color);
#endif /* __HILDON_COLOR_CHOOSER_DIALOG_H__ */
* #HildonControlbar is a horizontally positioned range widget that is
* visually divided into blocks and supports setting a minimum and
* maximum value for the range.
+ *
+ * <example>
+ * <title>HildonControlbar example</title>
+ * <programlisting>
+ * GtkWidget *cbar = hildon_controlbar_new();
+ * hildon_controlbar_set_max (HILDON_CONTROLBAR (cbar), 12);
+ * hildon_controlbar_set_value (HILDON_CONTROLBAR (cbar), 6);
+ * </programlisting>
+ * </example>
+ *
*/
#ifdef HAVE_CONFIG_H
* HildonDateEditor is a widget with three entry fields (day, month,
* year) and an icon (button): clicking on the icon opens up a
* HildonCalendarPopup.
+ *
+ * <example>
+ * <programlisting>
+ * gint y, m, d;
+ * <!-- -->
+ * date_editor = hildon_date_editor_new ();
+ * <!-- -->
+ * hildon_date_editor_get_date(date_editor, &y, &m, &d);
+ * <!-- -->
+ * </programlisting>
+ * </example>
+ *
*/
#ifdef HAVE_CONFIG_H
static gboolean
hildon_date_editor_date_error (HildonDateEditor *editor,
- HildonDateTimeError type);
+ HildonDateTimeError type);
static gboolean
hildon_date_editor_entry_focus_in (GtkWidget *widget,
* @month: month
* @day: day
*
- * Returns: the year, month, and day currently on the
- * date editor. You can pass NULL to any of the pointers if
+ * Gets the date represented by the date editor.
+ * You can pass NULL to any of the pointers if
* you're not interested in obtaining it.
+ *
*/
void
hildon_date_editor_get_date (HildonDateEditor *date,
* HildonGetPasswordDialog prompts the user for a password. It allows
* inputting password, with an optional configurable label eg. for
* showing a custom message. The maximum length of the password can be set.
+ *
+ * <example>
+ * <title>HildonGetPassword example</title>
+ * <programlisting>
+ * get_dialog = HILDON_GET_PASSWORD_DIALOG (hildon_get_password_dialog_new (parent, FALSE));
+ * <!-- -->
+ * gtk_widget_show (GTK_WIDGET (get_dialog));
+ * <!-- -->
+ * i = gtk_dialog_run (GTK_DIALOG (get_dialog));
+ * <!-- -->
+ * pass = hildon_get_password_dialog_get_password (get_dialog);
+ * <!-- -->
+ * if (i == GTK_RESPONSE_OK && (strcmp (pass, dialog.current_password) != 0))
+ * {
+ * gtk_infoprint (GTK_WINDOW (parent), STR_PASSWORD_INCORRECT);
+ * gtk_widget_set_sensitive (GTK_WIDGET (dialog.button2), FALSE);
+ * gtk_widget_set_sensitive (GTK_WIDGET (dialog.button3), FALSE);
+ * gtk_widget_set_sensitive (GTK_WIDGET (dialog.button4), FALSE);
+ * }
+ * <!-- -->
+ * else if (i == GTK_RESPONSE_OK)
+ * {
+ * gtk_widget_set_sensitive( GTK_WIDGET( dialog.button2 ), TRUE);
+ * }
+ * <!-- -->
+ * else
+ * {
+ * gtk_widget_set_sensitive (GTK_WIDGET (dialog.button2), FALSE);
+ * gtk_widget_set_sensitive (GTK_WIDGET (dialog.button3), FALSE);
+ * gtk_widget_set_sensitive (GTK_WIDGET (dialog.button4), FALSE);
+ * }
+ * gtk_widget_destroy (GTK_WIDGET (get_dialog));
+ * }
+ * </programlisting>
+ * </example>
*/
#ifdef HAVE_CONFIG_H
* @dialog: the dialog
* @max_characters: the maximum number of characters the password dialog
* accepts
- * @new_caption: the text to be set as the caption label
*
* sets the maximum number of characters allowed as the password
*/
* @name: default username, NULL if unset
* @password: default password, NULL if unset
*
- * Same as #hildon_login_dialog_new, but with a
+ * Same as #hildon_login_dialog_new but with a
* default username and password.
*
* Returns: the newly created #HildonLoginDialog
GtkWidget*
hildon_login_dialog_new_with_default (GtkWindow *parent,
- const gchar *username,
- const gchar *pass);
+ const gchar *name,
+ const gchar *password);
const gchar*
hildon_login_dialog_get_username (HildonLoginDialog *dialog);
/**
* hildon_note_set_button_texts:
* @note: a #HildonNote
- * @textOk: the new text of the default OK button
- * @textCancel: the new text of the default cancel button
+ * @text_ok: the new text of the default OK button
+ * @text_cancel: the new text of the default cancel button
*
* Sets the button texts to be used by this hildon_note widget.
*/
/**
* hildon_program_add_window:
- * @program: The @HildonProgram to which the window should be registered
+ * @self: The @HildonProgram to which the window should be registered
* @window: A @HildonWindow to be added
*
* Registers a @HildonWindow as belonging to a given @HildonProgram. This
**/
void
hildon_program_set_can_hibernate (HildonProgram *self,
- gboolean killable)
+ gboolean can_hibernate)
{
HildonProgramPrivate *priv;
priv = HILDON_PROGRAM_GET_PRIVATE (self);
g_assert (priv);
- if (priv->killable != killable)
+ if (priv->killable != can_hibernate)
{
g_slist_foreach (priv->windows,
- (GFunc)hildon_window_set_can_hibernate_property, &killable);
+ (GFunc) hildon_window_set_can_hibernate_property, &can_hibernate);
}
- priv->killable = killable;
+ priv->killable = can_hibernate;
}
/**
* HildonSortDialog is used to define an order (ascending/descending)
* and a field by which items are sorted in a list. The combo boxes
* display the current value when the dialog is opened.
+ *
+ * <example>
+ * <title>An example for using HildonSortDialog</title>
+ * <programlisting>
+ * HildonSortDialog *sort_dialog = HILDON_SORT_DIALOG (hildon_sort_dialog_new (parent));
+ * <!-- -->
+ * gint response_id, add_sort_index;
+ * <!-- -->
+ * sort_by[0] = STR_SORT_BY_DATE;
+ * sort_by[1] = STR_SORT_BY_NAME;
+ * sort_by[2] = STR_SORT_BY_SIZE;
+ * sort_by[3] = NULL;
+ * <!-- -->
+ * sorting_order[0] = STR_SORTING_ORDER_ASCENDING;
+ * sorting_order[1] = STR_SORTING_ORDER_DESCENDING;
+ * sorting_order[2] = NULL;
+ * <!-- -->
+ * add_sort_index = hildon_sort_dialog_add_sort_key (sort_dialog, STR_SORT_BY_DATE);
+ * <!-- -->
+ * hildon_sort_dialog_add_sort_key (sort_dialog, STR_SORT_BY_NAME);
+ * <!-- -->
+ * hildon_sort_dialog_add_sort_key (sort_dialog, STR_SORT_BY_SIZE);
+ * <!-- -->
+ * if (dialog.first_time_clicked == TRUE)
+ * {
+ * hildon_sort_dialog_set_sort_key (sort_dialog, add_sort_index);
+ * }
+ * <!-- -->
+ * if (dialog.first_time_clicked == FALSE)
+ * {
+ * hildon_sort_dialog_set_sort_key (sort_dialog, dialog.sort_key);
+ * hildon_sort_dialog_set_sort_order (sort_dialog, dialog.sort_order);
+ * }
+ * <!-- -->
+ * gtk_widget_show (GTK_WIDGET (sort_dialog));
+ * <!-- -->
+ * response_id = gtk_dialog_run (GTK_DIALOG (sort_dialog));
+ * <!-- -->
+ * if (response_id == GTK_RESPONSE_OK)
+ * {
+ * dialog.sort_key = hildon_sort_dialog_get_sort_key (sort_dialog);
+ * <!-- -->
+ * gtk_label_set_text (GTK_LABEL (dialog.label1), sort_by [dialog.sort_key]);
+ * <!-- -->
+ * dialog.sort_order = hildon_sort_dialog_get_sort_order (sort_dialog);
+ * <!-- -->
+ * gtk_label_set_text (GTK_LABEL (dialog.label2), sorting_order [dialog.sort_order]);
+ * <!-- -->
+ * dialog.first_time_clicked = FALSE;
+ * }
+ * </programlisting>
+ * </example>
*/
#ifdef HAVE_CONFIG_H
* amount of time up to 99 hours. It consists of entries for hours,
* minutes and seconds, and pm/am indicator as well as a button which
* popups a #HildonTimePicker dialog.
+ *
+ * <example>
+ * <title>HildonTimePicker example</title>
+ * <programlisting>
+ * <!-- -->
+ * editor = hildon_time_editor_new ();
+ * hildon_time_editor_set_time (editor, h, m, s);
+ * <!-- -->
+ * gtk_box_pack_start (..., editor)
+ * <!-- -->
+ * hildon_time_editor_get_time (editor, &h, &m, &s);
+ * <!-- -->
+ * </programlisting>
+ * </example>
+ *
*/
#ifdef HAVE_CONFIG_H
/**
* hildon_time_editor_get_time_separators:
- * @editor: the #HildonTimeEditor
* @hm_sep_label: the label that will show the hour:minutes separator
* @ms_sep_label: the label that will show the minutes:seconds separator
*
/**
* hildon_time_editor_set_show_hours:
* @editor: The #HildonTimeEditor.
- * @enable: Enable or disable showing of hours.
+ * @show_hours: Enable or disable showing of hours.
*
* This function shows or hides the hours field.
*
/**
* hildon_time_editor_get_show_hours:
- * @self: the @HildonTimeEditor widget.
+ * @editor: the @HildonTimeEditor widget.
*
* This function returns a boolean indicating the visibility of
* hours in the @HildonTimeEditor
* using up/down arrows on hours and minutes. There are two arrows for minutes,
* so that minutes can be added also in 10 min increments.This widget is mainly
* used as a part of #HildonTimeEditor implementation.
+ *
+ * <example>
+ * <title>HildonTimePicker example</title>
+ * <programlisting>
+ * <!-- -->
+ * parent = gtk_widget_get_ancestor (GTK_WIDGET (editor), GTK_TYPE_WINDOW);
+ * picker = hildon_time_picker_new (GTK_WINDOW (parent));
+ * <!-- -->
+ * hildon_time_editor_get_time (editor, &h, &m, &s);
+ * hildon_time_picker_set_time( HILDON_TIME_PICKER( picker ), h, m );
+ * <!-- -->
+ * result = gtk_dialog_run (GTK_DIALOG (picker));
+ * switch (result)
+ * {
+ * case GTK_RESPONSE_OK:
+ * case GTK_RESPONSE_ACCEPT:
+ * hildon_time_picker_get_time(HILDON_TIME_PICKER (picker), &h, &m );
+ * foo_set_time(h,m);
+ * break;
+ * default:
+ * break;
+ * }
+ * <!-- -->
+ * gtk_widget_destroy( picker );
+ * <!-- -->
+ * </programlisting>
+ * </example>
*/
#ifdef HAVE_CONFIG_H
* #HildonVVolumebar is a subclass of #HildonVolumebar. It displays a
* vertical volume bar that allows increasing or decreasing volume
* within a predefined range, and muting when users click the mute icon.
+ *
+ * Here is an example that creates a vertical volume bar and connects
+ * both its signals.
+ * <example>
+ * <title>HildonVVolumebar example</title>
+ * <programlisting>
+ * GtkWidget *volbar = hildon_vvolumebar_new ();
+ * g_signal_connect (G_OBJECT (volbar), "mute_toggled", G_CALLBACK (mute_toggle), NULL);
+ * g_signal_connect (G_OBJECT (volbar), "level_changed", G_CALLBACK (level_change), NULL);
+ * </programlisting>
+ * </example>
*/
#ifdef HAVE_CONFIG_H
* a certain event should take place, for example, which days a Calendar event
* should be repeated on. It is used in Calendar in the Repeat dialog, in Tasks
* in the Repeat dialog and in the Email set-up wizard.
+ *
+ * <example>
+ * <title>HildonWeekdayPicker example</title>
+ * <programlisting>
+ * gint i;
+ * HildonWeekdayPicker *picker = hildon_weekday_picker_new ();
+ * <!-- -->
+ * hildon_weekday_picker_set_day (picker, i);
+ * hildon_weekday_picker_unset_day (picker, i);
+ * hildon_weekday_picker_toggle_day (picker, i);
+ * hildon_weekday_picker_set_all (picker);
+ * <!-- -->
+ * hildon_weekday_picker_unset_all( picker );
+ * </programlisting>
+ * </example>
+ *
*/
/* GDate numbers days from 1 to 7 and G_DATE_MONDAY is 1st day. However
/**
* SECTION:hildon-window
- * @short_description: A basic container for other hildon widgets.
+ * @short_description: Widget representing a top-level window in the Hildon framework.
*
- * A single #HildonProgram can contain many #HildonWindows.
- * HildonWindow is a customized version of GtkWindow that handles
- * automatically some taks of the Hildon UI. A typicall hildon application
- * should contain at least one #HildonWindow.
+ * The HildonWindow is a GTK widget which represents a top-level
+ * window in the Hildon framework. It is derived from the GtkWindow
+ * and provides additional commodities specific to the Hildon
+ * framework.
+
+ * Among these windows in the Hildon framework can have a single menu
+ * attached, which is toggled with a hardware key or by tapping
+ * a custom button in the window frame. This menu can be set
+ * by providing a GtkMenu to the hildon_window_set_menu() method.
+
+ * Similarly a window in the Hildon framework can have several toolbars
+ * attached. These can be added to the HildonWindow with
+ * hildon_window_add_toolbar()..
+ *
+ * <example>
+ * <title>Creating a HildonWindow</title>
+ * <programlisting>
+ * HildonWindow *window;
+ * GtkToolbar *toolbar;
+ * GtkMenu *menu;
+ * GdkPixbuf *icon_pixbuf;
+ * <!-- -->
+ * window = HILDON_WINDOW (hildon_window_new());
+ * <!-- -->
+ * toolbar = create_toolbar();
+ * <!-- -->
+ * menu = create_menu();
+ * <!-- -->
+ * icon_pixbuf = create_icon();
+ * <!-- -->
+ * hildon_window_set_menu (window, menu);
+ * <!-- -->
+ * hildon_window_add_toolbar (window, toolbar);
+ * <!-- -->
+ * // Can be used to set the window fullscreen
+ * gtk_window_fullscreen (GTK_WINDOW (window));
+ * <!-- -->
+ * // Used to trigger the blinking of the window's icon in the task navigator
+ * gtk_window_set_urgency_hint (GTK_WINDOW (window), TRUE);
+ * <!-- -->
+ * // Change the window's icon in the task navigator
+ * gtk_window_set_icon (GTK_WINDOW (window), icon_pixbuf);
+ * </programlisting>
+ * </example>
*
*/
* Response buttons are dimmed/undimmed automatically and the standard
* icon is shown/hidden in response to page navigation. The notebook
* widget provided by users contains the actual wizard pages.
+ *
+ * Using of the API is very simple, it has only one function to create it
+ * and the rest of it is handled by developers notebook.
+ * Also the response is returned, either cancel or finnish.
+ * Next and previous buttons are handled by the wizard dialog it self, by
+ * switching the page either forward or backward in the notebook.
*/
#ifdef HAVE_CONFIG_H
projects / hildon / commitdiff