+006-03-16 Luc Pionchon <luc.pionchon@nokia.com>
+
+ * doc/tmpl/*
+ * hildon-widgets/*
+ moved widget descriptions to respective source file (*.c)
+ + minor doc updates
+
+
006-03-15 Luc Pionchon <luc.pionchon@nokia.com>
Cleanup color button
</para>
+<!-- ##### SECTION Stability_Level ##### -->
+
+
<!-- ##### FUNCTION gtk_infoprint_with_icon_stock ##### -->
<para>
@icon_name:
+<!-- ##### FUNCTION gtk_infoprint_with_icon_name ##### -->
+<para>
+
+</para>
+
+@parent:
+@text:
+@icon_name:
+
+
<!-- ##### FUNCTION gtk_infoprintf ##### -->
<para>
@icon_name:
+<!-- ##### FUNCTION gtk_confirmation_banner_with_icon_name ##### -->
+<para>
+
+</para>
+
+@parent:
+@text:
+@icon_name:
+
+
<!-- ##### FUNCTION gtk_confirmation_banner ##### -->
<para>
HildonApp
<!-- ##### SECTION Short_Description ##### -->
-A base widget to present application.
+
<!-- ##### SECTION Long_Description ##### -->
<para>
-This is the base for any hildon application.
-It controls basic looks and functionality of an application, like a title.
<informalexample>
<programlisting>
@Returns:
-<!-- ##### FUNCTION hildon_app_new ##### -->
+<!-- ##### MACRO HILDON_TYPE_ZOOM_LEVEL ##### -->
<para>
</para>
-@Returns:
-<!-- ##### FUNCTION hildon_app_new_with_appview ##### -->
+<!-- ##### MACRO HILDON_MENU_KEY ##### -->
<para>
</para>
-@appview:
-@Returns:
-<!-- ##### FUNCTION hildon_app_set_appview ##### -->
+<!-- ##### MACRO HILDON_HOME_KEY ##### -->
<para>
</para>
-@self:
-@appview:
-<!-- ##### FUNCTION hildon_app_get_appview ##### -->
+<!-- ##### MACRO HILDON_TOOLBAR_KEY ##### -->
<para>
</para>
-@self:
-@Returns:
-<!-- ##### FUNCTION hildon_app_set_title ##### -->
+<!-- ##### MACRO HILDON_FULLSCREEN_KEY ##### -->
<para>
</para>
-@self:
-@newtitle:
-<!-- ##### FUNCTION hildon_app_get_title ##### -->
+<!-- ##### MACRO HILDON_INCREASE_KEY ##### -->
<para>
</para>
-@self:
-@Returns:
-<!-- ##### FUNCTION hildon_app_set_zoom ##### -->
+<!-- ##### MACRO HILDON_DECREASE_KEY ##### -->
<para>
</para>
-@self:
-@newzoom:
-<!-- ##### FUNCTION hildon_app_get_zoom ##### -->
+<!-- ##### MACRO HILDON_TOOLBAR_MODIFIERS ##### -->
+<para>
+
+</para>
+
+
+
+<!-- ##### MACRO HILDON_KEYEVENT_IS_MENU_KEY ##### -->
+<para>
+
+</para>
+
+@keyevent:
+
+
+<!-- ##### MACRO HILDON_KEYEVENT_IS_HOME_KEY ##### -->
+<para>
+
+</para>
+
+@keyevent:
+
+
+<!-- ##### MACRO HILDON_KEYEVENT_IS_TOOLBAR_KEY ##### -->
+<para>
+
+</para>
+
+@keyevent:
+
+
+<!-- ##### MACRO HILDON_KEYEVENT_IS_FULLSCREEN_KEY ##### -->
+<para>
+
+</para>
+
+@keyevent:
+
+
+<!-- ##### MACRO HILDON_KEYEVENT_IS_INCREASE_KEY ##### -->
+<para>
+
+</para>
+
+@keyevent:
+
+
+<!-- ##### MACRO HILDON_KEYEVENT_IS_DECREASE_KEY ##### -->
+<para>
+
+</para>
+
+@keyevent:
+
+
+<!-- ##### MACRO TRANSIENCY_MAXITER ##### -->
+<para>
+
+</para>
+
+
+
+<!-- ##### FUNCTION hildon_app_get_type ##### -->
<para>
</para>
-@self:
@Returns:
-<!-- ##### FUNCTION hildon_app_get_default_font ##### -->
+<!-- ##### FUNCTION hildon_app_new ##### -->
<para>
</para>
-@self:
@Returns:
-<!-- ##### FUNCTION hildon_app_get_zoom_font ##### -->
+<!-- ##### FUNCTION hildon_app_new_with_appview ##### -->
<para>
</para>
-@self:
+@appview:
@Returns:
-<!-- ##### FUNCTION hildon_app_set_two_part_title ##### -->
+<!-- ##### FUNCTION hildon_app_set_appview ##### -->
<para>
</para>
@self:
-@istwoparttitle:
+@appview:
-<!-- ##### FUNCTION hildon_app_get_two_part_title ##### -->
+<!-- ##### FUNCTION hildon_app_get_appview ##### -->
<para>
</para>
HildonAppView
<!-- ##### SECTION Short_Description ##### -->
-A widget which present one view of an application.
+
<!-- ##### SECTION Long_Description ##### -->
<para>
-A widget which present one view of an application.
-Application can have many different views and the appview helps to organize.
-It has automatic fullscreen and menu handling. It also helps to handle components
-like a toolbar.
+</para>
+
+<para>
<informalexample>
<programlisting>
HildonCalendarPopup
<!-- ##### SECTION Short_Description ##### -->
-#HildonCalendarPopup is a dialog which contains a GtkCalendar.
+
<!-- ##### SECTION Long_Description ##### -->
<para>
-#HildonCalendarPopup is a dialog which contains a GtkCalendar.
-It also contains arrow buttons for changing month/year. The
-earliest possible date is 1/1/1980 and the latest date 31/12/2100.
-If navigating with keyboard to a date that is not in the current
-month the calendar moves to the corresponding month. If the new
-date would be unallowed then an information banner will be shown.
-
-The usage of CalendarPopup is shown in the following code. This function
-should be connect to eg. button-press-event.
<informalexample>
<programlisting>
...
#GtkCalendar
</para>
+<!-- ##### SECTION Stability_Level ##### -->
+
+
<!-- ##### MACRO HILDON_CALENDAR_POPUP_TYPE ##### -->
<para>
</para>
+<!-- ##### SECTION Stability_Level ##### -->
+
+
<!-- ##### ENUM HildonCaptionStatus ##### -->
<para>
HildonColorButton
<!-- ##### SECTION Short_Description ##### -->
-HildonColorButton is a widget to open HildonColorSelector.
+
<!-- ##### SECTION Long_Description ##### -->
<para>
-HildonColorButton is a widget to open HildonColorSelector.
-The color field in the button shows the selected color.
-The current color is set as a property to the button.
-The property name is "color" and it's type is GtkColor.
-
<informalexample>
<programlisting>
HildonColorButton *cbutton;
</para>
+<!-- ##### SECTION Stability_Level ##### -->
+
+
<!-- ##### STRUCT HildonColorButtonPrivate ##### -->
<para>
HildonColorSelector
<!-- ##### SECTION Short_Description ##### -->
-A widget for selecting a color.
+
<!-- ##### SECTION Long_Description ##### -->
<para>
-#HildonColorSelector allows a selection of a color. #HildonColorSelector
-consists of a control that displays the default palette of 16 colors and
-a control that can be opened to select a custom color from a 16M color
-palette.
+
</para>
<para>
-Here's a simple example for using a color selector.
+Here is an example for using a color selector.
<informalexample>
<programlisting>
</para>
+<!-- ##### SECTION Stability_Level ##### -->
+
+
<!-- ##### STRUCT HildonColorSelectorPriv ##### -->
<para>
HildonControlbar
<!-- ##### SECTION Short_Description ##### -->
-A widget that allows increasing or decreasing a value within a pre-defined
-range.
+
<!-- ##### SECTION Long_Description ##### -->
<para>
-#HildonControlbar is a horizontally positioned widget that allows increasing
-or decreasing a value within a pre-defined range. The amount of steps in a
-#HildonControlbar can be changed.
+
</para>
<para>
-Here's a simple example that creates a control bar and initializes it.
+Here is an example that creates a control bar and initializes it.
<informalexample>
<programlisting>
</para>
+<!-- ##### SECTION Stability_Level ##### -->
+
+
<!-- ##### FUNCTION hildon_controlbar_new ##### -->
<para>
@max:
-<!-- ##### SIGNAL HildonControlbar::end-reached ##### -->
-<para>
-
-</para>
-
-@hildoncontrolbar: the object which received the signal.
-@arg1:
-
-<!-- ##### ARG HildonControlbar:max ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG HildonControlbar:min ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG HildonControlbar:value ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG HildonControlbar:inner-border-width ##### -->
-<para>
-
-</para>
-
HildonDateEditor
<!-- ##### SECTION Short_Description ##### -->
-HildonDateEditor is a simple widget with three entry field (day, month,
-year) and a icon (eventbox) the clicking of which opens up a
-HildonCalendarPopup.
+
<!-- ##### SECTION Long_Description ##### -->
<para>
-HildonDateEditor is a simple widget with three entry field (day, month,
-year) and a icon (eventbox) the clicking of which opens up a
-HildonCalendarPopup.
-
<informalexample>
<programlisting>
gint y, m, d;
</para>
+<!-- ##### SECTION Stability_Level ##### -->
+
+
<!-- ##### MACRO HILDON_DATE_EDITOR_TYPE ##### -->
<para>
@Returns:
-<!-- ##### SIGNAL HildonDateEditor::date-error ##### -->
-<para>
-
-</para>
-
-@hildondateeditor: the object which received the signal.
-@arg1:
-@Returns:
-
-<!-- ##### ARG HildonDateEditor:day ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG HildonDateEditor:max-year ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG HildonDateEditor:min-year ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG HildonDateEditor:month ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG HildonDateEditor:year ##### -->
-<para>
-
-</para>
-
hildon-dialoghelp
<!-- ##### SECTION Short_Description ##### -->
-HildonDialogHelp is used to show a normal dialog which contains a button to open a help if so is needed.
+
<!-- ##### SECTION Long_Description ##### -->
<para>
-HildonDialogHelp is used to show a normal dialog which contains a button to open a help if so is needed.
+
</para>
<!-- ##### SECTION See_Also ##### -->
</para>
+<!-- ##### SECTION Stability_Level ##### -->
+
+
<!-- ##### FUNCTION gtk_dialog_help_enable ##### -->
<para>
HildonFileDetailsDialog
<!-- ##### SECTION Short_Description ##### -->
-#HildonFileDetailsDialog is used to show details of a file.
+
<!-- ##### SECTION Long_Description ##### -->
<para>
-#HildonFileDetailsDialog is used to show details of a file.
-
-Here's a simple example that creates and opens a #HildonFileDetailsDialog.
+Here is an example that creates and opens a #HildonFileDetailsDialog.
<informalexample>
<programlisting>
</para>
+<!-- ##### SECTION Stability_Level ##### -->
+
+
<!-- ##### STRUCT HildonFileDetailsDialogPrivate ##### -->
<para>
@Returns:
-<!-- ##### ARG HildonFileDetailsDialog:additional-tab ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG HildonFileDetailsDialog:additional-tab-label ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG HildonFileDetailsDialog:model ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG HildonFileDetailsDialog:show-tabs ##### -->
-<para>
-
-</para>
-
HildonFileHandlingNote
<!-- ##### SECTION Short_Description ##### -->
-Notification presented when a move operation is in progress.
+
<!-- ##### SECTION Long_Description ##### -->
<para>
-Notification presented when a move operation is in progress.
-The notification uses a progress bar to indicate the progress of the operation.
-For operation containing multiple items, a separator progress bar is shown
-for each item. The notification has single button, which allowes to stop
-the action.
-
<informalexample>
<programlisting>
</para>
+<!-- ##### SECTION Stability_Level ##### -->
+
+
<!-- ##### FUNCTION hildon_file_handling_note_new_moving ##### -->
<para>
HildonFindToolbar
<!-- ##### SECTION Short_Description ##### -->
-A special toolbar to be used with HildonAppView.
+
<!-- ##### SECTION Long_Description ##### -->
<para>
-HildonFindToolbar is a predefined toolbar for text searching purpose. It contains a GtkListStore which
-has the text items that the user has searched. But once the application is terminated, or HildonFindToolbar is trashed. Programmer
- is responsible for getting the GtkListStore through property "list", if he/she wants to use the information in the future.
- And through the same property, programmer is able to set the GtkListStore. Note, once the search button is pressed, string in the
- GtkComboxEntry is automatically added to the existing model, unless it is empty.
+
</para>
<!-- ##### SECTION See_Also ##### -->
HildonFontSelectionDialog
<!-- ##### SECTION Short_Description ##### -->
-A widget is used to select a font with certain properties
+
<!-- ##### SECTION Long_Description ##### -->
<para>
-Font selection dialog provides the user with the possiblity to
-choose a different font family, font size, font color, font
-weight(bold or not bold), font style(italic or not italic),
-underline, strikethrough, and position(normal, superscript
-or subscript).
</para>
<!-- ##### SECTION See_Also ##### -->
</para>
+<!-- ##### SECTION Stability_Level ##### -->
+
+
<!-- ##### FUNCTION hildon_font_selection_dialog_get_font ##### -->
<para>
@text:
-<!-- ##### ARG HildonFontSelectionDialog:bold ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG HildonFontSelectionDialog:bold-set ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG HildonFontSelectionDialog:color ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG HildonFontSelectionDialog:color-set ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG HildonFontSelectionDialog:family ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG HildonFontSelectionDialog:family-set ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG HildonFontSelectionDialog:italic ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG HildonFontSelectionDialog:italic-set ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG HildonFontSelectionDialog:position ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG HildonFontSelectionDialog:position-set ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG HildonFontSelectionDialog:preview-text ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG HildonFontSelectionDialog:size ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG HildonFontSelectionDialog:size-set ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG HildonFontSelectionDialog:strikethrough ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG HildonFontSelectionDialog:strikethrough-set ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG HildonFontSelectionDialog:underline ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG HildonFontSelectionDialog:underline-set ##### -->
-<para>
-
-</para>
-
HildonGetPasswordDialog
<!-- ##### SECTION Short_Description ##### -->
-HildonGetPasswordDialog is used to get a password.
+
<!-- ##### SECTION Long_Description ##### -->
<para>
-HildonGetPasswordDialog is used to get a password.
<informalexample>
<programlisting>
</para>
+<!-- ##### SECTION Stability_Level ##### -->
+
+
<!-- ##### MACRO HILDON_GET_PASSWORD_DIALOG_TITLE ##### -->
<para>
@max_characters:
-<!-- ##### ARG HildonGetPasswordDialog:caption-label ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG HildonGetPasswordDialog:domain ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG HildonGetPasswordDialog:max-characters ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG HildonGetPasswordDialog:numbers-only ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG HildonGetPasswordDialog:password ##### -->
-<para>
-
-</para>
-
</para>
+<!-- ##### SECTION Stability_Level ##### -->
+
+
HildonGridItem
<!-- ##### SECTION Short_Description ##### -->
-#HildonGridItem is indeded to be used with #HildonGrid.
+
<!-- ##### SECTION Long_Description ##### -->
<para>
-#HildonGridItem is an uninteractive widget representing item on #HildonGrid.
-Each item has an icon and a label. Depending on current style, icon can be
-either above or to the left of the label.
</para>
#HildonGrid
</para>
+<!-- ##### SECTION Stability_Level ##### -->
+
+
<!-- ##### ENUM HildonGridPositionType ##### -->
<para>
HildonGrid
<!-- ##### SECTION Short_Description ##### -->
-#HildonGrid is intended to be used where ever a number of single tap
-activatable items need to be presented (e.g. Control Panel applets).
+
<!-- ##### SECTION Long_Description ##### -->
<para>
-HildonGrid is a set of application-defineable items that are presented in a
-table. The form of this table is selected from two modes; large icon mode and
-small icon mode.
-
-In large icon mode, the Grid View items are presented with a large icon and a
-label underneath it. In small icon mode, the items are presented with a small
-icon and a label on the right side of the icon.
-
-The label of an item is displayed within a band of colour displayed as a
-background colour as wide as the maximum text width. This allows the text to
-have focus as well as be legible when displayed upon a black or dark background
-image. Long names are truncated with an ellipsis ("...") appended.
-</para>
-<para>
<informalexample>
Example:
<programlisting>
#HildonGridItem
</para>
+<!-- ##### SECTION Stability_Level ##### -->
+
+
<!-- ##### FUNCTION hildon_grid_new ##### -->
<para>
@item:
-<!-- ##### SIGNAL HildonGrid::activate-child ##### -->
-<para>
-
-</para>
-
-@hildongrid: the object which received the signal.
-@arg1:
-
-<!-- ##### SIGNAL HildonGrid::popup-context-menu ##### -->
-<para>
-
-</para>
-
-@hildongrid: the object which received the signal.
-@arg1:
-@arg2:
-@arg3:
-@Returns:
-
-<!-- ##### ARG HildonGrid:empty-label ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG HildonGrid:scrollbar-position ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG HildonGrid:style ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG HildonGrid:emblem-size ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG HildonGrid:icon-size ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG HildonGrid:item-height ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG HildonGrid:item-hspacing ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG HildonGrid:item-vspacing ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG HildonGrid:item-width ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG HildonGrid:label-height ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG HildonGrid:label-hspacing ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG HildonGrid:label-pos ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG HildonGrid:label-vspacing ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG HildonGrid:n-columns ##### -->
-<para>
-
-</para>
-
HildonHVolumebar
<!-- ##### SECTION Short_Description ##### -->
-A widget that displays a horizontal volume bar.
+
<!-- ##### SECTION Long_Description ##### -->
<para>
-The #HildonHVolumebar widget displays a horizontal volume bar that allows
-increasing or decreasing volume within a pre-defined range, and muting
-the volume by clicking on a specific mute icon.
+
</para>
<para>
-Here's a simple example that creates a horizontal volume bar and connects
+Here is an example that creates a horizontal volume bar and connects
both its signals:
<informalexample>
#HildonVVolumebar
</para>
+<!-- ##### SECTION Stability_Level ##### -->
+
+
<!-- ##### FUNCTION hildon_hvolumebar_new ##### -->
<para>
</para>
+<!-- ##### SECTION Stability_Level ##### -->
+
+
<!-- ##### MACRO HILDON_INPUT_MODE_HINT ##### -->
<para>
+<!-- ##### MACRO HILDON_AUTOCAP ##### -->
+<para>
+
+</para>
+
+
+
<!-- ##### ENUM HildonInputModeHint ##### -->
<para>
HildonInsertObjectDialog
<!-- ##### SECTION Short_Description ##### -->
-A dialog that enables the user to embed an object into rich text.
+
<!-- ##### SECTION Long_Description ##### -->
<para>
-#HildonInsertObjectDialog is a dialog that enables the user to insert a
-new or existing object into a Multi-line (Rich Text) Editor as an
-embedded object.
+
</para>
<para>
-Here's a simple example for using #HildonInsertObjectDialog:
+Here is an example for using #HildonInsertObjectDialog:
<informalexample>
<programlisting>
</para>
+<!-- ##### SECTION Stability_Level ##### -->
+
+
<!-- ##### MACRO HILDON_RESPONSE_INSERT_EXISTING ##### -->
<para>
</para>
-<!-- ##### ARG HildonFileDetailsDialog:model ##### -->
<para>
</para>
</para>
+<!-- ##### ARG HildonFileDetailsDialog:additional-tab ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### ARG HildonFileDetailsDialog:additional-tab-label ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### ARG HildonFileDetailsDialog:model ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### ARG HildonFileDetailsDialog:show-tabs ##### -->
+<para>
+
+</para>
+
+
<!-- ##### STRUCT HildonFileHandlingNote ##### -->
<para>
HildonNamePasswordDialog
<!-- ##### SECTION Short_Description ##### -->
-A widget which allows a user to enter username and password
-<!-- ##### SECTION Long_Description ##### -->
-<para>
-Used to enter a username and password when accessing a password protected function.
-</para>
+<!-- ##### SECTION Long_Description ##### -->
<para>
<informalexample>
Example:
</para>
+<!-- ##### SECTION Stability_Level ##### -->
+
+
<!-- ##### MACRO HILDON_NAME_PASSWORD_DIALOG_TITLE ##### -->
<para>
@domain:
-<!-- ##### ARG HildonNamePasswordDialog:content ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG HildonNamePasswordDialog:name ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG HildonNamePasswordDialog:password ##### -->
-<para>
-
-</para>
-
HildonNote
<!-- ##### SECTION Short_Description ##### -->
-A widget to ask confirmation from the user.
+
<!-- ##### SECTION Long_Description ##### -->
<para>
-Notes are used to have a confirmation (Ok/Cancel/etc.) from the user.
-A simple note contains an information text and an Ok-button to be pressed.
-Additional features can be e.g. progressbars or animations.
-
<informalexample>
<programlisting>
</para>
+<!-- ##### SECTION Stability_Level ##### -->
+
+
<!-- ##### ENUM HildonNoteType ##### -->
<para>
</para>
-@Returns:
-
+@Returns: GType
-<!-- ##### ARG HildonNote:description ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG HildonNote:icon ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG HildonNote:note-type ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG HildonNote:progressbar ##### -->
-<para>
-
-</para>
HildonNumberEditor
<!-- ##### SECTION Short_Description ##### -->
-HildonNumberEditor is used to set a number.
+
<!-- ##### SECTION Long_Description ##### -->
<para>
-HildonNumberEditor is used to set a number from a specific range. There's two buttons to scroll the value in number field, also manual input is possible.
-
<informalexample>
<programlisting>
number_editor = hildon_number_editor_new (-250, 500);
</para>
+<!-- ##### SECTION Stability_Level ##### -->
+
+
<!-- ##### ENUM HildonNumberEditorErrorType ##### -->
<para>
@value:
-<!-- ##### SIGNAL HildonNumberEditor::range-error ##### -->
-<para>
-
-</para>
-
-@hildonnumbereditor: the object which received the signal.
-@arg1:
-@Returns:
-
-<!-- ##### ARG HildonNumberEditor:value ##### -->
-<para>
-
-</para>
-
HildonRangeEditor
<!-- ##### SECTION Short_Description ##### -->
-HildonRangeEditor is used to ask a value from a specific limits.
+
<!-- ##### SECTION Long_Description ##### -->
<para>
-HildonRangeEditor is used to ask a value from a specific limits.
-
<informalexample>
<programlisting>
</para>
+<!-- ##### SECTION Stability_Level ##### -->
+
+
<!-- ##### MACRO HILDON_RANGE_EDITOR_TYPE ##### -->
<para>
@Returns:
-<!-- ##### ARG HildonRangeEditor:higher ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG HildonRangeEditor:lower ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG HildonRangeEditor:max ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG HildonRangeEditor:min ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG HildonRangeEditor:separator ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG HildonRangeEditor:hildon-range-editor-entry-alignment ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG HildonRangeEditor:hildon-range-editor-separator-padding ##### -->
-<para>
-
-</para>
-
hildon-scroll-area
<!-- ##### SECTION Short_Description ##### -->
-@GtkScrollArea is a helper to create Maemo specific views,
-which are using scrollable area.
+
<!-- ##### SECTION Long_Description ##### -->
<para>
-When application developer needs a view which contains multiple
-components, from which some has built-in @GtkScrolledWindow handling.
-(eg. @GtkTreeView) These widgets creates a problem which can be seen as
-unfunctional scrolling. @GtkScrollArea creates an area which handles
-these scrolling problems.
<informalexample>
<programlisting>
</para>
+<!-- ##### SECTION Stability_Level ##### -->
+
+
<!-- ##### FUNCTION hildon_scroll_area_new ##### -->
<para>
HildonSeekbar
<!-- ##### SECTION Short_Description ##### -->
-HildonSeekbar is used to seek a place from a content. Can be used eg. to browse a mp3 track.
+
<!-- ##### SECTION Long_Description ##### -->
<para>
-HildonSeekbar is used to seek a place from a content. Can be used eg. to browse a mp3 track.
-
<informalexample>
<programlisting>
GtkWidget *seekbar = hildon_seekbar_new();
</para>
+<!-- ##### SECTION Stability_Level ##### -->
+
+
<!-- ##### FUNCTION hildon_seekbar_new ##### -->
<para>
@Returns:
-<!-- ##### ARG HildonSeekbar:fraction ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG HildonSeekbar:position ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG HildonSeekbar:total-time ##### -->
-<para>
-
-</para>
-
HildonSetPasswordDialog
<!-- ##### SECTION Short_Description ##### -->
-HildonSetPasswordDialog is used to receive a new password from user. (User sets the password)
+
<!-- ##### SECTION Long_Description ##### -->
<para>
-HildonSetPasswordDialog is used to receive a new password from user. (User sets the password)
<informalexample>
Example:
</para>
+<!-- ##### SECTION Stability_Level ##### -->
+
+
<!-- ##### MACRO HILDON_SET_PASSWORD_DIALOG_TITLE ##### -->
<para>
@domain:
-<!-- ##### ARG HildonSetPasswordDialog:domain ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG HildonSetPasswordDialog:modify-protection ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG HildonSetPasswordDialog:password ##### -->
-<para>
-
-</para>
-
HildonSortDialog
<!-- ##### SECTION Short_Description ##### -->
-A widget for defining sorting order of items.
+
<!-- ##### SECTION Long_Description ##### -->
<para>
-Sort Dialog is used to define the order in which items are shown in a list.
+
</para>
<para>
<informalexample>
-Example:
+Here is an example for using HildonSortDialog.
<programlisting>
HildonSortDialog *sort_dialog = HILDON_SORT_DIALOG(
hildon_sort_dialog_new( parent ));
</para>
+<!-- ##### SECTION Stability_Level ##### -->
+
+
<!-- ##### FUNCTION hildon_sort_dialog_new ##### -->
<para>
HildonTelephoneEditor
<!-- ##### SECTION Short_Description ##### -->
-A widget which allows a user to enter a telephone number
+
<!-- ##### SECTION Long_Description ##### -->
<para>
-A Single Line Editor widget which allows user to enter a telephone number. There are two modes to choose from (corce/free format). Coerce format has three fields which are placed horizontally. Fields are country code, area code and number. When nothing is inputted to the fields assisting text is displayed in a field. Tapping on the field highlights the field and allows user to input numbers.
-</para>
-<para>
-The widget is used where a user should enter a phone number. Free format should be used wherever possible as it enables the user to enter the phone number in the format she likes in addition to entering DTMF strings as a part of the phone number. The format can not be changed at runtime.
</para>
<para>
</para>
+<!-- ##### SECTION Stability_Level ##### -->
+
+
<!-- ##### MACRO HILDON_TELEPHONE_EDITOR_TYPE ##### -->
<para>
@number:
-<!-- ##### ARG HildonTelephoneEditor:area ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG HildonTelephoneEditor:country ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG HildonTelephoneEditor:number ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG HildonTelephoneEditor:set-format ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG HildonTelephoneEditor:show-border ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG HildonTelephoneEditor:show-plus ##### -->
-<para>
-
-</para>
-
HildonTimeEditor
<!-- ##### SECTION Short_Description ##### -->
-#HildonTimeEditor is a simple widget with entries for hours and minutes and a
-pm/am indicator as well as a button which pops up a #HildonTimePicker dialog
-window.
+
<!-- ##### SECTION Long_Description ##### -->
<para>
-#HildonTimeEditor is a simple widget with entries for hours and minutes and a
-pm/am indicator as well as a button which pops up a #HildonTimePicker dialog
-window.
<informalexample>
<programlisting>
</para>
+<!-- ##### SECTION Stability_Level ##### -->
+
+
<!-- ##### FUNCTION hildon_time_editor_new ##### -->
<para>
@Returns:
-<!-- ##### ARG HildonTimeEditor:duration-max ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG HildonTimeEditor:duration-min ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG HildonTimeEditor:duration-mode ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG HildonTimeEditor:show-seconds ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG HildonTimeEditor:ticks ##### -->
-<para>
-
-</para>
-
HildonTimePicker
<!-- ##### SECTION Short_Description ##### -->
-#HildonTimePicker is a dialog popup widget which lets the user set a time.
+
<!-- ##### SECTION Long_Description ##### -->
<para>
-#HildonTimePicker is a dialog popup widget which lets the user set a time.
-using up/down arrows on hours and minutes. There are two arrows for minutes,
-so that minutes can be added also in 10min steps.
-
-The following code shows how the widget is used.
<informalexample>
<programlisting>
#HildonTimeEditor
</para>
+<!-- ##### SECTION Stability_Level ##### -->
+
+
<!-- ##### STRUCT HildonTimePickerPrivate ##### -->
<para>
@minutes:
-<!-- ##### ARG HildonTimePicker:minutes ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG HildonTimePicker:arrow-height ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG HildonTimePicker:arrow-width ##### -->
-<para>
-
-</para>
-
HildonVolumebar
<!-- ##### SECTION Short_Description ##### -->
-Base class for widgets that display a volume bar.
+
<!-- ##### SECTION Long_Description ##### -->
<para>
-#HildonVolumebar is a base class for widgets that display a volume bar that
-allows increasing or decreasing volume within a pre-defined range, and muting
-the volume by clicking on a specific mute icon.
+
</para>
<!-- ##### SECTION See_Also ##### -->
#HildonHVolumebar,#HildonVVolumebar
</para>
+<!-- ##### SECTION Stability_Level ##### -->
+
+
<!-- ##### FUNCTION hildon_volumebar_set_level ##### -->
<para>
@Returns:
-<!-- ##### SIGNAL HildonVolumebar::level-changed ##### -->
-<para>
-
-</para>
-
-@hildonvolumebar: the object which received the signal.
-
-<!-- ##### SIGNAL HildonVolumebar::mute-toggled ##### -->
-<para>
-
-</para>
-
-@hildonvolumebar: the object which received the signal.
-
-<!-- ##### ARG HildonVolumebar:can-focus ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG HildonVolumebar:has-mute ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG HildonVolumebar:level ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG HildonVolumebar:mute ##### -->
-<para>
-
-</para>
-
HildonVVolumebar
<!-- ##### SECTION Short_Description ##### -->
-A widget that displays a vertical volume bar.
+
<!-- ##### SECTION Long_Description ##### -->
<para>
-The #HildonVVolumebar widget displays a vertical volume bar that allows
-increasing or decreasing volume within a pre-defined range, and muting
-the volume by clicking on a specific mute icon.
+
</para>
<para>
-Here's a simple example that creates a vertical volume bar and connects
-both its signals:
+Here is an example that creates a vertical volume bar and connects
+both its signals.
<informalexample>
<programlisting>
#HildonHVolumebar
</para>
+<!-- ##### SECTION Stability_Level ##### -->
+
+
<!-- ##### FUNCTION hildon_vvolumebar_new ##### -->
<para>
HildonWeekdayPicker
<!-- ##### SECTION Short_Description ##### -->
-A widget for selecting weekday(s)
+
<!-- ##### SECTION Long_Description ##### -->
<para>
-Weekday picker supports non-mutually exclusive selection of days of the week. Selected days of the week are shown with a pushed-in effect.
-</para>
-<para>
-Weekday picker is used where users are required to pick days on which 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.
</para>
<para>
</para>
+<!-- ##### SECTION Stability_Level ##### -->
+
+
<!-- ##### MACRO HILDON_WEEKDAY_PICKER_TYPE ##### -->
<para>
@Returns:
-<!-- ##### SIGNAL HildonWeekdayPicker::selection-changed ##### -->
-<para>
-
-</para>
-
-@hildonweekdaypicker: the object which received the signal.
-@arg1:
-
HildonWizardDialog
<!-- ##### SECTION Short_Description ##### -->
-#HildonWizardDialog is a widget to create eg. a guided installation
-process.
+
<!-- ##### SECTION Long_Description ##### -->
<para>
-#HildonWizardDialog is a widget to create eg. a guided installation
-process. The dialog has four buttons to be used. It's parameters are
-the dialogs parent, the wizard dialog name, which is a part of title.
-Last parameter is a #GtkNotebook, which contains the content of wizard.
-This content is created by the application developer.
<informalexample>
<programlisting>
</para>
+<!-- ##### SECTION Stability_Level ##### -->
+
+
<!-- ##### STRUCT HildonWizardDialogPrivate ##### -->
<para>
/**
* hildon_add_home_dialog_new:
- * @parent: Parent window for the dialog.
- * @name: Name to show in the entry (or label, if @new_name is not NULL)
- * @new_name: Name to show in the new name entry. If this is not NULL
+ * @parent: parent window for the dialog
+ * @name: name to show in the entry (or label, if @new_name is not NULL)
+ * @new_name: name to show in the new name entry. If this is not NULL
* the widget acts as a RenameShortcutDialog.
*
* Creates a new Add to Home dialog or Rename Shortcut dialog.
*
- * Returns the new dialog.
+ * Returns: the new dialog.
*/
GtkWidget *hildon_add_home_dialog_new(GtkWindow * parent,
const gchar * name,
/**
* hildon_add_home_dialog_get_name:
- * @dialog: The dialog.
+ * @dialog: the dialog
*
- * Returns the name the user has entered in the entry.
- *
- * Returns a string the user has entered.
+ * Returns: the string the user has entered in the entry
*/
const gchar *hildon_add_home_dialog_get_name(HildonAddHomeDialog * dialog)
{
*
*/
-/*
- * @file hildon-app.c
- *
- * This file implements the HildonApp widget
+/**
+ * SECTION:hildon-app
+ * @short_description: A base widget to present application
+ * @see_also: #HildonAppView
*
+ * #HildonApp is the base for any hildon application.
+ * It controls basic looks and functionality of an application, like a title.
*/
#include <gdk/gdk.h>
/* FIXME: Zoom level is deprecated, should be removed */
/**
* hildon_zoom_level_get_type:
- * @Returns : GType of #HildonZoomLevel
*
* Initialises, and returns the type of a hildon zoom level
+ *
+ * Returns: GType of #HildonZoomLevel
*/
GType
*
* Creates a new #HildonApp
*
- * Return value: Pointer to a new @HildonApp structure.
- **/
+ * Returns: pointer to a new #HildonApp structure
+ */
GtkWidget *
hildon_app_new (void)
{
/**
* hildon_app_new_with_appview:
- * @appview : A @HildonAppView
+ * @appview : a #HildonAppView
*
* Creates an app, and sets it's initial appview.
*
- * Return value: Pointer to a new @HildonApp structure.
- **/
+ * Returns: pointer to a new #HildonApp structure
+ */
GtkWidget *
hildon_app_new_with_appview (HildonAppView *appview)
{
/**
* hildon_app_get_appview:
- * @self : A @HildonApp
+ * @self : a #HildonApp
*
* Gets the currently shown appview.
*
- * Return value: The currently shown appview in this HildonApp.
- * If no appview is currently set for this HildonApp,
- * returns NULL.
- **/
+ * Returns: the currently shown appview in this HildonApp.
+ * If no appview is currently set for this HildonApp,
+ * returns NULL.
+ */
HildonAppView *
hildon_app_get_appview (HildonApp *self)
{
/**
* hildon_app_set_appview:
- * @self : A @HildonApp
- * @appview : A @HildonAppView.
+ * @self : a #HildonApp
+ * @appview : a #HildonAppView
*
* Sets (switches to) appview.
*/
/**
* hildon_app_set_title:
- * @self : A @HildonApp
- * @newtitle : The new title assigned to the application.
+ * @self : a #HildonApp
+ * @newtitle : the new title assigned to the application
*
* Sets title of the application.
- **/
+ */
void
hildon_app_set_title (HildonApp *self, const gchar *newtitle)
{
/**
* hildon_app_get_title:
- * @self : A @HildonApp
+ * @self : a #HildonApp
*
* Gets the title of the application.
*
- * Return value: The title currently assigned to the application. This
- * value is not to be freed or modified by the calling application.
- **/
+ * Returns: the title currently assigned to the application. This
+ * value is not to be freed or modified by the calling application
+ */
const gchar *
hildon_app_get_title (HildonApp *self)
{
/* FIXME: Zoom is deprecated, remove */
/**
* hildon_app_set_zoom:
- * @self : A @HildonApp
- * @newzoom: The zoom level of type @HildonZoomLevel to be assigned to an
- * application.
+ * @self : a #HildonApp
+ * @newzoom: the zoom level of type #HildonZoomLevel to be assigned to an
+ * application
*
* Sets the zoom level. Warning! This function is deprecated and
* should not be used. It's lecacy stuff from ancient specs.
- **/
+ */
void
hildon_app_set_zoom (HildonApp *self, HildonZoomLevel newzoom)
{
/**
* hildon_app_get_zoom:
- * @self : A @HildonApp
+ * @self : a #HildonApp
*
* Gets the zoom level. Warning! This function is deprecated and
* should not be used. It's lecacy stuff from ancient specifications.
*
- * Return value: Returns the zoom level of the Hildon application. The
- * returned zoom level is of type @HildonZoomLevel.
- **/
+ * Returns: the zoom level of the Hildon application. The
+ * returned zoom level is of type #HildonZoomLevel.
+ */
HildonZoomLevel
hildon_app_get_zoom (HildonApp *self)
{
/**
* hildon_app_get_default_font:
- * @self : A @HildonApp
+ * @self : a #HildonApp
*
* Gets default font. Warning! This function is deprecated and should
* not be used. It's legacy stuff from ancient version of specification.
*
- * Return value: Pointer to PangoFontDescription for the default,
- * normal size font.
- **/
+ * Returns: pointer to PangoFontDescription for the default,
+ * normal size font
+ */
PangoFontDescription *
hildon_app_get_default_font (HildonApp *self)
{
/**
* hildon_app_get_zoom_font:
- * @self : A @HildonApp
+ * @self : a #HildonApp
*
* Gets the description of the default font. Warning! This function
* is deprecated and should not be used. It's legacy stuff from
* ancient specs.
*
- * Return value: Pointer to PangoFontDescription for the default,
- * normal size font.
- **/
+ * Returns: pointer to PangoFontDescription for the default,
+ * normal size font
+ */
PangoFontDescription *
hildon_app_get_zoom_font (HildonApp *self)
{
/**
* hildon_app_set_two_part_title:
- * @self : A @HildonApp
- * @istwoparttitle : A gboolean indicating wheter to activate
+ * @self : a #HildonApp
+ * @istwoparttitle : a gboolean indicating wheter to activate
* a title that has both the application title and application
- * view title separated by a triangle.
+ * view title separated by a triangle
*
* Sets the two part title.
*/
/**
* hildon_app_get_two_part_title:
- * @self : A @HildonApp
+ * @self : a #HildonApp
*
* Gets the 'twopart' represention of the title inside #HildonApp.
*
- * Return value: A boolean indicating wheter title shown has both
+ * Returns: a boolean indicating wheter title shown has both
* application, and application view title separated by a triangle.
- **/
+ */
gboolean
hildon_app_get_two_part_title (HildonApp *self)
{
/**
* hildon_app_set_autoregistration
- * @self : a @HildonApp
- * @auto_reg : Whether the (app)view autoregistration should be active
+ * @self : a #HildonApp
+ * @auto_reg : whether the (app)view autoregistration should be active
*
* Controls the autoregistration/unregistration of (app)views.
- **/
+ */
void hildon_app_set_autoregistration(HildonApp *self, gboolean auto_reg)
{
/**
* hildon_app_register_view:
- * @self : a @HildonApp
- * @view_ptr : Pointer to the view instance to be registered
+ * @self : a #HildonApp
+ * @view_ptr : pointer to the view instance to be registered
*
* Registers a new view. For appviews, this can be done automatically
* if autoregistration is set.
/**
* hildon_app_register_view_with_id:
- * @self : a @HildonApp
- * @view_ptr : Pointer to the view instance to be registered
- * @view_id : The ID of the view
+ * @self : a #HildonApp
+ * @view_ptr : pointer to the view instance to be registered
+ * @view_id : the ID of the view
*
* Registers a new view. Allows the application to specify any ID.
*
- * Return value: TRUE if the view registration succeeded, FALSE otherwise.
+ * Returns: TRUE if the view registration succeeded, FALSE otherwise.
* The probable cause of failure is that view with that ID
* already existed.
*/
/**
* hildon_app_unregister_view:
- * @self : A @HildonApp
- * @view_ptr : Pointer to the view instance to be unregistered
+ * @self : a #HildonApp
+ * @view_ptr : pointer to the view instance to be unregistered
*
* Unregisters a view from HildonApp. Done usually when a view is
* destroyed. For appviews, this is can be automatically
/**
* hildon_app_unregister_view_with_id:
- * @self : A @HildonApp
- * @view_id : The ID of the view that should be unregistered
+ * @self : a #HildonApp
+ * @view_id : the ID of the view that should be unregistered
*
* Unregisters a view with specified ID, if it exists.
*/
/**
* hildon_app_notify_view_changed:
- * @self : A @HildonApp
- * @view_ptr : Pointer to the view that is switched to
+ * @self : a #HildonApp
+ * @view_ptr : pointer to the view that is switched to
*
* Updates the X property that contains the currently active view
*/
/**
* hildon_app_find_view_id:
- * @self : a @HildonApp
- * @view_ptr : Pointer to the view whose ID we want to acquire
+ * @self : a #HildonApp
+ * @view_ptr : pointer to the view whose ID we want to acquire
*
- * Return value: The ID of the view, or 0 if not found.
+ * Returns: the ID of the view, or 0 if not found
*
* Allows mapping of view pointer to its view ID. If NULL is passed
* as the view pointer, returns the ID of the current view.
/**
* hildon_app_set_killable:
- * @self : A @HildonApp
- * @killability : Truth value indicating whether the app can be killed
+ * @self : a #HildonApp
+ * @killability : truth value indicating whether the app can be killed
*
* Updates information about whether the application can be killed or not by
* Task Navigator (i.e. whether its statesave is up to date)
* If @uim is NULL, unsets the current ui manager.
* The @HildonApp holds a reference to the ui manager until
* the @HildonApp is destroyed or unset.
- **/
+ */
void hildon_app_set_ui_manager(HildonApp *self, GtkUIManager *uim)
{
HildonAppPrivate *priv;
*
* Gets the #GtkUIManager assigned to the #HildonApp.
*
- * Return value: The #GtkUIManager assigned to this application
- * or null if no manager is assigned.
- **/
+ * Returns: the #GtkUIManager assigned to this application
+ * or null if no manager is assigned
+ */
GtkUIManager *hildon_app_get_ui_manager(HildonApp *self)
{
HildonAppPrivate *priv;
*
*/
+/**
+ * SECTION:hildon-appview
+ * @short_description: A widget which present one view of an application
+ * @see_also: #HildonApp
+ *
+ * #HildonAppView is a widget which presents one view of an application.
+ * Application can have many different views and the appview helps to organize.
+ * It has automatic fullscreen and menu handling. It also helps to handle
+ * components like a toolbar.
+ */
#include <memory.h>
#include <string.h>
/**
* hildon_appview_new:
- * @title: The application view title of the new @HildonAppView.
+ * @title:the application view title of the new @HildonAppView
*
* Use this function to create a new application view. The title will
* be set only if two-part-title is enabled on the @HildonApp.
*
- * Return value: A @HildonAppView.
+ * Returns: A #HildonAppView.
**/
GtkWidget *hildon_appview_new(const gchar * title)
{
/**
* hildon_appview_add_with_scrollbar
- * @self : A @HildonAppView
- * @child : A @GtkWidget
+ * @self : a @HildonAppView
+ * @child : a @GtkWidget
*
* Adds the @child to the @self(HildonAppView) and creates a vertical
- * scrollbar to it. Similar as adding first a @GtkScrolledWindow
+ * scrollbar to it. Similar as adding first a #GtkScrolledWindow
* and then the @child to it.
*/
void hildon_appview_add_with_scrollbar(HildonAppView * self,
/**
* hildon_appview_get_title:
- * @self : A @HildonAppView
+ * @self : a #HildonAppView
*
* Gets the title of given #HildonAppView.
*
- * Return value: The title of the application view.
- **/
+ * Returns: the title of the application view
+ */
const gchar *hildon_appview_get_title(HildonAppView * self)
{
g_return_val_if_fail(self && HILDON_IS_APPVIEW(self), "");
/**
* hildon_appview_set_title:
- * @self : A @HildonAppView
- * @newname : The new title of the application view.
+ * @self : a #HildonAppView
+ * @newname : the new title of the application view.
*
* Sets an title of an application view. The title is visible only if
- * two-part-title is enabled on the @HildonApp.
+ * two-part-title is enabled on the #HildonApp.
*
- **/
+ */
void hildon_appview_set_title(HildonAppView * self, const gchar * newname)
{
gchar *oldtitle;
/**
* hildon_appview_set_toolbar:
- * @self: A #HildonAppView
- * @toolbar: A #GtkToolbar
+ * @self: a #HildonAppView
+ * @toolbar: a #GtkToolbar
*
* Sets the #GtkToolbar to given #HildonAppView. This is, however, not a
* recommended way to set your toolbars. When you have multi toolbars, calling
* is responsible to pack his toolbars in the #GtkVBox, and #HildonAppView will
* take care of putting them at the right place.
*
- **/
+ */
#ifndef HILDON_DISABLE_DEPRECATED
void hildon_appview_set_toolbar(HildonAppView * self, GtkToolbar * toolbar)
{
#endif
/**
* hildon_appview_get_toolbar:
- * @self: A #HildonAppView
+ * @self: a #HildonAppView
*
* This function will only
* return the last widget that has been packed into the #GtkVBox in the public
* structure. Note this does not, however, mean that it is the bottom most
* toolbar.
*
- * Return value: The #GtkToolbar assigned to this application view.
+ * Return value: the #GtkToolbar assigned to this application view.
**/
#ifndef HILDON_DISABLE_DEPRECATED
GtkToolbar *hildon_appview_get_toolbar(HildonAppView * self)
#endif
/**
* hildon_appview_set_fullscreen:
- * @self: A @HildonAppView
- * @fullscreen: The new state of fullscreen mode. TRUE means fullscreen
+ * @self: a #HildonAppView
+ * @fullscreen: the new state of fullscreen mode. TRUE means fullscreen
* will be set. FALSE the opposite.
*
* Set the fullscreen state of given #HildonAppView class.
- **/
+ */
void hildon_appview_set_fullscreen(HildonAppView * self,
gboolean fullscreen)
{
/**
* hildon_appview_get_fullscreen:
- * @self: A @HildonAppView
+ * @self: a #HildonAppView
*
* Gets the current state of fullscreen mode.
*
- * Return value: The current state of fullscreen mode.
- **/
+ * Returns: the current state of fullscreen mode
+ */
gboolean hildon_appview_get_fullscreen(HildonAppView * self)
{
g_return_val_if_fail(self && HILDON_IS_APPVIEW(self), FALSE);
/**
* hildon_appview_get_fullscreen_key_allowed:
- * @self: A @HildonAppView
+ * @self: a #HildonAppView
*
* Check if fullscreening with a shortcut is allowed for given
* #HildonAppView.
*
- * Return value: Wheter it's possible to swith fullscreen on/off with
- * a shortcut key.
- **/
+ * Returns: wheter it's possible to swith fullscreen on/off with
+ * a shortcut key
+ */
gboolean hildon_appview_get_fullscreen_key_allowed(HildonAppView * self)
{
g_return_val_if_fail(self && HILDON_IS_APPVIEW(self), FALSE);
/**
* hildon_appview_set_fullscreen_key_allowed:
- * @self: A @HildonAppView
- * @allow: Wheter it's possible to swith fullscreen on/off with
- * a shortcut key.
+ * @self: a #HildonAppView
+ * @allow: wheter it's possible to swith fullscreen on/off with
+ * a shortcut key
*
* Sets given #HildonAppView whether to allow toggling fullscreen mode
* with a shortcut key.
- **/
+ */
void hildon_appview_set_fullscreen_key_allowed(HildonAppView * self,
gboolean allow)
{
*
* Gets the #GtMenu assigned to the #HildonAppview.
*
- * Return value: The #GtkMenu assigned to this application view.
- **/
+ * Returns: the #GtkMenu assigned to this application view
+ */
GtkMenu *hildon_appview_get_menu(HildonAppView * self)
{
g_return_val_if_fail(self && HILDON_IS_APPVIEW(self), NULL);
/**
* _hildon_appview_toggle_menu:
- * @self : A @HildonAppView
+ * @self : a #HildonAppView
* @button_event_time :
*
* This function should be only called from @HildonApp.
/**
* _hildon_appview_menu_visible
- * @self : A @HildonAppView
+ * @self: a #HildonAppView
*
* Checks whether the titlebar menu is currently visible
- * Return value : TRUE if the menu is visible, FALSE if not.
+ * Returns: TRUE if the menu is visible, FALSE if not
*/
gboolean _hildon_appview_menu_visible(HildonAppView * self)
/**
* hildon_appview_set_connected_adjustment
- * @self : A @HildonAppView
- * @adjustment : A new #GtkAdjustment set to reach to increase
- * / decrease hardware keys or NULL to unset.
+ * @self : #HildonAppView
+ * @adjustment : a new #GtkAdjustment set to reach to increase
+ * / decrease hardware keys or NULL to unset
*
* Sets a #GtkAdjustment which will change when increase/decrease buttons
* are pressed.
- **/
+ */
void hildon_appview_set_connected_adjustment (HildonAppView * self,
GtkAdjustment * adjustment)
{
/**
* hildon_appview_get_connected_adjustment
- * @self : A @HildonAppView
+ * @self : a #HildonAppView
*
- * Retrieves the @GtkAdjustment which is connected to this application view
+ * Retrieves the #GtkAdjustment which is connected to this application view
* and is changed with increase / decrease hardware buttons.
*
- * Return value: Currently connectd #GtkAdjustment assigned to this
- * application view or NULL if it's not set.
- **/
+ * Returns: currently connectd #GtkAdjustment assigned to this
+ * application view or NULL if it's not set
+ */
GtkAdjustment * hildon_appview_get_connected_adjustment (HildonAppView * self)
{
g_return_val_if_fail (HILDON_IS_APPVIEW (self), NULL);
/**
* hildon_appview_set_menu_ui
- * @self : A @HildonAppView
- * @ui_string : A @GtkUIManager ui description string
+ * @self : a #HildonAppView
+ * @ui_string : a #GtkUIManager ui description string
*
* Sets the ui description (xml) from which the UIManager creates menus
* (see @GtkUIManager for details on how to use it)
- **/
+ */
void hildon_appview_set_menu_ui(HildonAppView *self, const gchar *ui_string)
{
g_return_if_fail (HILDON_IS_APPVIEW (self));
/**
* hildon_appview_get_menu_ui
- * @self : A @HildonAppView
+ * @self : a #HildonAppView
*
* Sets the ui description (xml) from which the UIManager creates menus
- * (see @GtkUIManager for details on how to use it)
+ * (see #GtkUIManager for details on how to use it)
*
- * Return value: Currently set ui description
- *
- **/
+ * Returns: currently set ui description
+ */
const gchar *hildon_appview_get_menu_ui(HildonAppView *self)
{
g_return_val_if_fail (HILDON_IS_APPVIEW (self), NULL);
*
*/
-/* HILDON DOC
+/**
+ * SECTION:hildon-calendar-popup
* @shortdesc: CalendarPopup allows choosing a date from a popup calendar.
* @longdesc: The Calendar popup is a dialog that contains a GtkCalendar
* widget. The pop-up is cancelled by pressing the ESC key.
* </para><para>
*
* @seealso: #HildonDateEditor, #HildonTimeEditor
+ *
+ * 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.
*/
#ifdef HAVE_CONFIG_H
* selected date is specified by the parameters (year, month, day).
* If the specified date is invalid, the current date is used.
*
- * Return value: Pointer to a new @HildonCalendarPopup widget.
- **/
+ * Returns: new @HildonCalendarPopup widget
+ */
GtkWidget *hildon_calendar_popup_new(GtkWindow * parent, guint year,
guint month, guint day)
{
* @month: month
* @day: day
*
- * This function activates a new date on the calendar popup.
+ * activates a new date on the calendar popup.
**/
void
hildon_calendar_popup_set_date(HildonCalendarPopup * cal,
* @month: month
* @day: day
*
- * This function is used to get the currently selected year, month,
- * and day.
- **/
+ * Gets the currently selected year, month, and day.
+ */
void
hildon_calendar_popup_get_date(HildonCalendarPopup * cal,
guint * year, guint * month, guint * day)
*
*/
+/**
+ * SECTION:hildon-caption
+ * @short_description: A single-child container widget that precedes the
+ * contained widget with a field label and an optional icon
+ *
+ * #HildonCaption is a single-child container widget that precedes the
+ * contained widget with a field label and an optional icon. It allows
+ * grouping of several controls together. When a captioned widget has focus,
+ * both widget and caption label are displayed with active focus.
+ */
+
#include <gtk/gtkhbox.h>
#include <gtk/gtklabel.h>
#include <gtk/gtkimage.h>
/**
* hildon_caption_get_type:
- * @Returns : GType of #HildonCaption.
*
* Initialises, and returns the type of a hildon caption.
+ *
+ * @Returns: GType of #HildonCaption
*/
GType hildon_caption_get_type (void)
{
/**
* hildon_caption_set_sizegroup:
- * @caption : A #HildonCaption
- * @new_group : A #GtkSizeGroup
+ * @caption : a #HildonCaption
+ * @new_group : a #GtkSizeGroup
*
* Sets a #GtkSizeGroup of a given captioned control.
*
- * Deprecated: Use g_object_set, property "size_group".
+ * Deprecated: use g_object_set, property "size_group"
*/
void hildon_caption_set_sizegroup( const HildonCaption *self,
GtkSizeGroup *group )
/**
* hildon_caption_get_sizegroup:
- * @caption : A #HildonCaption
- * @Returns : A #GtkSizeGroup
+ * @caption : a #HildonCaption
*
* Query given captioned control for the #GtkSizeGroup assigned to it.
*
- * Deprecated: Use g_object_get, property "size_group".
+ * @Returns : a #GtkSizeGroup
+ *
+ * Deprecated: Use g_object_get, property "size_group".
*/
GtkSizeGroup *hildon_caption_get_sizegroup( const HildonCaption *self )
{
/**
* hildon_caption_new:
- * @group : a #GtkSizeGroup for controlling the size of related captions.
- * Can be NULL.
+ * @group : a #GtkSizeGroup for controlling the size of related captions,
+ * Can be NULL
* @value : the caption text to accompany the text entry. The widget makes
* a copy of this text.
* @control : the control that is to be captioned
* @icon : an icon to accompany the label - can be NULL in which case no
* icon is displayed
* @flag : indicates whether this captioned control is mandatory or
- * optional.
- * @returns : A #GtkWidget pointer of Caption
- *
+ * optional
+ *
* Creates a new instance of hildon_caption widget, with a specific
* control and image.
* Note: Clicking on a focused caption will trigger the activate signal.
* The default behaviour for the caption's activate signal is to call
* gtk_widget_activate on it's control.
+ *
+ * @Returns : a #GtkWidget pointer of Caption
*/
GtkWidget *hildon_caption_new( GtkSizeGroup *group, const gchar *value,
GtkWidget *control, GtkWidget *icon,
/**
* hildon_caption_is_mandatory:
- * @caption : A #HildonCaption
- * @returns : is this captioned control a mandatory one?
+ * @caption : a #HildonCaption
*
* Query #HildonCaption whether this captioned control is a mandatory one.
*
+ * @Returns : is this captioned control a mandatory one?
*/
gboolean hildon_caption_is_mandatory( const HildonCaption *caption )
/**
* hildon_caption_set_status:
- * @caption : A #HildonCaption
+ * @caption : a #HildonCaption
* @flag : one of the values from #HildonCaptionStatus
*
* Sets #HildonCaption status.
- *
-
*/
void hildon_caption_set_status( HildonCaption *caption,
/**
* hildon_caption_get_status:
- * @caption : A #HildonCaption
- * @returns : one of the values from #HildonCaptionStatus
+ * @caption : a #HildonCaption
*
* Gets #HildonCaption status.
*
+ * @Returns : one of the values from #HildonCaptionStatus
*/
HildonCaptionStatus hildon_caption_get_status( const HildonCaption *caption )
/**
* hildon_caption_set_icon_image:
- * @caption : A #HildonCaption
+ * @caption : a #HildonCaption
* @icon : the #GtkImage to use as the icon.
* calls gtk_widget_show on the icon if !GTK_WIDGET_VISIBLE(icon)
*
* Sets the icon to be used by this hildon_caption widget.
- *
*/
void hildon_caption_set_icon_image( HildonCaption *caption, GtkWidget *icon )
/**
* hildon_caption_get_icon_image:
- * @caption : A #HildonCaption
- * @returns : the #GtkImage that is being used as the icon by the
- * hildon_caption, or NULL if no icon is in use.
+ * @caption : a #HildonCaption
*
* Gets icon of #HildonCaption
*
+ * @Returns : the #GtkImage that is being used as the icon by the
+ * hildon_caption, or NULL if no icon is in use
*/
GtkWidget *hildon_caption_get_icon_image( const HildonCaption *caption )
/**
* hildon_caption_set_label:
- * @caption : A #HildonCaption
+ * @caption : a #HildonCaption
* @label : the text to use
*
* Sets the label text that appears before the control.
* Separator character is added to the end of the label string. By default
* the separator is ":".
- *
*/
void hildon_caption_set_label( HildonCaption *caption, const gchar *label )
/**
* hildon_caption_get_label:
- * @caption : A #HildonCaption
- * @returns : the text currently being used as the label of the caption
- * control. The string is owned by the label and the caller should never free or
- * modify this value.
+ * @caption : a #HildonCaption
*
* Gets label of #HildonCaption
- *
+ *
+ * @Returns : the text currently being used as the label of the caption
+ * control. The string is owned by the label and the caller should never
+ * free or modify this value.
*/
gchar *hildon_caption_get_label( const HildonCaption *caption )
/**
* hildon_caption_set_separator:
- * @caption : A #HildonCaption
+ * @caption : a #HildonCaption
* @separator : the separator to use
*
* Sets the separator character that appears after the label.
* The default seaparator character is ":"
* separately.
- *
-
*/
void hildon_caption_set_separator( HildonCaption *caption,
/**
* hildon_caption_get_separator:
- * @caption : A #HildonCaption
- * @returns : the text currently being used as the separator of the caption
- * control. The string is owned by the caption control and the caller should
- * never free or modify this value.
+ * @caption : a #HildonCaption
*
* Gets separator string of #HildonCaption
*
+ * @Returns : the text currently being used as the separator of the caption
+ * control. The string is owned by the caption control and the caller should
+ * never free or modify this value.
*/
gchar *hildon_caption_get_separator( const HildonCaption *caption )
/**
* hildon_caption_get_control:
- * @caption : A #HildonCaption
- * @returns : A #GtkWidget
+ * @caption : a #HildonCaption
*
* Gets caption's control.
- *
+ *
+ * @Returns : a #GtkWidget
+ *
* Deprecated: use gtk_bin_get_child instead
*/
GtkWidget *hildon_caption_get_control( const HildonCaption *caption )
/**
* hildon_caption_set_child_expand:
- * @caption : A #HildonCaption
+ * @caption : a #HildonCaption
* @expand : gboolean to determine is the child expandable
*
* Sets child expandability.
/**
* hildon_caption_get_child_expand:
- * @caption : A #HildonCaption
- * @returns : Wheter the child is expandable or not.
+ * @caption : a #HildonCaption
*
* Gets childs expandability.
+ *
+ * @Returns : wheter the child is expandable or not.
*/
gboolean hildon_caption_get_child_expand( const HildonCaption *caption )
{
/**
* hildon_caption_set_control:
- * @caption : A #HildonCaption
- * @control : The control to use. Control should not be NULL.
+ * @caption : a #HildonCaption
+ * @control : the control to use. Control should not be NULL.
*
* Sets the control of the caption.
* The old control will be destroyed, unless the caller has added a
* Function unparents the old control (if there is one) and adds the new
* control.
*
- * Deprecated: Use gtk_container_add.
+ * Deprecated: use gtk_container_add
*/
void hildon_caption_set_control( HildonCaption *caption, GtkWidget *control )
{
/**
* hildon_caption_set_label_alignment:
- * @caption: a #HildonCaption widget.
- * @alignment: new vertical alignment.
+ * @caption: a #HildonCaption widget
+ * @alignment: new vertical alignment
*
* Sets the vertical alignment to be used for the
* text part of the caption. Applications need to
/**
* hildon_caption_get_label_alignment:
- * @caption: a #HildonCaption widget.
+ * @caption: a #HildonCaption widget
*
* Gets current vertical alignment for the text part.
*
- * Returns: vertical alignment.
+ * Returns: vertical alignment
*/
gfloat hildon_caption_get_label_alignment(HildonCaption *caption)
{
*
*/
+/**
+ * SECTION:hildon-color-button
+ * @short_description: A widget to open HildonColorSelector
+ * @see_also: #HildonColorSelector, #HildonColorPopup
+ *
+ * HildonColorButton is a widget to open a HildonColorSelector.
+ * 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.
+ */
#include <config.h>
#include <gtk/gtkbutton.h>
/**
* hildon_color_button_new:
*
- * Creates a new color button. This returns a widget in the form of
- * a small button containing a swatch representing the current selected
- * color. When the button is clicked, a color-selection dialog will open,
- * allowing the user to select a color. The swatch will be updated to reflect
- * the new color when the user finishes.
+ * Creates a new color button. This returns a widget in the form of a
+ * small button containing a swatch representing the selected color.
+ * When the button is clicked, a color-selection dialog will open,
+ * allowing the user to select a color. The swatch will be updated to
+ * reflect the new color when the user finishes.
*
- * Return value: a new color button.
+ * Returns: a new color button
*/
GtkWidget *
hildon_color_button_new(void)
/**
* hildon_color_button_new_with_color:
- * @color: A #GdkColor to set the current color with.
+ * @color: a #GdkColor for the initial color
*
- * Creates a new color button.
+ * Creates a new color button with @color as the initial color.
*
- * Return value: a new color button.
+ * Returns: a new color button
*/
GtkWidget *
hildon_color_button_new_with_color(const GdkColor *color)
/**
* hildon_color_button_set_color:
- * @button: A #HildonColorButton
- * @color: A color to be set
+ * @button: a #HildonColorButton
+ * @color: a color to be set
*
- * Sets a color to the button.
+ * Sets the color selected by the button.
*/
void
hildon_color_button_set_color( HildonColorButton *button, GdkColor *color )
/**
* hildon_color_button_get_color:
- * @button: A #HildonColorButton
- *
- * Gets a color from the button.
+ * @button: a #HildonColorButton
*
- * Return value: The color set to a current button.
+ * Returns: the color selected by the button
*/
GdkColor *
hildon_color_button_get_color( HildonColorButton *button )
*
*/
-/*
- * @file hildon-color-popup.c
+/**
+ * SECTION:hildon-color-popup
+ * @short_description: A popup dialog for editing a color and showing the
+ * edited result
+ * @see_also: #HildonColorButton, #HildonColorSelector
*
- * This file contains the implementation of Hildon Color Selector Popup
- * widget containing the custom color palette selector popup for selecting
- * different colors based on RGB values.
+ * #HildonColorPopup is only used inside #HildonColorButton. It is a
+ * popup dialog for editing a color. The color can be changed using
+ * three control bars that are used to adjust the red, green and blue
+ * color channels. The display is updated in real time when the bars are
+ * moved.
*/
#ifdef HAVE_CONFIG_H
gpointer data);
/**
* hildon_color_popup_new:
- * @parent: the parent window of the dialog.
- * @initial_color: a #GdkColor with the initial values to be used.
- * @popup_data: a #HildonColorPopup.
+ * @parent: the parent window of the dialog
+ * @initial_color: a #GdkColor with the initial values to be used
+ * @popup_data: a #HildonColorPopup
*
* This function creates a new popup dialog with three controlbars
* (red, green, blue) and a drawing area with the current color.
* Used as normal GtkDialog (run with gtk_dialog_run() and read
* stardard responses (GTK_RESPONSE_OK, GTK_RESPONSE_CANCEL).
*
- * Returns: the newly created popup dialog.
+ * Returns: the newly created popup dialog
*/
GtkWidget *
/**
* hildon_color_popup_set_color_from_sliders:
- * @color: a pointer to #GdkColor to which the new values will be put.
- * @popup_data: a #HildonColorPopup.
+ * @color: a pointer to #GdkColor to which the new values will be put
+ * @popup_data: a #HildonColorPopup
*
- * This function sets the values of the given #GdkColor to the values
- * in the sliders of controlbars.
- *
- * Returns: void.
+ * Sets the values in the given #GdkColor to the values of the
+ * controlbars.
*/
void
*
*/
-/*
- * @file hildon-color-selector.c
- *
- * This file contains the implementation of Hildon Color Selector
- * widget containing the base color and custom color palette selector
- * and popup for selecting different colors based on RGB values.
+/**
+ * SECTION:hildon-color-selector
+ * @short_description: A widget for selecting a color
+ * @see_also: #HildonColorButton, #HildonColorPopup
+ *
+ * #HildonColorSelector allows selection of a color from a standard
+ * 16-color palette or a palette of 8 user-customizable colors.
+ * The user-customizable colors can be modified through HildonColorPopup.
*/
+
#ifdef HAVE_CONFIG_H
#include <config.h>
#endif
/**
* hildon_color_selector_new:
- * @parent: The parent window. The X window ID of the parent window
- * has to be the same as the X window ID of the application.
- * @returns: new #HildonColorSelector.
+ * @parent: the parent window. The X window ID of the parent window
+ * has to be the same as the X window ID of the application
*
* Creates a new #HildonColorSelector dialog with 3x8 layout of
- * Windows base colors and 'OK', 'More..' and 'Cancel' buttons.
+ * base colors and 'OK', 'More..' and 'Cancel' buttons.
+ *
+ * Returns: new #HildonColorSelector
**/
GtkWidget *hildon_color_selector_new(GtkWindow * parent)
{
* hildon_color_selector_get_color:
* @selector: a #HildonColorSelector
*
- * Gets the currently selected base color as #GdkColor.
- *
- * Returns: The currently selected #GdkColor. The returned pointer must
+ * Returns: the currently selected #GdkColor. The returned pointer must
* not be freed.
*/
G_CONST_RETURN GdkColor *hildon_color_selector_get_color(HildonColorSelector * selector)
/**
* hildon_color_selector_set_color:
* @selector: #HildonColorSelector
- * @color: #Gdkcolor to set.
+ * @color: #Gdkcolor to set
*
- * Select the color specified. Does nothing if the color does not
- * exists among the standard colors.
+ * Selects the color specified. Does nothing if the color does not
+ * exist among the standard colors.
*/
void hildon_color_selector_set_color(HildonColorSelector * selector,
GdkColor * color)
* 02110-1301 USA
*
*/
+
#include <gtk/gtkwidget.h>
#include <gtk/gtkwindow.h>
#include "hildon-composite-widget.h"
*
*/
-/*
- * @file hildon-caption-control.c
- *
- * This file contains the implementation of Hildon Caption Control
+/**
+ * SECTION:hildon-controlbar
+ * @short_description: A widget that allows increasing or decreasing
+ * a value within a pre-defined range
*
+ * #HildonControlbar is a horizontally positioned range widget that is
+ * visually divided into blocks and supports setting a minimum and
+ * maximum value for the range.
*/
+
#include <math.h>
#include <gdk/gdk.h>
#include <gdk/gdkkeysyms.h>
*
* Creates a new #HildonControlbar widget.
*
- * Return value: A #GtkWidget pointer of newly created #HildonControlbar
- * widget.
+ * Returns: a #GtkWidget pointer of newly created control bar
+ * widget
*/
GtkWidget *hildon_controlbar_new(void)
{
/**
* hildon_controlbar_set_value:
- * @self: Pointer to #HildonControlbar
- * @value: Value in range of >= 0 && < G_MAX_INT
+ * @self: pointer to #HildonControlbar
+ * @value: value in range of >= 0 && < G_MAX_INT
*
- * This method will change #HildonControlbar current value
- * to the given value.
+ * Change the current value of the control bar to the specified value.
*/
void hildon_controlbar_set_value(HildonControlbar * self, gint value)
{
/**
* hildon_controlbar_get_value:
- * @self: Pointer to #HildonControlbar
+ * @self: pointer to #HildonControlbar
*
- * Accessor method for getting controlbars current value
- *
- * Return value: Current value as gint.
+ * Returns: current value as gint
*/
gint hildon_controlbar_get_value(HildonControlbar * self)
{
/**
* hildon_controlbar_set_max:
- * @self: Pointer to #HildonControlbar
- * @max: Maximum value to set. The value needs to be
- * in range of > 0 && <= G_MAX_INT.
- * If the new maximum is smaller than current value,
- * the value will be adjusted so that
- * it equals the new maximum.
+ * @self: pointer to #HildonControlbar
+ * @max: maximum value to set. The value needs to be greater than 0.
*
- * Accessor method for setting #HildonControlbar maximum to the
- * given value.
- **/
+ * Set the control bar's maximum to the given value.
+ *
+ * If the new maximum is smaller than current value, the value will be
+ * adjusted so that it equals the new maximum.
+ */
void hildon_controlbar_set_max(HildonControlbar * self, gint max)
{
GtkAdjustment *adj;
/**
* hildon_controlbar_set_min:
- * @self: Pointer to #HildonControlbar
- * @min: Minimum value to set. The value needs to be
- * in range of => 0 && <= G_MAX_INT.
- * If the new minimum is smaller than current value,
- * the value will be adjusted so that
- * it equals the new minimum.
+ * @self: pointer to #HildonControlbar
+ * @min: minimum value to set. The value needs to be greater than or
+ * equal to 0.
*
- * Accessor method for setting #HildonControlbar minimum to the
- * given value.
- **/
+ * Set the control bar's minimum to the given value.
+ *
+ * If the new minimum is smaller than current value, the value will be
+ * adjusted so that it equals the new minimum.
+ */
void hildon_controlbar_set_min(HildonControlbar * self, gint min)
{
GtkAdjustment *adj;
/**
* hildon_controlbar_set_range:
- * @self: Pointer to #HildonControlbar
- * @max: Maximum value to set. The value needs to be
- * in range of > 0 && <= G_MAX_INT.
- * @min: Minimum value to set. The value needs to be
- * in range of => 0 && <= G_MAX_INT.
- * If the new maximum is smaller than current value,
- * the value will be adjusted so that
- * it equals the new maximum.
- * If the new minimum is smaller than current value,
- * the value will be adjusted so that
- * it equals the new minimum.
+ * @self: pointer to #HildonControlbar
+ * @max: maximum value to set. The value needs to be greater than 0.
+ * @min: Minimum value to set. The value needs to be greater than or
+ * equal to 0.
+ *
+ * Set the controlbars range to the given value
+ *
+ * If the new maximum is smaller than current value, the value will be
+ * adjusted so that it equals the new maximum.
*
- * Accessor method for setting #HildonControlbar maximum to the
- * given value.
- **/
+ * If the new minimum is smaller than current value, the value will be
+ * adjusted so that it equals the new minimum.
+ */
void hildon_controlbar_set_range(HildonControlbar * self, gint min,
gint max)
{
/**
* hildon_controlbar_get_max:
- * @self: A pointer to #HildonControlbar
- *
- * Accessor method for getting controlbars current maximum value
+ * @self: a pointer to #HildonControlbar
*
- * Return value: Maximum value as gint
+ * Returns: maximum value of control bar
*/
gint hildon_controlbar_get_max(HildonControlbar * self)
{
/**
* hildon_controlbar_get_min:
- * @self: A pointer to #HildonControlbar
- *
- * Accessor method for getting controlbars current minimum value
+ * @self: a pointer to #HildonControlbar
*
- * Return value: Minimum value as gint
+ * Returns: minimum value of controlbar
*/
gint hildon_controlbar_get_min(HildonControlbar * self)
{
*
*/
-/* HILDON DOC
- * @shortdesc: DateEditor is a widget for setting, getting and showing a
- * date.
- * @longdesc: The date editor consists of a GtkLabel that shows the current
- * date in localized form and an icon. Clicking on either the label or the
- * icon opens the #HildonCalendarPopup used for selecting the date.
- * Similarly, if the editor has the focus, and space or enter key is
- * pressed, the #HildonCalendarPopup will open.
+/**
+ * SECTION:hildon-date-editor
+ * @short_description: A widget which queries a date from user or opens
+ * a HildonCalendarPopup
+ * @see_also: #HildonCalendarPopup, #HildonTimeEditor
*
- * @seealso: #HildonTimeEditor, #HildonCalendarPopup
+ * HildonDateEditor is a widget with three entry fields (day, month,
+ * year) and an icon (eventbox): clicking on the icon opens up a
+ * HildonCalendarPopup.
*/
#include <glib.h>
/**
* hildon_date_editor_new:
*
- * Creates a new time editor. The current system date
+ * Creates a new date editor. The current system date
* is shown in the editor.
*
- * Return value: Pointer to a new @HildonDateEditor widget.
- **/
+ * Returns: pointer to a new @HildonDateEditor widget.
+ */
GtkWidget *hildon_date_editor_new(void)
{
return GTK_WIDGET(g_object_new(HILDON_DATE_EDITOR_TYPE, NULL));
* @day: day
*
* Sets the date shown in the editor.
- **/
+ */
void hildon_date_editor_set_date(HildonDateEditor * editor,
guint year, guint month, guint day)
{
* @month: month
* @day: day
*
- * Returns the year, month, and day currently on the
+ * Returns: the year, month, and day currently on the
* date editor.
- **/
+ */
void hildon_date_editor_get_date(HildonDateEditor * date,
guint * year, guint * month, guint * day)
{
*
* Sets the year shown in the editor.
*
- * Return: Returns TRUE if the year is valid.
- **/
+ * Returns: TRUE if the year is valid
+ */
gboolean hildon_date_editor_set_year(HildonDateEditor *editor, guint year)
{
HildonDateEditorPrivate *priv;
*
* Sets the month shown in the editor.
*
- * Return: Returns TRUE if the month is valid.
- **/
+ * Returns: TRUE if the month is valid
+ */
gboolean hildon_date_editor_set_month(HildonDateEditor *editor, guint month)
{
HildonDateEditorPrivate *priv;
*
* Sets the day shown in the editor.
*
- * Return: Returns TRUE if the day is valid.
- **/
+ * Returns: TRUE if the day is valid
+ */
gboolean hildon_date_editor_set_day(HildonDateEditor *editor, guint day)
{
HildonDateEditorPrivate *priv;
* hildon_date_editor_get_year:
* @editor: the @HildonDateEditor widget
*
- * Gets the year shown in the editor.
- *
- * Return: Returns the current year shown in the editor.
- **/
+ * Returns: the current year shown in the editor.
+ */
guint hildon_date_editor_get_year(HildonDateEditor *editor)
{
HildonDateEditorPrivate *priv;
*
* Gets the month shown in the editor.
*
- * Return: Returns the current month shown in the editor.
- **/
+ * Returns: the current month shown in the editor.
+ */
guint hildon_date_editor_get_month(HildonDateEditor *editor)
{
*
* Gets the day shown in the editor.
*
- * Return: Returns the current day shown in the editor.
- **/
+ * Returns: the current day shown in the editor
+ */
guint hildon_date_editor_get_day(HildonDateEditor *editor)
{
*
*/
+/**
+ * SECTION:hildon-defines
+ * @short_description: Not a widget, just a helper
+ *
+ */
+
#include <gtk/gtk.h>
#include "hildon-defines.h"
*
*/
-/*
- * @file hildon-dialoghelp.c
- *
- * This file provides API for the help dialog with
- * the optional icon.
- *
+/**
+ * SECTION:hildon-dialoghelp
+ * @short_description: A helper which contains a button in a normal dialog to
+ * open a help if required
+ *
+ * #HildonDialoghelp is a helper that provides an API for enabling or
+ * disabling a help button in the titlebar area of normal dialogs that
+ * are derived from GtkDialog.
*/
#include <stdlib.h>
* gtk_dialog_help_enable:
* @dialog: The dialog for which help is to be enabled.
*
- * Enables context help button for given dialog. The signal "help" can be
- * connected to handler by normal gtk methods. Note that this function
+ * Enables context help button for a given dialog. The signal "help" can be
+ * connected to handler by normal GTK methods. Note that this function
* has to be called before the dialog is shown.
*
* The "help" signal itself has no other parameters than the dialog where
* it is connected to, ie.:
* void user_function(GtkDialog *dialog, gpointer user_data);
- **/
+ */
void gtk_dialog_help_enable(GtkDialog * dialog)
{
GdkWindow *window;
gdk_window_add_filter(window, handle_xevent, dialog);
}
+
/**
* gtk_dialog_help_disable:
* @dialog: The dialog for which help is to be disabled.
*
*/
+/**
+ * SECTION:hildon-file-handling-note
+ * @short_description: Displaying the notification when a move
+ * operation is in progress.
+ * @see_also: #HildonFileHandlingNote
+ *
+ * This is the notification displayed when a move operation is in
+ * progress. The notification uses a progress bar to indicate the
+ * progress of the operation. For operation containing multiple items, a
+ * separe progress bar is shown for each item. The notification has a
+ * single button, which allows users to stop the move operation.
+ */
+
#include "hildon-note.h"
#include "hildon-file-handling-note.h"
#include <stdio.h>
/**
* hildon_file_handling_note_set_counter_and_name:
* @note: the #HildonFileHandlingNote widget
- * @current: Current item
- * @maximum: Maximum value for counter
- * @name: Filename
+ * @current: progress, current item being processed
+ * @maximum: maximum value for counter (number of items)
+ * @name: filename
*
* This function sets current counter value, maximum
* counter value and filename for dialog
+ *
* DEPRECATED: use hildon-note instead of hildon-file-handling-note.
*/
void hildon_file_handling_note_set_counter_and_name(HildonFileHandlingNote
/**
* hildon_file_handling_note_set_name:
* @note: the @HildonFileHandlingNote widget
- * @name: Filename
+ * @name: filename
*
- * This function sets filename for dialog
+ * This function sets the filename for dialog
* DEPRECATED: use hildon-note instead of hildon-file-handling-note.
*/
void hildon_file_handling_note_set_name(HildonFileHandlingNote * note,
* This function creates new dialog
* which is "moving" type.
*
- * Return value: a new #HildonFileHandlingNote.
+ * Returns: a new #HildonFileHandlingNote
* DEPRECATED: use hildon-note instead of hildon-file-handling-note.
*/
GtkWidget *hildon_file_handling_note_new_moving(GtkWindow * parent)
* This function creates new dialog
* which is "deleting" type.
*
- * Return value: a new #HildonFileHandlingNote.
+ * Returns: a new #HildonFileHandlingNote
* DEPRECATED: use hildon-note instead of hildon-file-handling-note.
*/
GtkWidget *hildon_file_handling_note_new_deleting(GtkWindow * parent)
* This function creates new dialog
* which is "opening" type
*
- * Return value: a new #HildonFileHandlingNote.
+ * Returns: a new #HildonFileHandlingNote
* DEPRECATED: use hildon-note instead of hildon-file-handling-note.
*/
GtkWidget *hildon_file_handling_note_new_opening(GtkWindow * parent)
* This function creates new dialog
* which is "saving" type.
*
- * Return value: a new #HildonFileHandlingNote.
+ * Returns: a new #HildonFileHandlingNote
* DEPRECATED: use hildon-note instead of hildon-file-handling-note.
*/
GtkWidget *hildon_file_handling_note_new_saving(GtkWindow * parent)
*
*/
+/**
+ * SECTION:hildon-find-toolbar
+ * @short_description: A special toolbar to be used with HildonAppView
+ * @see_also: #HildonAppView
+ *
+ * HildonFindToolbar is a predefined toolbar for text searching purpose.
+ * It contains a GtkListStore which has the text items that the user has
+ * searched. But once the application is terminated, or HildonFindToolbar
+ * is trashed. Programmer is responsible for getting the GtkListStore through
+ * property "list", if he/she wants to use the information in the future.
+ * And through the same property, programmer is able to set the GtkListStore.
+ * Note, once the search button is pressed, string in the GtkComboxEntry is
+ * automatically added to the existing model, unless it is empty.
+ */
+
#include "hildon-find-toolbar.h"
#include "hildon-defines.h"
#include <gdk/gdkkeysyms.h>
/**
* hildon_find_toolbar_new:
* @label: label for the find_toolbar, NULL to set the label to
- * default "Find".
+ * default "Find"
*
* Returns a new HildonFindToolbar.
*
- **/
+ * Returns: a new HildonFindToolbar
+ */
GtkWidget *
hildon_find_toolbar_new(const gchar *label)
/**
* hildon_find_toolbar_new_with_model
* @label: label for the find_toolbar, NULL to set the label to
- * default "Find".
- * @model: A @GtkListStore.
- * @column: Indicating which column the search histry list will
- * retreive string from.
+ * default "Find"
+ * @model: a @GtkListStore
+ * @column: indicating which column the search histry list will
+ * retreive string from
*
* Returns a new HildonFindToolbar, with a model.
*
- **/
+ * Returns: a new #HildonFindToolbar
+ */
GtkWidget *
hildon_find_toolbar_new_with_model(const gchar *label,
GtkListStore *model,
/**
* hildon_find_toolbar_highlight_entry
- * @HildonFindToolbar: Find Toolbar whose entry is to be highlighted.
+ * @ftb: find Toolbar whose entry is to be highlighted
* @get_focus: if user passes TRUE to this value, then the text in
* the entry will not only get highlighted, but also get focused.
*
- * */
+ */
void
hildon_find_toolbar_highlight_entry(HildonFindToolbar *ftb,
gboolean get_focus)
*
*/
+/**
+ * SECTION:hildon-font-selection-dialog
+ * @short_description: A widget used to allow users to select a font
+ * with certain properties
+ *
+ * Font selection can be made using this widget. Users can select font name,
+ * size, style, etc. Users can also preview text in the selected font.
+ */
+
#include <stdlib.h>
#include <string.h>
/**
* hildon_font_selection_dialog_new:
- * @parent: the parent window.
- * @title: the title of font selection dialog.
+ * @parent: the parent window
+ * @title: the title of font selection dialog
*
* If NULL is passed for title, then default title
* "Font" will be used.
*
- * Return value: a new #HildonFontSelectionDialog.
+ * Returns: a new #HildonFontSelectionDialog
*/
GtkWidget *
hildon_font_selection_dialog_new(GtkWindow * parent,
/**
* hildon_font_selection_dialog_get_preview_text:
- * @fsd: the font selection dialog.
+ * @fsd: the font selection dialog
*
* Gets the text in preview dialog, which does not include the
* reference text. The returned string must be freed by the user.
*
- * Returns: a string pointer.
+ * Returns: a string pointer
*/
gchar *
hildon_font_selection_dialog_get_preview_text(HildonFontSelectionDialog * fsd)
/**
* hildon_font_selection_dialog_set_preview_text:
- * @fsd: the font selection dialog.
- * @text: the text to be set to the preview dialog.
+ * @fsd: the font selection dialog
+ * @text: the text to be displayed in the preview dialog
*
* The default preview text is
* "The quick brown fox jumped over the lazy dogs"
/**
* hildon_font_selection_dialog_get_text_tag:
- * @fsd: the font selection dialog.
+ * @fsd: the font selection dialog
*
* Get the #GtkTextTag for selections. This function
- * is deprecated function. The best way to use
+ * is deprecated. The best way to use
* the text tags is to reuse them as much as possible.
- * The recommended way is to get the properties of font
- * selection dialog on GTK_RESPONSE_OK, according to
- * these property use the tags that you have pre-created.
+ * The recommended way is to get the properties of the font
+ * selection dialog on GTK_RESPONSE_OK, and according to
+ * these properties use the tags that you have pre-created.
*
* Returns: a #GtkTextTag having corresponding properties
- * set.
+ * set
*/
GtkTextTag *
hildon_font_selection_dialog_get_text_tag (HildonFontSelectionDialog *fsd)
/**
* hildon_font_selection_dialog_set_buffer:
- * @fsd: the font selection dialog.
+ * @fsd: the font selection dialog
* @buffer: a #GtkTextBuffer containing the text to which the selections will
* be applied. Applying is responsibility of application.
*
- * This is deprecated function. GtkTextBuffer is not enough
+ * This is deprecated. GtkTextBuffer is not enough
* to get the attributes of currently selected text. Please
* inspect the attributes yourself, and set the properties of
* font selection dialog to reflect your inspection.
- *
*/
void
hildon_font_selection_dialog_set_buffer (HildonFontSelectionDialog *fsd,
/**
* hildon_font_selection_dialog_get_font:
- * @fsd: the font selection dialog.
+ * @fsd: the font selection dialog
*
- * This is a deprecated function, @PangoAttrList needs
+ * This is deprecated. @PangoAttrList needs
* starting index, and end index on construction.
*
- * Return value: pointer to @PangoAttrList.
+ * Returns: pointer to @PangoAttrList
*/
PangoAttrList
*hildon_font_selection_dialog_get_font(HildonFontSelectionDialog * fsd)
/**
* hildon_font_selection_dialog_set_font:
- * @fsd: the font selection dialog.
- * @list: the pango attribute list.
+ * @fsd: the font selection dialog
+ * @list: the pango attribute list
*
- * This is a deprecated function.
+ * This is a deprecated.
*
* Sets the font to the dialog.
*/
*
*/
+/**
+ * SECTION:hildon-get-password-dialog
+ * @short_description: A widget used to get a password
+ * @see_also: #HildonSetPasswordDialog
+ *
+ * HildonGetPasswordDialog prompts the user for a password. It allows
+ * inputting password, with an optional configurable label eg. for
+ * showing the domain. The maximum length of the password can be set.
+ */
+
#include <glib.h>
#include <errno.h>
* Returns GType for HildonGetPasswordDialog as produced by
* g_type_register_static().
*
- * Return value: HildonGetPasswordDialog type
- **/
+ * Returns: HildonGetPasswordDialog type
+ */
GType hildon_get_password_dialog_get_type(void)
{
static GType dialog_type = 0;
* hildon_get_password_dialog_new:
* @parent: parent window; can be NULL
* @get_old_password_title: FALSE creates a new get password dialog and
- * TRUE creates a new get old password dialog
+ * TRUE creates a new get old password dialog. That is,
+ * if the password to be obtained is the old password,
+ * this parameter is specified TRUE.
*
* Construct a new HildonGetPasswordDialog.
*
- * Return value: a new #GtkWidget of type HildonGetPasswordDialog
- **/
+ * Returns: a new #GtkWidget of type HildonGetPasswordDialog
+ */
GtkWidget *hildon_get_password_dialog_new(GtkWindow * parent,
gboolean get_old_password_title)
{
}
/**
- * hildon_get_password_dialog_new:
+ * hildon_get_password_dialog_new_with_default:
* @parent: parent window; can be NULL
- * @password: a default password to be shown in password field.
+ * @password: a default password to be shown in password field
* @get_old_password_title: FALSE creates a new get password dialog and
- * TRUE creates a new get old password dialog
+ * TRUE creates a new get old password dialog.That is,
+ * if the password to be obtained is the old password,
+ * this parameter is specified TRUE.
+ *
*
* Same as #hildon_get_password_dialog_new but with a default password
* in password field.
*
- * Return value: a new #GtkWidget of type HildonGetPasswordDialog
- **/
+ * Returns: a new #GtkWidget of type HildonGetPasswordDialog
+ */
GtkWidget *hildon_get_password_dialog_new_with_default (GtkWindow * parent,
const gchar *password,
gboolean get_old_password_title)
*
* Gets the currently inputted password.
*
- * Return value: current password ( if the dialog is successfully
+ * Returns: current password ( if the dialog is successfully
* accepted with 'OK' )
- **/
+ */
const gchar
*hildon_get_password_dialog_get_password(HildonGetPasswordDialog *
dialog)
/**
* hildon_get_password_dialog_set_domain(GtkWidget *dialog,
* @dialog: the dialog
- * @domain: the domain or some other descriptive text to be set.
+ * @domain: the domain or some other descriptive text to be set
*
- * sets the optional descriptive text
+ * Sets the optional descriptive text.
*/
void hildon_get_password_dialog_set_domain(HildonGetPasswordDialog *dialog,
/**
* hildon_get_password_dialog_set_title:
* @dialog: the dialog
- * @new_title: the text to be set as the dialog title.
+ * @new_title: the text to be set as the dialog title
*
- * sets the dialog title
+ * Sets the dialog title.
*
* DEPRECATED! use gtk_window_set_title instead.
*/
/**
* hildon_get_password_dialog_set_caption:
* @dialog: the dialog
- * @new_caption: the text to be set as the caption label.
+ * @new_caption: the text to be set as the caption label
*
- * sets the password entry field's neigbouring label.
+ * Sets the password entry field's neigbouring label.
*/
void hildon_get_password_dialog_set_caption(HildonGetPasswordDialog *dialog,
* hildon_get_password_dialog_set_max_characters:
* @dialog: the dialog
* @max_characters: the maximum number of characters the password dialog
- * accepts.
+ * accepts
+ * @new_caption: the text to be set as the caption label
*
* sets the maximum number of characters allowed as the password
*/
*
*/
-/*
- * @file hildon-grid-item.c
- *
- * This file contains the implementation of HildonGridItem.
- * HildonGridItem is an item mainly used in HildonGrid. It has an icon,
- * emblem and a label.
+/**
+ * SECTION:hildon-grid-item
+ * @short_description: Creating grid items used by #HildonGrid
+ * @see_also: #HildonGrid
*
+ * HildonGridItem is used to create grid items used by #HildonGrid. The
+ * grid item consists of an icon and a label. Based on the displaying
+ * mode employed by #HildonGrid, the label is justified to the right or
+ * the bottom.
*/
/*
/**
* hildon_grid_item_new:
- * @icon_basename: Icon base name
+ * @icon_basename: icon base name
*
* Creates a new #HildonGridItem.
*
- * Return value: A new #HildonGridItem
+ * Returns: a new #HildonGridItem
*/
GtkWidget *
hildon_grid_item_new(const gchar *icon_basename)
/**
* hildon_grid_item_new_with_label:
- * @icon_basename: Icon base name
- * @label: Text label for icon
+ * @icon_basename: icon base name
+ * @label: text label for icon
*
- * Creates a new #HildonGridItem.
+ * Creates a new #HildonGridItem with a specified label for the icon.
*
- * Return value: A new #HildonGridItem
+ * Returns: a new #HildonGridItem
*/
GtkWidget *
hildon_grid_item_new_with_label(const gchar *icon_basename,
/**
* hildon_grid_item_set_emblem_type:
* @item: #HildonGridItem
- * @emblem_basename: Emblem's basename
+ * @emblem_basename: emblem's basename
*
* Sets item emblem type.
*/
* hildon_grid_item_get_emblem_type:
* @item: #HildonGridItem
*
- * Returns emblem's basename. Must not be changed or freed.
- *
- * Return value: Emblem's basename
+ * Returns: emblem's basename. Must not be changed or freed.
*/
const gchar *
hildon_grid_item_get_emblem_type(HildonGridItem *item)
*
*/
-/*
- * @file hildon-grid.c
+/**
+ * SECTION:hildon-grid
+ * @short_description: Being used where ever a number of single tap
+ * activatable items need to be presented (e.g. Control Panel applets)
+ * @see_also: #HildonGridItem
+ *
+ * HildonGrid is a set of application-defineable items that are presented in a
+ * table. There are two modes for the form of the table; large icon mode
+ * and small icon mode.
*
- * This file contains the implementation of HildonGrid. HildonGrid is used
- * in views like Home and Control Panel which have single-tap activated
- * items.
+ * In large icon mode, the Grid View items are presented with a large
+ * icon and a label under it. In small icon mode, the items are
+ * presented with a small icon and a label on the right side of the
+ * icon.
+ *
+ * The label has a solid background as wide as the maximum text width.
+ * This allows the text to have focus as well as be legible when
+ * displayed upon a black or dark background image. Long names are
+ * truncated with an ellipsis ("...") appended.
*/
/*
#include "hildon-marshalers.h"
#include <hildon-widgets/hildon-grid.h>
#include <hildon-widgets/hildon-grid-item.h>
-#include <hildon-widgets/hildon-app.h>
#include <libintl.h>
#define _(String) dgettext(PACKAGE, String)
* _hildon_grid_get_empty_label:
* @grid: #HildonGrid
*
- * Returns empty label. Label must not be modified nor freed.
- *
- * Return value: Label
+ * Returns: empty label. Label must not be modified nor freed.
*/
static const gchar *
hildon_grid_get_empty_label(HildonGrid * grid)
/*
* hildon_grid_set_num_columns:
* @grid: #HildonGrid
- * @columsn: Number of columns
+ * @columns: Number of columns
*
* Sets number of columns.
*/
*
* Creates a new #HildonGrid.
*
- * Return value: A new #HildonGrid
+ * Returns: a new #HildonGrid
*/
GtkWidget *hildon_grid_new(void)
{
/**
* hildon_grid_add:
- * @container: Container (#HildonGrid) to add HildonGridItem into.
- * @widget: #GtkWidget (#HildonGridItem) to add.
+ * @container: container (#HildonGrid) to add HildonGridItem into
+ * @widget: #GtkWidget (#HildonGridItem) to add
*
* Adds a new HildonGridItem into HildonGrid.
*/
/**
* hildon_grid_remove:
- * @container: Container (#HildonGrid) to remove #HildonGridItem from.
- * @widget: Widget (#HildonGridItem) to be removed.
+ * @container: container (#HildonGrid) to remove #HildonGridItem from
+ * @widget: widget (#HildonGridItem) to be removed
*
* Removes HildonGridItem from HildonGrid.
*/
* @grid: #HildonGrid
* @item: #HildonGridItem
*
- * Emits a signal to tell HildonGridItem was actiavated.
+ * Sends a signal to indicate that this HildonGridItem is activated.
*/
void hildon_grid_activate_child(HildonGrid * grid, HildonGridItem * item)
{
/**
* hildon_grid_set_style:
* @grid: #HildonGrid
- * @style_name: Style name
+ * @style_name: style name
*
* Sets style. Setting style sets widget size, spacing, label position,
* number of columns, and icon size.
*
* Returns the name of style currently used in HildonGrid.
*
- * Return value: Style name
+ * Returns: style name
*/
const gchar *hildon_grid_get_style(HildonGrid * grid)
{
* get_style_properties:
* @grid: #HildonGrid
*
- * Gets widget size and other stuff from gtkrc. If some stuff changed, let
- * children know this, too.
+ * Gets widget size and other properties from gtkrc. If some properties
+ * have changed, notify children of this, too.
*/
static void get_style_properties(HildonGrid * grid)
{
* hildon_grid_get_scrollbar_pos:
* @grid: #HildonGrid
*
- * Returns position of scrollbar (in pixels).
- *
- * Return value: Scrollbar position
+ * Returns: position of scrollbar (in pixels).
*/
gint hildon_grid_get_scrollbar_pos(HildonGrid * grid)
{
*
*/
-/*
- * @file hildon-hvolumebar.c
- *
- * This file contains API implementation for Hildon horizontal volumebar.
+/**
+ * SECTION:hildon-hvolumebar
+ * @short_description: A widget that displays a horizontal volume bar
+ * @see_also: #HildonVVolumebar, #HildonVolumebar
+ *
+ * The #HildonHVolumebar widget displays a horizontal volume bar that allows
+ * increasing or decreasing volume within a pre-defined range, and includes
+ * a mute icon which users can click to mute the sound.
*/
*
* Creates a new #HildonHVolumebar widget.
*
- * Returns: a new #HildonHVolumebar.
+ * Returns: a new #HildonHVolumebar
*/
GtkWidget *hildon_hvolumebar_new(void)
{
*
*/
+/**
+ * SECTION:hildon-insert-object-dialog
+ * @short_description: A dialog that enables the user to embed an object
+ * into rich text
+ *
+ * #HildonInsertObjectDialog is a dialog that enables the user to insert a
+ * new or existing object into a Multi-line (Rich Text) Editor as an
+ * embedded object.
+ */
+
#ifdef HAVE_CONFIG_H
#include <config.h>
#endif
/**
* hildon_insert_object_dialog_new:
- * @parent: the parent window of the dialog.
+ * @parent: the parent window of the dialog
*
* Creates a new #HildonInsertObjectDialog widget.
*
- * Return value: the newly created #HildonInsertObjectDialog
+ * Returns: the newly created #HildonInsertObjectDialog
*/
GtkWidget *hildon_insert_object_dialog_new(GtkWindow * parent)
{
/**
* hildon_insert_object_dialog_get_name:
- * @dialog: the dialog.
+ * @dialog: the dialog
*
- * Gets the text in name field.
+ * Gets the text in name field of the file dialog.
+ * This specifies the object to be inserted.
*
- * Return value: a pointer to the name string.
+ * Returns: a pointer to the name string
*/
const gchar *hildon_insert_object_dialog_get_name(HildonInsertObjectDialog
* dialog)
/**
* hildon_insert_object_dialog_get_mime_type:
- * @dialog: the dialog.
+ * @dialog: the dialog
*
* Gets the mime type selected in the combobox.
*
- * Return value: a pointer to the mime type string.
+ * Returns: a pointer to the mime type string, must not be freed
*/
const gchar
*hildon_insert_object_dialog_get_mime_type(HildonInsertObjectDialog *
*
*/
+/**
+ * SECTION:hildon-name-password-dialog
+ * @short_description: A widget which allows a user to enter an username
+ * and a password
+ * @see_also: #HildonGetPasswordDialog, #HildonSetPasswordDialog
+ *
+ * #HildonNamePasswordDialog is used to enter a username and password
+ * when accessing a password protected function. The widget performs no
+ * input checking and is used only for retrieving a user name and a
+ * password.
+ */
+
#include <glib.h>
#include <gtk/gtk.h>
#include <errno.h>
/**
* hildon_name_password_dialog_new:
- * @parent: the parent window of the dialog.
+ * @parent: the parent window of the dialog
*
* Creates a new #HildonNamePasswordDialog widget with Ok and Close
* buttons.
*
- * Return value: the newly created #HildonNamePasswordDialog
+ * Returns: the newly created #HildonNamePasswordDialog
*/
GtkWidget *hildon_name_password_dialog_new(GtkWindow * parent)
{
/**
* hildon_name_password_dialog_new_with_default:
- * @parent: the parent window of the dialog.
- * @name: default name, nul-terminated string, if you want
- * to leave it unset, pass a NULL pointer.
- * @password: default password, nul-terminated string,
- * if you want to leave it unset, pass a NULL pointer.
+ * @parent: the parent window of the dialog
+ * @name: default name, NULL if unset
+ * @password: default password, NULL if unset
*
* Same as #hildon_name_password_dialog_new, but with a
* default name and password.
*
- * Return value: the newly created #HildonNamePasswordDialog
+ * Returns: the newly created #HildonNamePasswordDialog
*/
GtkWidget *hildon_name_password_dialog_new_with_default
(GtkWindow * parent,
/**
* hildon_name_password_dialog_get_name:
- * @dialog: the dialog.
+ * @dialog: the dialog
*
* Gets the text that's in the name entry.
*
- * Return value: a pointer to the name string.
+ * Returns: a pointer to the name string.
*/
const gchar *hildon_name_password_dialog_get_name(HildonNamePasswordDialog
* dialog)
/**
* hildon_name_password_dialog_get_password:
- * @dialog: the dialog.
+ * @dialog: the dialog
*
* Gets the text that's in the password entry.
*
- * Return value: a pointer to the password string.
+ * Returns: a pointer to the password string
*/
const gchar *hildon_name_password_dialog_get_password(HildonNamePasswordDialog
* dialog)
/**
* hildon_name_password_dialog_set_domain(GtkWidget *dialog,
* @dialog: the dialog
- * @domain: the domain or some other descriptive text to be set.
+ * @domain: the domain or some other descriptive text to be set
*
* sets the optional descriptive text
*/
*
*/
-/*
- * @file hildon-note.c
+/**
+ * SECTION:hildon-note
+ * @short_description: A widget to ask confirmation from the user
*
- * This file contains API for confirmation, information and cancel notes.
+ * Notes are used to for confirmation (OK/Cancel/etc.) from the user.
+ * A simple note contains an information text and an OK button to be
+ * pressed. Additional features such as progress bars or animation can
+ * also be included.
*/
#ifdef HAVE_CONFIG_H
/**
* hildon_note_new_confirmation_add_buttons:
- * @parent: The parent window. The X window ID of the parent window
+ * @parent: the parent window. The X window ID of the parent window
* has to be the same as the X window ID of the application. This is
* important so that the window manager could handle the windows
* correctly.
- * In GTK the X window ID can be checked with
+ * In GTK the X window ID can be checked using
* GDK_WINDOW_XID(GTK_WIDGET(parent)->window).
- * @description: The message to confirm.
- * @Varargs: Arguments pairs for new buttons(label and return value).
+ *
+ * @description: the message to confirm
+ * @Varargs: arguments pairs for new buttons(label and return value).
* Terminate the list with %NULL value.
*
* Create a new confirmation note with custom buttons. Confirmation
* default ok/cancel buttons are not appended but you have to provide
* all of the buttons.
*
- * Return value: A #GtkWidget pointer of the note.
+ * Returns: A #GtkWidget pointer of the note
*/
/* FIXME: This doc seems to be wrong, the two buttons aren't added so it
/**
* hildon_note_new_confirmation:
- * @parent: The parent window. The X window ID of the parent window
+ * @parent: the parent window. The X window ID of the parent window
* has to be the same as the X window ID of the application. This is
* important so that the window manager could handle the windows
- * correctly. In GTK the X window ID can be checked with
+ * correctly. In GTK the X window ID can be checked using
* GDK_WINDOW_XID(GTK_WIDGET(parent)->window).
- * @description: The message to confirm.
+ * @description: the message to confirm
*
- * Create a new confirmation note. Confirmation note has a text,
- * two buttons and an default confirmation icon.
+ * Create a new confirmation note. Confirmation note has text (description)
+ * that you specify, two buttons and a default confirmation stock icon.
*
- * Return value: A #GtkWidget pointer of the note.
+ * Returns: a #GtkWidget pointer of the note
*/
GtkWidget *hildon_note_new_confirmation(GtkWindow * parent,
const gchar * description)
/**
* hildon_note_new_confirmation_with_icon_stock:
- * @parent: The parent window. The X window ID of the parent window
+ * @parent: the parent window. The X window ID of the parent window
* has to be the same as the X window ID of the application. This is
* important so that the window manager could handle the windows
- * correctly. In GTK the X window ID can be checked with
+ * correctly. In GTK the X window ID can be checked using
* GDK_WINDOW_XID(GTK_WIDGET(parent)->window).
- * @description: The message to confirm.
- * @stock_id: Icon to be displayed. If NULL, default icon is used.
+ * @description: the message to confirm
+ * @stock_id: icon to be displayed. If NULL, default icon is used.
*
- * Create a new confirmation note. Confirmation note has a text,
- * two buttons and an icon.
+ * Create a new confirmation note. Confirmation note has text (description)
+ * that you specify, two buttons and an icon.
*
* Note! This function is deprecated and broken, and really should not
* be used by anyone!
*
- * Return value: A #GtkWidget pointer of the note.
+ * Returns: a #GtkWidget pointer of the note
*/
GtkWidget *hildon_note_new_confirmation_with_icon_stock(GtkWindow * parent,
const gchar *
/**
* hildon_note_new_confirmation_with_icon_name:
- * @parent: The parent window. The X window ID of the parent window
+ * @parent: the parent window. The X window ID of the parent window
* has to be the same as the X window ID of the application. This is
* important so that the window manager could handle the windows
- * correctly. In GTK the X window ID can be checked with
+ * correctly. In GTK the X window ID can be checked using
* GDK_WINDOW_XID(GTK_WIDGET(parent)->window).
- * @description: The message to confirm.
- * @icon_name: Icon to be displayed. If NULL, default icon is used.
+ * @description: the message to confirm
+ * @icon_name: icon to be displayed. If NULL, default icon is used.
*
- * Create a new confirmation note. Confirmation note has a text,
- * two buttons and an icon.
+ * Create a new confirmation note. Confirmation note has text(description)
+ * that you specify, two buttons and an icon.
*
- * Return value: A #GtkWidget pointer of the note.
+ * Returns: a #GtkWidget pointer of the note
*/
GtkWidget *hildon_note_new_confirmation_with_icon_name(GtkWindow * parent,
const gchar *
/**
* hildon_note_new_information:
- * @parent: The parent window. The X window ID of the parent window
+ * @parent: the parent window. The X window ID of the parent window
* has to be the same as the X window ID of the application. This is
* important so that the window manager could handle the windows
- * correctly. In GTK the X window ID can be checked with
+ * correctly. In GTK the X window ID can be checked using
* GDK_WINDOW_XID(GTK_WIDGET(parent)->window).
- * @description: The message to confirm.
+ * @description: the message to confirm
*
- * Create a new information note. Information note has a text,
- * 'OK' labeled button and an icon.
+ * Create a new information note. Information note has a text(description)
+ * that you specify, an OK button and an icon.
*
- * Return value: A #GtkWidget pointer of the note.
+ * Returns: a #GtkWidget pointer of the note
*/
GtkWidget *hildon_note_new_information(GtkWindow * parent,
const gchar * description)
/**
* hildon_note_new_information_with_icon_stock:
- * @parent: The parent window. The X window ID of the parent window
+ * @parent: the parent window. The X window ID of the parent window
* has to be the same as the X window ID of the application. This is
* important so that the window manager could handle the windows
- * correctly. In GTK the X window ID can be checked with
+ * correctly. In GTK the X window ID can be checked using
* GDK_WINDOW_XID(GTK_WIDGET(parent)->window).
- * @description: The message to confirm.
- * @stock_id: Icon to be displayed. If NULL, default icon is used.
+ * @description: the message to confirm
+ * @stock_id: icon to be displayed. If NULL, default icon is used.
*
- * Create a new information note. Information note has a text,
- * 'OK' labeled button and an icon.
+ * Create a new information note. Information note has text(description)
+ * that you specify, an OK button and a default stock note icon.
*
* Note! This function is broken and deprecated and should not be
* used by anybody. Since the platform doesn't use stock icons,
* use #hildon_note_new_information_with_icon_name instead.
*
- * Return value: A #GtkWidget pointer of the note.
+ * Returns: a #GtkWidget pointer of the note
*/
GtkWidget *hildon_note_new_information_with_icon_stock(GtkWindow * parent,
const gchar *
/**
* hildon_note_new_information_with_icon_name:
- * @parent: The parent window. The X window ID of the parent window
+ * @parent: the parent window. The X window ID of the parent window
* has to be the same as the X window ID of the application. This is
* important so that the window manager could handle the windows
- * correctly. In GTK the X window ID can be checked with
+ * correctly. In GTK the X window ID can be checked using
* GDK_WINDOW_XID(GTK_WIDGET(parent)->window).
- * @description: The message to confirm.
- * @icon_name: Icon to be displayed. If NULL, default icon is used.
+ * @description: the message to confirm
+ * @icon_name: icon to be displayed. If NULL, default icon is used.
*
- * Create a new information note. Information note has a text,
- * 'OK' labeled button and an icon.
+ * Create a new information note. Information note has text(description)
+ * that you specify, an OK button and an icon.
*
- * Return value: A #GtkWidget pointer of the note.
+ * Returns: a #GtkWidget pointer of the note
*/
GtkWidget *hildon_note_new_information_with_icon_name(GtkWindow * parent,
const gchar *
/**
* hildon_note_new_information_with_icon_theme:
- * @parent: The parent window.
- * @description: The message to confirm.
- * @icon: #GtkIconTheme icon to be displayed.
+ * @parent: the parent window. The X window ID of the parent window
+ * has to be the same as the X window ID of the application. This is
+ * important so that the window manager could handle the windows
+ * correctly. In GTK the X window ID can be checked using
+ * GDK_WINDOW_XID(GTK_WIDGET(parent)->window).
+ *
+ * @description: the message to confirm
+ * @icon: #GtkIconTheme icon to be displayed
*
* This function is deprecated. Use
* #hildon_note_new_information_with_icon_name instead.
*
- * Return value: A #GtkWidget pointer of the note.
+ * Create a new information note. Information note has text(description)
+ * that you specify, an OK button and an icon.
+ *
+ * Returns: a #GtkWidget pointer of the note.
*/
GtkWidget *hildon_note_new_information_with_icon_theme(GtkWindow *parent,
const gchar *description,
/**
* hildon_note_new_cancel_with_progress_bar:
- * @parent: The parent window. The X window ID of the parent window
+ * @parent: the parent window. The X window ID of the parent window
* has to be the same as the X window ID of the application. This is
* important so that the window manager could handle the windows
- * correctly. In GTK the X window ID can be checked with
+ * correctly. In GTK the X window ID can be checked using
* GDK_WINDOW_XID(GTK_WIDGET(parent)->window).
- * @description: The action to cancel.
- * @progressbar: A pointer to #GtkProgressBar to be filled with the
+ * @description: the action to cancel
+ * @progressbar: a pointer to #GtkProgressBar to be filled with the
* progressbar assigned to this note. Use this to set the fraction of
* progressbar done. This parameter can be %NULL as well, in which
* case plain text cancel note appears.
*
- * Create a new cancel note with a progress bar. The note has a text,
- * 'Cancel' labeled button and a progress bar.
+ * Create a new cancel note with a progress bar. Cancel note has
+ * text(description) that you specify, a Cancel button and a progress bar.
*
- * Return value: A #GtkDialog. Use this to get rid of this note when you
+ * Returns: a #GtkDialog. Use this to get rid of this note when you
* no longer need it.
*/
GtkWidget *hildon_note_new_cancel_with_progress_bar(GtkWindow * parent,
/**
* hildon_note_set_button_text:
- * @note: A #HildonNote
- * @text: Sets the button text and if there is two buttons in dialog,
+ * @note: a #HildonNote
+ * @text: sets the button text and if there is two buttons in dialog,
* the button texts will be <text>, "Cancel".
*
- * Sets the button text to be used by this hildon_note widget.
+ * Sets the button text to be used by the hildon_note widget.
*/
void hildon_note_set_button_text(HildonNote * note, const gchar * text)
{
/**
* 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.
+ * @note: a #HildonNote
+ * @textOk: the new text of the default OK button
+ * @textCancel: the new text of the default cancel button
*
* Sets the button texts to be used by this hildon_note widget.
*/
*
*/
-/*
- * @file hildon-number-editor.c
- *
- * This file contains the implementation of Hildon Number Editor
+/**
+ * SECTION:hildon-number-editor
+ * @short_description: A widget used to enter a number within a pre-defined range
*
+ * HildonNumberEditor is used to enter a number from a specific range.
+ * There are two buttons to scroll the value in number field.
+ * Manual input is also possible.
*/
#include <gdk/gdkkeysyms.h>
/**
* hildon_number_editor_new:
- * @min: Minimum accepted value
- * @max: Maximum accepted value
+ * @min: minimum accepted value
+ * @max: maximum accepted value
*
* Creates new number editor
*
- * Return value: a new #HildonNumberEditor widget.
+ * Returns: a new #HildonNumberEditor widget
*/
GtkWidget *
hildon_number_editor_new (gint min, gint max)
/**
* hildon_number_editor_set_range:
* @editor: a #HildonNumberEditor widget
- * @min: Minimum accepted value
- * @max: Maximum accepted value
+ * @min: minimum accepted value
+ * @max: maximum accepted value
*
* Sets accepted number range for editor
*/
* hildon_number_editor_get_value:
* @editor: pointer to #HildonNumberEditor
*
- * Return value: Current NumberEditor value
+ * Returns: current NumberEditor value
*/
gint
hildon_number_editor_get_value (HildonNumberEditor *editor)
*
*/
-/*
- * @file hildon-range-editor.c
- *
- * This file implements the HildonRangeEditor widget.
+/**
+ * SECTION:hildon-range-editor
+ * @short_description: A widget is used to ask bounds of a range
*
- */
-
-/* HILDON DOC
- * @desc: Range Editor is used to define the range of some attribute. Accepted
- * number type is integer and '-' character is also acceptable. Range can
- * be used in application area and in dialog.
- *
+ * HidlonRangeEditor allows entering a pair of integers, e.g. the lower
+ * and higher bounds of a range. A minimum and maximum can also be set
+ * for the bounds.
*/
#include <gtk/gtkbox.h>
/**
* hildon_range_editor_get_type:
- * @Returns : GType of #HildonRangeEditor.
- *
+ *
* Initializes, and returns the type of a hildon range editor.
+ *
+ * @Returns : GType of #HildonRangeEditor
+ *
*/
GType
hildon_range_editor_get_type (void)
*
* HildonRangeEditor contains two GtkEntrys that accept numbers and minus.
*
- * Return value: pointer to a new @HildonRangeEditor widget.
- **/
+ * Returns: pointer to a new @HildonRangeEditor widget
+ */
GtkWidget *
hildon_range_editor_new (void)
{
/**
* hildon_range_editor_new_with_separator:
- * @separator: A string that is shown between the numbers.
+ * @separator: a string that is shown between the numbers
*
- * HildonRangeEditor contains two @GtkEntrys that accept numbers.
- * @separator is displayed between two entrys.
+ * HildonRangeEditor contains two Gtk entries that accept numbers.
+ * A separator is displayed between two entries.
* CHECKME: Use '-' as a separator in the case of null separator?
- *
- * Return value: pointer to a new @HildonRangeEditor widget.
- **/
+ *
+ * Returns: pointer to a new @HildonRangeEditor widget
+ */
GtkWidget *
hildon_range_editor_new_with_separator (const gchar *separator)
{
/**
* hildon_range_editor_set_range:
- * @editor: the #HildonRangeEditor widget.
- * @start: range's start value.
- * @end: range's end value.
+ * @editor: the #HildonRangeEditor widget
+ * @start: range's start value
+ * @end: range's end value
*
* Sets a range to the editor. (The current value)
*
* Sets the range of the @HildonRangeEditor widget.
- **/
+ */
void
hildon_range_editor_set_range (HildonRangeEditor *editor, gint start, gint end)
{
/**
* hildon_range_editor_get_range:
- * @editor: the #HildonRangeEditor widget.
- * @start: ranges start value.
- * @end: ranges end value.
+ * @editor: the #HildonRangeEditor widget
+ * @start: ranges start value
+ * @end: ranges end value
*
* Gets the range of the @HildonRangeEditor widget.
- **/
+ */
void
hildon_range_editor_get_range (HildonRangeEditor *editor, gint *start,
gint *end)
/**
* hildon_range_editor_set_limits:
- * @editor: the #HildonRangeEditor widget.
- * @start: minimum acceptable value (default: no limit).
- * @end: maximum accecptable value (default: no limit).
+ * @editor: the #HildonRangeEditor widget
+ * @start: minimum acceptable value (default: no limit)
+ * @end: maximum acceptable value (default: no limit)
*
* Sets the range of the @HildonRangeEditor widget.
- **/
+ */
void
hildon_range_editor_set_limits (HildonRangeEditor *editor, gint start,
gint end)
*
*/
+/**
+ * SECTION:hildon-scroll-area
+ * @short_description: A helper to create Maemo specific views,
+ * which are using scrollable area
+ *
+ * #GtkScrollArea combines a large widget that needs scrolling (like a
+ * text editor or a tree view) and other widgets that wouldn't fit one
+ * the screen normally without scrolling (like entries, toolbars etc.)
+ * into one scrollable area.
+ */
+
#include "hildon-scroll-area.h"
#include <gtk/gtkscrolledwindow.h>
#include <gtk/gtkfixed.h>
/**
* hildon_scroll_area_new:
* @sw: #GtkWidget - #GtkScrolledWindow
- * @child: #GtkWidget - Child to be place inside the sw
+ * @child: #GtkWidget - child to be place inside the sw
*
- * This is not a widget. It's a helper function to provide
- * hildon specified scrolling for applications.
- * Puts and connects the @child to the @sw.
+ * This is not a widget. It's a helper function to create
+ * hildon-specific scrolling methods.
* A common situation where the scroll area should be used
* might be following. A view containing @GtkTreeView based widget,
* (or any similar widget which has built-in @GtkScrolledWindow support)
*
*/
-/*
- * @file hildon-seekbar.c
+/**
+ * SECTION:hildon-seekbar
+ * @short_description: A widget used to identify a place from a content
*
- * This file contains the API implementation for Hildon Seekbar widget.
- * Based on seekbar.gob rev 1.10
+ * HildonSeekbar allows seeking in media with a range widget. It
+ * supports for setting or getting the length (total time) of the media,
+ * the position within it and the fraction (maximum position in a
+ * stream/the amount currently downloaded). The position is clamped
+ * between zero and the total time, or zero and the fraction in case of
+ * a stream.
*/
#ifdef HAVE_CONFIG_H
*
* Create a new #HildonSeekbar widget.
*
- * Return value: A #GtkWidget pointer of #HildonSeekbar widget.
+ * Returns: a #GtkWidget pointer of #HildonSeekbar widget
*/
GtkWidget *hildon_seekbar_new(void)
{
/**
* hildon_seekbar_get_total_time:
- * @seekbar: Pointer to #HildonSeekbar widget.
- *
- * Get total playing time of stream in seconds.
+ * @seekbar: pointer to #HildonSeekbar widget
*
- * Returns: Total time as gint.
- **/
+ * Returns: total playing time of media in seconds.
+ */
gint hildon_seekbar_get_total_time(HildonSeekbar *seekbar)
{
GtkWidget *widget;
/**
* hildon_seekbar_set_total_time:
- * @seekbar: Pointer to #HildonSeekbar widget.
- * @time: Time within range of > 0 && < G_MAXINT
+ * @seekbar: pointer to #HildonSeekbar widget
+ * @time: integer greater than zero
*
- * Set total playing time of stream in seconds.
- *
- **/
+ * Set total playing time of media in seconds.
+ */
void hildon_seekbar_set_total_time(HildonSeekbar *seekbar, gint time)
{
GtkAdjustment *adj;
/**
* hildon_seekbar_get_fraction:
- * @seekbar: Pointer to #HildonSeekbar widget.
+ * @seekbar: pointer to #HildonSeekbar widget
*
- * Get current fraction related to the progress indicator.
+ * Get current fraction value of the rage.
*
- * Returns: Current fraction.
- **/
+ * Returns: current fraction
+ */
guint hildon_seekbar_get_fraction( HildonSeekbar *seekbar )
{
g_return_val_if_fail( HILDON_IS_SEEKBAR( seekbar ), 0 );
/**
* hildon_seekbar_set_fraction:
- * @seekbar: Pointer to #HildonSeekbar widget.
- * @fraction: The new position of the progress indicator.
+ * @seekbar: pointer to #HildonSeekbar widget
+ * @fraction: the new position of the progress indicator
*
- * Set current fraction value related to the progress indicator.
+ * Set current fraction value of the range.
* It should be between the minimal and maximal values of the range in seekbar.
- **/
+ */
void hildon_seekbar_set_fraction( HildonSeekbar *seekbar, guint fraction )
{
GtkRange *range = NULL;
/**
* hildon_seekbar_get_position:
- * @seekbar: Pointer to #HildonSeekbar widget.
+ * @seekbar: pointer to #HildonSeekbar widget
*
* Get current position in stream in seconds.
*
- * Returns: Current position in stream in seconds.
- **/
+ * Returns: current position in stream in seconds
+ */
gint hildon_seekbar_get_position(HildonSeekbar *seekbar)
{
g_return_val_if_fail(HILDON_IS_SEEKBAR(seekbar), 0);
/**
* hildon_seekbar_set_position:
- * @seekbar: Pointer to #HildonSeekbar widget.
- * @time: Time within range of >= 0 && < G_MAXINT
+ * @seekbar: pointer to #HildonSeekbar widget
+ * @time: time within range of >= 0 && < G_MAXINT
*
* Set current position in stream in seconds.
- **/
+ */
void hildon_seekbar_set_position(HildonSeekbar *seekbar, gint time)
{
GtkRange *range;
*
*/
-/*
- * @file hildon-set-password-dialog.c
+/**
+ * SECTION:hildon-set-password-dialog
+ * @short_description: A dialog used to set, change or remove a password
+ * @see_also: #HildonGetPasswordDialog
*
- * This file implements API for Hildon Set and Change Password dialog.
+ * HildonSetPasswordDialog allows setting and changing a password.
*
- * Change password dialog:
- * @desc: Change Password Dialog is used to change an existing one in
- * situtations where the password can be removed. Unselecting the check
- * box dims the password fields below it. If the dialog is accepted with
- * 'OK' while the check box is unselected, a Confirmation Note is played.
- * If a Confirmation Note Dialog is accepted with 'Remove', the password
- * protection is removed.
+ * In Change mode: Dialog is used to change or remove an existing
+ * password. Unselecting the check box dims the password fields below
+ * it. If the dialog is accepted with 'OK' while the check box is
+ * unselected, a Confirmation Note is shown. If the Confirmation Note
+ * Dialog is accepted with 'Remove', the password protection is removed.
*
- * Set password dialog:
- * @desc: Set Password Dialog is used to define a password, or change a
- * password that cannot be removed.
- * @seealso: #HildonGetPasswordDialog
- *
+ * In Set mode: Set Password Dialog is used to define a password, or
+ * change a password that cannot be removed.
*/
#ifdef HAVE_CONFIG_H
* Returns GType for HildonPasswordDialog as produced by
* g_type_register_static().
*
- * Return value: HildonSetPasswordDialog type
- **/
+ * Returns: HildonSetPasswordDialog type
+ */
GType hildon_set_password_dialog_get_type(void)
{
static GType dialog_type = 0;
* @modify_protection: TRUE creates a new change password dialog and FALSE
* creates a new set password dialog
*
- * Construct a new HildonSetPasswordDialog.
+ * Constructs a new HildonSetPasswordDialog.
*
- * Return value: a new #GtkWidget of type HildonSetPasswordDialog
- **/
+ * Returns: a new #GtkWidget of type HildonSetPasswordDialog
+ */
GtkWidget *hildon_set_password_dialog_new(GtkWindow * parent,
gboolean modify_protection)
/**
* hildon_set_password_dialog_new_with_default:
* @parent: parent window; can be NULL
- * @password: a default password to be shown in password field.
+ * @password: a default password to be shown in password field
* @modify_protection: TRUE creates a new change password dialog and FALSE
* creates a new set password dialog
*
* Same as #hildon_set_password_dialog_new, but with a default password
* in password field.
*
- * Return value: a new #GtkWidget of type HildonSetPasswordDialog
- **/
+ * Returns: a new #GtkWidget of type HildonSetPasswordDialog
+ */
GtkWidget *hildon_set_password_dialog_new_with_default
(GtkWindow *parent,
*
* Returns current password.
*
- * Return value: changed password ( if the dialog is successfully
+ * Returns: changed password ( if the dialog is successfully
* accepted with 'OK' ( and when the check box is 'ON' ( in Change Password
* Dialog ))
- **/
+ */
const gchar
*hildon_set_password_dialog_get_password(HildonSetPasswordDialog *
dialog)
* hildon_set_password_dialog_get_protected:
* @dialog: pointer to HildonSetPasswordDialog
*
- * Returns protection mode.
+ * Returns the protection mode.
*
- * Return value: password protection mode ( TRUE when the protection is
+ * Returns: password protection mode ( TRUE when the protection is
* 'ON' and FALSE when the protection is 'OFF' )
- **/
+ */
gboolean
hildon_set_password_dialog_get_protected(HildonSetPasswordDialog * dialog)
{
/**
* hildon_set_password_dialog_set_domain(GtkWidget *dialog,
* @dialog: the dialog
- * @domain: the domain or some other descriptive text to be set.
+ * @domain: the domain or some other descriptive text to be set
*
- * sets the optional descriptive text
+ * Sets the optional descriptive text.
*/
void hildon_set_password_dialog_set_domain(HildonSetPasswordDialog *dialog,
*
*/
-/*
- * @file hildon-sort-dialog.c
+/**
+ * SECTION:hildon-sort-dialog
+ * @short_description: A widget for defining the sorting order of items
*
- * This file contains API for Hildon Sort dialog.
- * @desc: The sort dialog is used to define the order in which item are
- * shown in a list. Choice lists always display the current value when
- * the dialog is opened.
- *
+ * 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.
*/
#ifdef HAVE_CONFIG_H
* Returns GType for HildonSortDialog as produced by
* g_type_register_static().
*
- * Return value: HildonSortDialog type
- **/
+ * Returns: HildonSortDialog type
+ */
GType hildon_sort_dialog_get_type()
{
static GType dialog_type = 0;
/**
* hildon_sort_dialog_new:
- * @parent: Widget to be transient for, or NULL if none.
+ * @parent: widget to be transient for, or NULL if none
*
- * HildonSortDialog contains two #HildonCaption:s with combo boxes.
+ * HildonSortDialog contains two HildonCaptions with combo boxes.
*
- * Return value: pointer to a new @HildonSortDialog widget.
+ * Returns: pointer to a new @HildonSortDialog widget
*/
GtkWidget *hildon_sort_dialog_new(GtkWindow * parent)
{
/**
* hildon_sort_dialog_get_sort_key:
- * @dialog: the #HildonSortDialog widget.
+ * @dialog: the #HildonSortDialog widget
*
* Gets index to currently active sort key.
*
- * Return value: An integer which is the index value of the "Sort by"
+ * Returns: an integer which is the index value of the "Sort by"
* field
*/
gint hildon_sort_dialog_get_sort_key(HildonSortDialog * dialog)
/**
* hildon_sort_dialog_get_sort_order:
- * @dialog: the #HildonSortDialog widget.
+ * @dialog: the #HildonSortDialog widget
*
* Gets current sorting order from "Sort order" field.
*
- * Return value: current sorting order as #GtkSortType.
+ * Returns: current sorting order as #GtkSortType
*/
GtkSortType hildon_sort_dialog_get_sort_order(HildonSortDialog * dialog)
{
/**
* hildon_sort_dialog_set_sort_key:
- * @dialog: the #HildonSortDialog widget.
- * @key: Combo box's index value.
+ * @dialog: the #HildonSortDialog widget
+ * @key: combo box's index value
*
* Sets the index value of the #HildonSortDialog widget.
*/
/**
* hildon_sort_dialog_set_sort_order:
- * @dialog: the #HildonSortDialog widget.
- * @order: Combo box's index value.
+ * @dialog: the #HildonSortDialog widget
+ * @order: combo box's index value
*
* Sets the index value of the #HildonSortDialog widget.
*/
/**
* hildon_sort_dialog_add_sort_key:
- * @dialog: the #HildonSortDialog widget.
- * @sort_key: Combo box's index value
+ * @dialog: the #HildonSortDialog widget
+ * @sort_key: combo box's index value
*
* Adds a new sort key and returns the respective index in
* sort key combobox.
*
- * Return value: An integer which is the index of the added combo box's
- * item.
+ * Returns: an integer which is the index of the added combo box's
+ * item
*/
gint
hildon_sort_dialog_add_sort_key(HildonSortDialog * dialog,
*
*/
+/**
+ * SECTION:hildon-system-sound
+ * @short_description: An esd-based utility function for playing a sound
+ *
+ * HildonSystemSound is an esd-based utility function for playing a sound
+ * from the system sounds directory with volume taken from GConf.
+ */
+
#include <gconf/gconf-client.h>
#include <esd.h>
#include "hildon-system-sound.h"
/**
* hildon_play_system_sound:
- * @sample: Sound file to play
+ * @sample: sound file to play
*
* Plays the given sample using esd sound daemon.
* Volume level is received from gconf.
*
*/
-/*
- * @file hildon-telephone-editor.c
- *
- * This file implements the HildonTelephoneEditor widget.
- */
-
-/*
- * TODO:
- * - update hildon doc
+/**
+ * SECTION:hildon-telephone-editor.c
+ * @short_description: A widget which allows users to enter telephone numbers
*
- */
-
-/* HILDON DOC
- * @shortdesc:
- * @longdesc:
+ * A single-line editor which allows user to enter a telephone number.
+ * There are two modes to choose from (coerce/free format).
+ * Coerce format has three fields which are placed horizontally.
+ * The fields are: country code, area code and number. When nothing is
+ * entered in the fields, assisting text is displayed. Tapping on the
+ * field highlights the field and allows users to input numbers.
*
- * @seealso:
+ * The widget is used where a user should enter a phone number. Free format
+ * should be used wherever possible as it enables the user to enter the
+ * phone number in the format she likes. Free format also supports DTMF
+ * strings as a part of the phone number. The format can not be changed
+ * at runtime.
*/
#ifdef HAVE_CONFIG_H
/**
* hildon_telephone_editor_new:
- * @format: Format of the editor.
+ * @format: format of the editor
*
* Creates a new #HildonTelephoneEditor. The editor can be in a free
* format where the user can type in country code, area code and the
* digits. See #HildonTelephoneEditorFormat for the different coerse
* formats.
*
- * Return value: New #HildonTelephoneEditor.
+ * Returns: new #HildonTelephoneEditor
*/
GtkWidget *
hildon_telephone_editor_new(HildonTelephoneEditorFormat format)
/**
* hildon_telephone_editor_new_with_strings:
- * @format: Format of the editor.
- * @country: Default text for the country field.
- * @area: Default text for the area field.
- * @number: Default text for the number field.
+ * @format: format of the editor
+ * @country: default text for the country field
+ * @area: default text for the area field
+ * @number: default text for the number field
*
* Creates a new #HildonTelephoneEditor. See hildon_telephone_editor_new
* for details.
*
- * Return value: New #HildonTelephoneEditor.
+ * Returns: new #HildonTelephoneEditor
*/
GtkWidget *
hildon_telephone_editor_new_with_strings(HildonTelephoneEditorFormat
/**
* hildon_telephone_editor_set_editable:
- * @hte: #HildonTelephoneEditor.
- * @country: Set the editable status of the country field in coarce format.
- * @area: Set the editable status of the area field in coarce format.
- * @number: Set the editable status of the number field in coarce format.
+ * @hte: #HildonTelephoneEditor
+ * @country: set the editable status of the country field in coarce format
+ * @area: set the editable status of the area field in coarce format
+ * @number: set the editable status of the number field in coarce format
*
* Specify wheter the fields in coerse format are editable or
* not. This function is ignored if the editor is in free mode. The
* number or area and number parameters are ignored if the editor is
* in HILDON_TELEPHONE_EDITOR_FORMAT_COERCE_AREA or
* HILDON_TELEPHONE_EDITOR_FORMAT_COERCE_COUNTRY formats,
- * respectively.
- *
- *
- **/
+ * respectively.
+ */
void
hildon_telephone_editor_set_editable(HildonTelephoneEditor * editor,
gboolean country,
/**
* hildon_telephone_editor_set_widths:
- * @hte: #HildonTelephoneEditor.
- * @country: Width (characters) of the country field in coarce mode.
- * @area: Width (characters) of the area field in coarce mode.
- * @number: Width (characters) of the number field in coarce mode.
+ * @hte: #HildonTelephoneEditor
+ * @country: width (characters) of the country field in coarce mode
+ * @area: width (characters) of the area field in coarce mode
+ * @number: width (characters) of the number field in coarce mode
*
- * Set widths of the fields in coerse format. Country and area parameters
+ * Set widths of the fields in coecse format. Country and area parameters
* are ignored, if the editor is in free mode. The number or area and number
* parameters are ignored if the editor is in
* HILDON_TELEPHONE_EDITOR_FORMAT_COERCE_AREA or
* HILDON_TELEPHONE_EDITOR_FORMAT_COERCE_COUNTRY mode, respectively.
- *
- **/
+ */
void
hildon_telephone_editor_set_widths(HildonTelephoneEditor * editor,
guint country,
/**
* hildon_telephone_editor_set_show_plus:
- * @hte: #HildonTelephoneEditor.
- * @show: Show the plus sign.
- *
- * Show or hide the plus sign in front of coerce format's country field.
+ * @hte: #HildonTelephoneEditor
+ * @show: show the plus sign
*
- *
- **/
+ * Show or hide the plus sign in front of coerce format's country field.
+ */
void
hildon_telephone_editor_set_show_plus(HildonTelephoneEditor * editor,
gboolean show)
/**
* hildon_telephone_editor_get_show_plus:
- * @hte: #HildonTelephoneEditor.
+ * @hte: #HildonTelephoneEditor
*
* Get the visibility status of the plus sign in
* front of coerce format's country field.
*
- * Return value: gboolean.
- *
- **/
+ * Returns: gboolean
+ */
gboolean
hildon_telephone_editor_get_show_plus(HildonTelephoneEditor *
editor)
/**
* hildon_telephone_editor_set_show_border:
- * @hte: #HildonTelephoneEditor.
- * @show: Show the border.
+ * @hte: #HildonTelephoneEditor
+ * @show: show the border
*
* Show or hide the border around the widget
- *
- *
- **/
+ */
void
hildon_telephone_editor_set_show_border(HildonTelephoneEditor *
editor, gboolean show)
/**
* hildon_telephone_editor_get_show_border:
- * @hte: #HildonTelephoneEditor.
+ * @hte: #HildonTelephoneEditor
*
* Get the visibility status of the border around the widget.
*
- * Return value: gboolean.
- *
- **/
+ * Returns: gboolean
+ */
gboolean
hildon_telephone_editor_get_show_border(HildonTelephoneEditor * editor)
{
/**
* hildon_telephone_editor_get_country:
- * @hte: #HildonTelephoneEditor.
+ * @hte: #HildonTelephoneEditor
*
* Get text in the country field in coarse format. This function must
* not be called if in free mode.
*
- * Return value: pointer to the text in the country field. It must not
+ * Returns: pointer to the text in the country field. It must not
* be changed or freed.
- **/
+ */
const gchar *
hildon_telephone_editor_get_country(HildonTelephoneEditor *
editor)
/**
* hildon_telephone_editor_set_country:
- * @hte: #HildonTelephoneEditor.
- * @country: text to be set in country field.
+ * @hte: #HildonTelephoneEditor
+ * @country: text to be set in country field
*
* Set text in the country field in coarse format. This function must
* not be called if in free mode.
- **/
+ */
void
hildon_telephone_editor_set_country(HildonTelephoneEditor * editor,
const gchar * country)
/**
* hildon_telephone_editor_get_area:
- * @hte: #HildonTelephoneEditor.
+ * @hte: #HildonTelephoneEditor
*
* Get text in the area field in coarse format. This function must not
* be called if in free mode or in
* HILDON_TELEPHONE_EDITOR_FORMAT_COERCE_COUNTRY mode.
*
- * Return value: pointer to the text in the area field. It must not be
+ * Returns: pointer to the text in the area field. It must not be
* changed or freed.
- **/
+ */
const gchar *
hildon_telephone_editor_get_area(HildonTelephoneEditor *
editor)
/**
* hildon_telephone_editor_set_area:
- * @hte: #HildonTelephoneEditor.
- * @area: text to be set in area field.
+ * @hte: #HildonTelephoneEditor
+ * @area: text to be set in area field
*
* Set text in the area field in coarse format. This function must not
* be called if in free mode or in
* HILDON_TELEPHONE_EDITOR_FORMAT_COERCE_COUNTRY mode.
- **/
+ */
void
hildon_telephone_editor_set_area(HildonTelephoneEditor * editor,
const gchar * area)
/**
* hildon_telephone_editor_get_number:
- * @hte: #HildonTelephoneEditor.
+ * @hte: #HildonTelephoneEditor
*
- * Get text in the number field in all formats. If in free mode this
- * functions returns the whole phone number and if in coarce mode only
- * the number field's is returned. This function must not be called if
+ * Get text in the number field in all formats. In free mode, this
+ * functions returns the whole phone number. In coarce mode, it returns
+ * only the number field. This function must not be called if
* the editor is in HILDON_TELEPHONE_EDITOR_FORMAT_COERCE_AREA or
* HILDON_TELEPHONE_EDITOR_FORMAT_COERCE_COUNTRY modes.
*
- * Return value: pointer to text in the number field. It must not be
+ * Returns: pointer to text in the number field. It must not be
* changed or freed.
- **/
+ */
const gchar *
hildon_telephone_editor_get_number(HildonTelephoneEditor *
editor)
/**
* hildon_telephone_editor_set_number:
- * @hte: #HildonTelephoneEditor.
- * @number: text to be set to number field.
+ * @hte: #HildonTelephoneEditor
+ * @number: text to be set to number field
*
- * Set text in the number field in all formats. If in free mode this
- * functions sets the whole phone number and if in coerce mode only
- * the number field's is set. This function must not be called if
+ * Set text in the number field in all formats. In free mode this
+ * functions sets the whole phone number. In coerce mode, it sets
+ * only the number field. This function must not be called if
* the editor is in HILDON_TELEPHONE_EDITOR_FORMAT_COERSE_AREA or
* HILDON_TELEPHONE_EDITOR_FORMAT_COERCE_COUNTRY modes.
- **/
+ */
void
hildon_telephone_editor_set_number(HildonTelephoneEditor * editor,
const gchar * number)
*
*/
-/* HILDON DOC
- * @shortdesc: TimeEditor is a widget for setting, getting and showing a
- * time.
- * @longdesc: The Time Editor widget is used to enter the system time
- * (hours and minutes) in the Date/Time system plugin. It is a composite
- * widget consisting of two GtkEntry widgets that are placed next to each
- * other. The leftmost GtkEntry is used to enter the hours, and it accepts
- * the values 0--23, while the rightmost GtkEntry accepts values 0--59
- * and is used to set the minutes. Between the two GtkEntries there
- * is a label displaying a colon.
- * </para><para>
- * From the usability point of view, the GtkSpinbutton widget would
- * have been a better choice than the GtkEntry widgets, but it uses
- * floating point operations and is thus not acceptable in this
- * project.
- *
- * @seealso: #HildonDateEditor
+/**
+ * SECTION:hildon-time-editor
+ * @short_description: A widget used to enter time or duration in hours, minutes,
+ * and optional seconds
+ * @see_also: #HildonTimePicker
+ *
+ * HildonTimeEditor is used to edit time or duration. Time mode is
+ * restricted to normal 24 hour cycle, but Duration mode can select any
+ * 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.
*/
#ifdef HAVE_CONFIG_H
*
* This function creates a new time editor.
*
- * Return value: pointer to a new #HildonTimeEditor widget.
- **/
+ * Returns: pointer to a new #HildonTimeEditor widget
+ */
GtkWidget *hildon_time_editor_new(void)
{
/**
* hildon_time_editor_set_ticks:
- * @self: the @HildonTimeEditor widget.
- * @ticks: The duration to set, in seconds.
+ * @editor: the #HildonTimeEditor widget
+ * @ticks: the duration to set, in seconds
*
* Sets the current duration in seconds. This means seconds from
* midnight, if not in duration mode. In case of any errors, it tries
* to fix it.
- *
- **/
+ */
void hildon_time_editor_set_ticks (HildonTimeEditor * editor,
guint ticks)
/**
* hildon_time_editor_get_ticks:
- * @self: the @HildonTimeEditor widget.
+ * @editor: the #HildonTimeEditor widget
*
* This function returns the current duration, in seconds.
* This means seconds from midnight, if not in duration mode.
*
- * Return value: Current duration in seconds.
- **/
+ * Returns: current duration in seconds
+ */
guint hildon_time_editor_get_ticks (HildonTimeEditor * editor)
{
/**
* hildon_time_editor_set_show_seconds:
- * @editor: The #HildonTimeEditor.
- * @enable: Enable or disable showing of seconds.
+ * @editor: the #HildonTimeEditor
+ * @show_seconds: enable or disable showing of seconds
*
* This function shows or hides the seconds field.
- *
- **/
+ */
void hildon_time_editor_set_show_seconds (HildonTimeEditor * editor,
gboolean show_seconds)
/**
* hildon_time_editor_get_show_seconds:
- * @self: the @HildonTimeEditor widget.
+ * @editor: the #HildonTimeEditor widget
*
* This function returns a boolean indicating the visibility of
- * seconds in the @HildonTimeEditor
+ * seconds in the #HildonTimeEditor
*
- * Return value: TRUE if the seconds are visible.
- **/
+ * Returns: TRUE if the seconds are visible
+ */
gboolean hildon_time_editor_get_show_seconds (HildonTimeEditor * editor)
{
/**
* hildon_time_editor_set_duration_mode:
- * @editor: The #HildonTimeEditor.
- * @enable: Enable or disable duration editor mode
+ * @editor: the #HildonTimeEditor
+ * @duration_mode: enable or disable duration editor mode
*
* This function sets the duration editor mode in which the maximum hours
- * is 99 and the #HildonTimePicker is disabled.
- *
- **/
+ * is 99.
+ */
void hildon_time_editor_set_duration_mode (HildonTimeEditor * editor,
gboolean duration_mode)
/**
* hildon_time_editor_get_duration_mode:
- * @self: the @HildonTimeEditor widget.
+ * @editor: the #HildonTimeEditor widget
*
- * This function returns a boolean indicating whether the @HildonTimeEditor
+ * This function returns a boolean indicating whether the #HildonTimeEditor
* is in the duration mode.
*
- * Return value: TRUE if the @HildonTimeEditor is in duration mode.
- **/
+ * Returns: TRUE if the #HildonTimeEditor is in duration mode
+ */
gboolean hildon_time_editor_get_duration_mode (HildonTimeEditor * editor)
{
/**
* hildon_time_editor_set_duration_min:
- * @self: the @HildonTimeEditor widget.
- * @duration_min: Mimimum allowed duration.
+ * @editor: the #HildonTimeEditor widget
+ * @duration_min: mimimum allowed duration
*
* Sets the minimum allowed duration for the duration mode.
* Note: Has no effect in time mode
- **/
+ */
void hildon_time_editor_set_duration_min (HildonTimeEditor * editor,
guint duration_min)
/**
* hildon_time_editor_get_duration_min:
- * @self: the @HildonTimeEditor widget.
+ * @editor: the #HildonTimeEditor widget
*
- * This function returns the smallest duration the @HildonTimeEditor
+ * This function returns the smallest duration the #HildonTimeEditor
* allows in the duration mode.
*
- * Return value: Mimimum allowed duration in seconds.
- **/
+ * Returns: minimum allowed duration in seconds
+ */
guint hildon_time_editor_get_duration_min (HildonTimeEditor * editor)
{
/**
* hildon_time_editor_set_duration_max:
- * @self: the @HildonTimeEditor widget.
- * @duration_min: Maximum allowed duration in seconds.
+ * @editor: the #HildonTimeEditor widget
+ * @duration_max: maximum allowed duration in seconds
*
* Sets the maximum allowed duration in seconds for the duration mode.
* Note: Has no effect in time mode
- *
- **/
+ */
void hildon_time_editor_set_duration_max (HildonTimeEditor * editor,
guint duration_max)
/**
* hildon_time_editor_get_duration_max:
- * @self: the @HildonTimeEditor widget.
+ * @editor: the #HildonTimeEditor widget
*
- * This function returns the longest duration the @HildonTimeEditor
+ * This function returns the longest duration the #HildonTimeEditor
* allows in the duration mode.
*
- * Return value: Maximum allowed duration in seconds.
- **/
+ * Returns: maximum allowed duration in seconds
+ */
guint hildon_time_editor_get_duration_max (HildonTimeEditor * editor)
{
/**
* hildon_time_editor_set_time:
- * @editor: the @HildonTimeEditor widget.
+ * @editor: the #HildonTimeEditor widget
* @hours: hours
* @minutes: minutes
* @seconds: seconds
* This function sets the time on an existing time editor. If the
* time specified by the arguments is invalid, it's fixed.
* The time is assumed to be in 24h format.
- *
- **/
+ */
void hildon_time_editor_set_time(HildonTimeEditor * editor, guint hours,
guint minutes, guint seconds)
/**
* hildon_time_editor_get_time:
- * @editor: the @HildonTimeEditor widget.
+ * @editor: the #HildonTimeEditor widget
* @hours: hours
* @minutes: minutes
* @seconds: seconds
*
- * Gets the time of the @HildonTimeEditor widget. The time returned is
+ * Gets the time of the #HildonTimeEditor widget. The time returned is
* always in 24h format.
- **/
+ */
void hildon_time_editor_get_time(HildonTimeEditor * editor,
guint * hours,
/**
* hildon_time_editor_set_duration_range:
- * @editor: the @HildonTimeEditor widget.
+ * @editor: the #HildonTimeEditor widget
* @min_seconds: minimum allowed time in seconds
* @max_seconds: maximum allowed time in seconds
*
- * Sets the duration editor time range of the @HildonTimeEditor widget.
- **/
+ * Sets the duration editor time range of the #HildonTimeEditor widget.
+ */
void hildon_time_editor_set_duration_range(HildonTimeEditor * editor,
guint min_seconds,
/**
* hildon_time_editor_get_duration_range:
- * @editor: the @HildonTimeEditor widget.
+ * @editor: the #HildonTimeEditor widget
* @min_seconds: pointer to guint
* @max_seconds: pointer to guint
*
- * Gets the duration editor time range of the @HildonTimeEditor widget.
- **/
+ * Gets the duration editor time range of the #HildonTimeEditor widget.
+ */
void hildon_time_editor_get_duration_range(HildonTimeEditor * editor,
guint * min_seconds,
/**
* hildon_time_editor_show_seconds:
- * @editor: The #HildonTimeEditor.
- * @enable: Enable or disable showing of seconds.
- *
- * This function is deprecated, use @hildon_time_editor_set_show_seconds instead.
+ * @editor: the #HildonTimeEditor
+ * @enable: enable or disable showing of seconds
*
- **/
+ * This function is deprecated,
+ * use #hildon_time_editor_set_show_seconds instead.
+ */
void hildon_time_editor_show_seconds(HildonTimeEditor * editor,
gboolean enable)
{
}
/**
* hildon_time_editor_enable_duration_mode:
- * @editor: The #HildonTimeEditor.
- * @enable: Enable or disable duration editor mode
+ * @editor: the #HildonTimeEditor
+ * @enable: enable or disable duration editor mode
*
- * This function is deprecated, use @hildon_time_editor_set_duration_mode instead.
- *
- **/
+ * This function is deprecated,
+ * use #hildon_time_editor_set_duration_mode instead.
+ */
void hildon_time_editor_enable_duration_mode(HildonTimeEditor * editor,
gboolean enable)
{
*
*/
-/*
- * @file hildon-time-picker.c
- *
- * This file implements the HildonTimePicker widget. This widget
- * is used with HildonTimeEditor widget to set time.
- *
- */
-
-/* HILDON DOC
- * @shortdesc: TimePicker is a widget for setting a time.
- * @longdesc: The TimePicker contains two fields for setting the
- * time. Arrow buttons can be used to increment and decrement time. If
- * specified in systems locale setting AM/PM button is displayed.
+/**
+ * SECTION:hildon-time-picker
+ * @short_description: A dialog popup widget which lets the user set the time
+ * @see_also: #HildonTimeEditor
*
- * @seealso: #HildonTimeEditor
+ * #HildonTimePicker is a dialog popup widget which lets the user set the time,
+ * 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.
*/
#include "hildon-time-picker.h"
/**
* hildon_time_picker_new:
- * @parent: parent window.
+ * @parent: parent window
*
- * Hildon Time Picker shows time picker dialog. Close button is placed
- * in dialog's action area and time picker is placed in dialogs vbox.
- * Actual time picker consists two #GtkLabel fields one for hour and
- * one for minutes, arrow buttons and an AM/PM button. A : is placed
+ * #HildonTimePicker shows time picker dialog. The close button is placed
+ * in the dialog's action area and time picker is placed in dialogs vbox.
+ * The actual time picker consists of two #GtkLabel fields - one for hours
+ * and one for minutes - and an AM/PM button. A colon (:) is placed
* between hour and minute fields.
*
- * Return value: pointer to a new #HildonTimePicker widget.
- **/
+ * Returns: pointer to a new #HildonTimePicker widget.
+ */
GtkWidget *hildon_time_picker_new( GtkWindow *parent )
{
GtkWidget *widget = g_object_new( HILDON_TYPE_TIME_PICKER,
/**
* hildon_time_picker_set_time:
- * @picker: the #HildonTimePicker widget.
+ * @picker: the #HildonTimePicker widget
* @hours: hours
* @minutes: minutes
*
* Sets the time of the #HildonTimePicker widget.
- **/
+ */
void hildon_time_picker_set_time( HildonTimePicker *picker,
guint hours, guint minutes )
{
/**
* hildon_time_picker_get_time:
- * @picker: the #HildonTimePicker widget.
+ * @picker: the #HildonTimePicker widget
* @hours: hours
* @minutes: minutes
*
* Gets the time of the #HildonTimePicker widget.
- **/
+ */
void hildon_time_picker_get_time( HildonTimePicker *picker,
guint *hours, guint *minutes )
{
*
*/
-/*
- * @file hildon-volumebar.c
- *
- * This file contains the implementation of the Hildon Volumebar.
- * It is a base class for Hildon Vertical Volumebar and for
- * Hildon Horizontal Volumebar classes.
+/**
+ * SECTION:hildon-volumebar
+ * @short_description: Base class for widgets that display a volume bar
+ * @see_also: #HildonHVolumebar, #HildonVVolumebar
*
+ * #HildonVolumebar is a base class for widgets that display a volume bar that
+ * allows increasing or decreasing volume within a predefined range, and muting
+ * the volume when users click the mute icon.
*/
#include <gtk/gtkwindow.h>
/**
* hildon_volumebar_level_change:
- * @self: a HildonVolumebar widget.
+ * @self: a #HildonVolumebar widget
*
- * Emits "level_changed" signal to the given volumebar. This function
+ * Emits "level_changed" signal to the given volume bar. This function
* is mainly used by derived classes.
*/
void
/**
* hildon_volumebar_set_level:
- * @self: volumebar to change level on
+ * @self: volume bar to change level on
* @level: new level
*
- * Sets new volumelevel for this #HildonVolumebar.
- **/
+ * Sets new volume level for this #HildonVolumebar.
+ */
void
hildon_volumebar_set_level(HildonVolumebar * self, gdouble level)
{
/**
* hildon_volumebar_get_level:
- * @self: volumebar to query level on
+ * @self: volume bar to query level on
*
- * Gets the volumelevel of this #HildonVolumebar.
+ * Gets the volume level of this #HildonVolumebar.
*
- * Return value: Volume level or -1 on error.
- **/
+ * Returns: volume level or -1 on error
+ */
gdouble
hildon_volumebar_get_level(HildonVolumebar * self)
{
/**
* hildon_volumebar_set_mute:
- * @self: volumebar to work on
+ * @self: volume bar to work on
* @mute: mute ON/OFF
*
* Sets mute status for this #HildonVolumebar.
- *
- **/
+ */
void
hildon_volumebar_set_mute(HildonVolumebar * self, gboolean mute)
{
/**
* hildon_volumebar_get_mute:
- * @self: volumebar to query mute status
+ * @self: volume bar to query mute status
*
* Gets mute status of this #HildonVolumebar (ON/OFF).
*
- * Return value: Mute status as #gboolean value.
- **/
+ * Returns: Mute status as #gboolean value.
+ */
gboolean
hildon_volumebar_get_mute(HildonVolumebar * self)
{
/**
* hildon_volumebar_get_adjustment
- * @self : A #HildonVolumebar
+ * @self : a #HildonVolumebar
*
- * Gets the GtkAdjustment used in volumebar. This can be handy
+ * Gets the GtkAdjustment used in volume bar. This can be handy
* to give to hildon_appview_set_connected_adjustment which
* will allow changing the volume with increase / decrease
* hardware buttons.
*
- * This is a temporary solution until volumebar is restructured to
+ * This is a temporary solution until volume bar is restructured to
* be a child class of GtkRange.
*
- * Return value: A @GtkAdjustment used by volumebar.
- **/
+ * Returns: a #GtkAdjustment used by volume bar.
+ */
GtkAdjustment *
hildon_volumebar_get_adjustment (HildonVolumebar * self)
{
*/
/*
- * @file hildon-vvolumebar.c
+ * SECTION:hildon-vvolumebar
+ * @short_description: A widget that displays a vertical volume bar
+ * @see_also: #HildonVolumebar, #HildonHVolumebar
*
- * This file contains the implementation of HildonVVolumebar.
- * This widget is a subclass of HildonVolumebar and implements
- * horizontal version of Volumebar.
+ * #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.
*/
#ifdef HAVE_CONFIG_H
*
* Creates a new #HildonVVolumebar widget.
*
- * Returns: a new #HildonVVolumebar.
+ * Returns: a new #HildonVVolumebar
*/
GtkWidget *hildon_vvolumebar_new(void)
{
*
*/
+/**
+ * SECTION:hildon-weekday-picker
+ * @short_description: A widget for picking days on which a certain event
+ * should take place
+ * @see_also: #HildonWeekdayPicker
+ *
+ * #HildonWeekdayPicker supports non-mutually exclusive selection of days of
+ * the week. Selected days of the week are shown with a pushed-in effect.
+ *
+ * #HildonWeekdayPicker is used where users are required to pick days on which
+ * 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.
+ */
+
/* GDate numbers days from 1 to 7 and G_DATE_MONDAY is 1st day. However
according to locale settings first day is sunday. To get around this
problem, we addjust GDate days numbering to be same as locale
*
* Creates a new #HildonWeekdayPicker.
*
- * Return value: Pointer to a new @HildonWeekdayPicker widget.
+ * Returns: pointer to a new #HildonWeekdayPicker widget.
*/
GtkWidget *hildon_weekday_picker_new(void)
{
/**
* hildon_weekday_picker_set_day:
- * @picker: the @HildonWeekdayPicker widget
- * @day: Day to be set active
+ * @picker: the #HildonWeekdayPicker widget
+ * @day: day to be set active
*
- * Set specified weekday active.
+ * Sets specified weekday active.
*/
void
hildon_weekday_picker_set_day(HildonWeekdayPicker * picker,
/**
* hildon_weekday_picker_unset_day:
- * @picker: the @HildonWeekdayPicker widget
- * @day: Day to be set inactive
+ * @picker: the #HildonWeekdayPicker widget
+ * @day: day to be set inactive
*
- * Set specified weekday inactive.
+ * Sets specified weekday inactive.
*/
void
hildon_weekday_picker_unset_day(HildonWeekdayPicker * picker,
/**
* hildon_weekday_picker_toggle_day:
- * @picker: the @HildonWeekdayPicker widget
- * @day: Day to be toggled
+ * @picker: the #HildonWeekdayPicker widget
+ * @day: day to be toggled
*
- * Toggle current status of the specified weekday.
+ * Toggles current status of the specified weekday.
*/
void
hildon_weekday_picker_toggle_day(HildonWeekdayPicker * picker,
/**
* hildon_weekday_picker_set_all:
- * @picker: the @HildonWeekdayPicker widget
+ * @picker: the #HildonWeekdayPicker widget
*
- * Set all weekdays active.
+ * Sets all weekdays active.
*/
void
hildon_weekday_picker_set_all(HildonWeekdayPicker * picker)
/**
* hildon_weekday_picker_unset_all:
- * @picker: the @HildonWeekdayPicker widget
+ * @picker: the #HildonWeekdayPicker widget
*
- * Set all weekdays inactive.
+ * Sets all weekdays inactive.
*/
void
hildon_weekday_picker_unset_all(HildonWeekdayPicker * picker)
/**
* hildon_weekday_picker_isset_day:
- * @picker: the @HildonWeekdayPicker widget
- * @day: Day to be checked.
+ * @picker: the #HildonWeekdayPicker widget
+ * @day: day to be checked.
*
- * Check if the specified weekday is set active.
+ * Checks if the specified weekday is set active.
*
- * Return value: TRUE if the day is set, FALSE is day is not set.
+ * Returns: TRUE if the day is set, FALSE if the day is not set
*/
gboolean
hildon_weekday_picker_isset_day(HildonWeekdayPicker * picker,
*
*/
+/**
+ * SECTION:hildon-wizard-dialog
+ * @short_description: A widget to create a guided installation
+ * process wizard
+ *
+ * #HildonWizardDialog is a widget to create a guided installation
+ * process. The dialog has four standard buttons, previous, next,
+ * finish, cancel, and contains several pages with optional icons.
+ * 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.
+ */
+
#include <gtk/gtkdialog.h>
#include <gtk/gtknotebook.h>
#include <gtk/gtkimage.h>
/**
* hildon_wizard_dialog_new:
- * @parent: A #GtkWindow
- * @wizard_name: The name of dialog
- * @notebook: The notebook to be shown on the dialog
+ * @parent: a #GtkWindow
+ * @wizard_name: the name of dialog
+ * @notebook: the notebook to be shown on the dialog
*
- * Creates a new #HildonWizardDialog
+ * Creates a new #HildonWizardDialog.
*
- * Return value: A new HildonWizardDialog
+ * Returns: a new #HildonWizardDialog
*/
GtkWidget *hildon_wizard_dialog_new(GtkWindow * parent,
const char *wizard_name,
projects / hildon / commitdiff