+2008-08-12 Alberto Garcia <agarcia@igalia.com>
+
+ * doc/hildon-docs.sgml
+ * src/hildon-app-menu.c
+ * src/hildon-bread-crumb.c
+ * src/hildon-button.c
+ * src/hildon-gtk.c
+ * src/hildon-program.c
+ * src/hildon-stackable-window.c
+ * src/hildon-window.c: Lots of documentation updates.
+
2008-08-12 Kimmo Hämäläinen <kimmo.hamalainen@nokia.com>
Released 2.1.4
<xi:include href="xml/hildon-sound.xml"/>
<xi:include href="xml/hildon-helper.xml"/>
<xi:include href="xml/hildon-defines.xml"/>
+ <xi:include href="xml/hildon-bread-crumb.xml"/>
</chapter>
<index>
* Besides that, the #HildonAppMenu can contain a group of filter buttons
* (#GtkToggleButton or #GtkRadioButton).
*
+ * To use a #HildonAppMenu, add it to a #HildonStackableWindow with
+ * with hildon_stackable_window_set_main_menu(). The menu will appear
+ * when the user presses the window title bar.
+ *
+ * Alternatively, you can show it by hand using gtk_widget_show().
+ *
* <example>
* <title>Creating a HildonAppMenu</title>
* <programlisting>
+ * HildonStackableWindow *win;
* HildonAppMenu *menu;
* GtkWidget *button;
* GtkWidget *filter;
* <!-- -->
+ * win = HILDON_STACKABLE_WINDOW (hildon_stackable_window_new ());
* menu = HILDON_APP_MENU (hildon_app_menu_new ());
* <!-- -->
* // Create a button and add it to the menu
* button = gtk_button_new_with_label ("Menu command one");
* g_signal_connect (button, "clicked", G_CALLBACK (button_one_clicked), userdata);
* hildon_app_menu_append (menu, GTK_BUTTON (button));
+ * <!-- -->
* // Another button
* button = gtk_button_new_with_label ("Menu command two");
* g_signal_connect (button, "clicked", G_CALLBACK (button_two_clicked), userdata);
* // Create a filter and add it to the menu
* filter = gtk_radio_button_new_with_label (NULL, "Filter one");
* gtk_toggle_button_set_mode (GTK_TOGGLE_BUTTON (filter), FALSE);
- * g_signal_connect (filter, "clicked", G_CALLBACK (filter_two_clicked), userdata);
+ * g_signal_connect (filter, "clicked", G_CALLBACK (filter_one_clicked), userdata);
* hildon_app_menu_add_filter (menu, GTK_BUTTON (filter));
+ * <!-- -->
* // Add a new filter
* filter = gtk_radio_button_new_with_label_from_widget (GTK_RADIO_BUTTON (filter), "Filter two");
* gtk_toggle_button_set_mode (GTK_TOGGLE_BUTTON (filter), FALSE);
- * g_signal_connect (filter, "clicked", G_CALLBACK (filter_three_clicked), userdata);
+ * g_signal_connect (filter, "clicked", G_CALLBACK (filter_two_clicked), userdata);
* hildon_app_menu_add_filter (menu, GTK_BUTTON (filter));
* <!-- -->
- * // Show the menu
- * gtk_widget_show (menu);
+ * // Add the menu to the window
+ * hildon_stackable_window_set_main_menu (win, menu);
* </programlisting>
* </example>
*
/**
* hildon_app_menu_new:
*
- * Creates a new HildonAppMenu.
+ * Creates a new #HildonAppMenu.
*
- * Return value: A @HildonAppMenu.
+ * Return value: A #HildonAppMenu.
**/
GtkWidget *
hildon_app_menu_new (void)
}
/**
- * hildon_app_menu_append
- * @menu : A @HildonAppMenu
- * @item : A @GtkButton to add to the HildonAppMenu
+ * hildon_app_menu_append:
+ * @menu : A #HildonAppMenu
+ * @item : A #GtkButton to add to the #HildonAppMenu
*
- * Adds the @item to the @HildonAppMenu
+ * Adds the @item to @menu.
*/
void
hildon_app_menu_append (HildonAppMenu *menu,
/**
* hildon_app_menu_add_filter
- * @menu : A @HildonAppMenu
- * @filter : A @GtkButton to add to the #HildonAppMenu.
- *
- * Adds the @filter to the #HildonAppMenu.
+ * @menu : A #HildonAppMenu
+ * @filter : A #GtkButton to add to the #HildonAppMenu.
*
+ * Adds the @filter to @menu.
*/
void
hildon_app_menu_add_filter (HildonAppMenu *menu,
g_param_spec_uint (
"horizontal-spacing",
"Horizontal spacing on menu items",
- "Horizontal spacing between each menu item (but not filters)",
+ "Horizontal spacing between each menu item. Does not apply to filter buttons.",
0, G_MAXUINT, 16,
G_PARAM_READABLE));
g_param_spec_uint (
"vertical-spacing",
"Vertical spacing on menu items",
- "Vertical spacing between each menu item (but not filters)",
+ "Vertical spacing between each menu item. Does not apply to filter buttons.",
0, G_MAXUINT, 16,
G_PARAM_READABLE));
*
*/
+/**
+ * SECTION:hildon-bread-crumb
+ * @short_description: Interface for elements in a #HildonBreadCrumbTrail
+ *
+ * #HildonBreadCrumb is an interface for creating new types of items
+ * for the #HildonBreadCrumbTrail widget.
+ */
+
#include "hildon-bread-crumb.h"
static void hildon_bread_crumb_base_init (gpointer g_class);
* "auto" so it behaves like a standard GtkButton.
*
* The #HildonButton can hold any valid child widget, but it usually
- * contains two labels, named title and value. To change the alignment
- * of the labels, use gtk_button_set_alignment()
+ * contains two labels, named title and value, and it can also contain
+ * an image. To change the alignment of the button contents, use
+ * gtk_button_set_alignment()
+ *
+ * <example>
+ * <title>Creating a HildonButton</title>
+ * <programlisting>
+ * void
+ * button_clicked (HildonButton *button, gpointer user_data)
+ * {
+ * const gchar *title, *value;
+ * <!-- -->
+ * title = hildon_button_get_title (button);
+ * value = hildon_button_get_value (button);
+ * g_debug ("Button clicked with title '%s' and value '%s'", title, value);
+ * }
+ * <!-- -->
+ * GtkWidget *
+ * create_button (void)
+ * {
+ * GtkWidget *button;
+ * <!-- -->
+ * button = hildon_button_new (HILDON_SIZE_AUTO, HILDON_BUTTON_ARRANGEMENT_VERTICAL);
+ * hildon_button_set_text (HILDON_BUTTON (button), "Some title", "Some value");
+ * <!-- -->
+ * g_signal_connect (button, "clicked", G_CALLBACK (button_clicked), NULL);
+ * <!-- -->
+ * return button;
+ * }
+ * </programlisting>
+ * </example>
*/
#include "hildon-button.h"
* @size_group: A #GtkSizeGroup for the button image
*
* Adds the image of @button to @size_group. You must add an image
- * using hildon_button_set_image before calling this function.
+ * using hildon_button_set_image() before calling this function.
**/
void
hildon_button_add_image_size_group (HildonButton *button,
* @size: Flags to set the size of the button.
* @arrangement: How the labels must be arranged.
*
- * Creates a new #HildonButton. To add a child widget use gtk_container_add().
+ * Creates a new #HildonButton. To set text in the labels, use
+ * hildon_button_set_title() and
+ * hildon_button_set_value(). Alternatively, you can add a custom
+ * child widget using gtk_container_add().
*
* Returns: a new #HildonButton
**/
*
* Sets the title (main label) of @button to @title.
*
- * This will clear the previously set title.
+ * This will clear any previously set title.
*
* If @title is set to %NULL, the title label will be hidden and the
* value label will be realigned.
*
* Sets the value (secondary label) of @button to @value.
*
- * This will clear the previously set value.
+ * This will clear any previously set value.
*
* If @value is set to %NULL, the value label will be hidden and the
* title label will be realigned.
* @button: a #HildonButton
* @position: the position of the image (%GTK_POS_LEFT or %GTK_POS_RIGHT)
*
- * Sets the position of the image inside @button. Only left and right
- * are supported.
+ * Sets the position of the image inside @button. Only %GTK_POS_LEFT
+ * and %GTK_POS_RIGHT are currently supported.
**/
void
hildon_button_set_image_position (HildonButton *button,
/**
* SECTION:hildon-gtk
* @short_description: Additional functions for Gtk widgets
+ * @see_also: #HildonButton
*
* Hildon provides some functions to extend the functionality of
* existing Gtk widgets. This also includes convenience functions to
/**
* SECTION:hildon-program
* @short_description: An object that represents an application running in the Hildon framework.
+ * @see_also: #HildonWindow, #HildonStackableWindow
*
- * The HildonProgram is an object used to represent an application running
+ * The #HildonProgram is an object used to represent an application running
* in the Hildon framework.
- *
- * Such an application is thought to have one or more HildonWindow. These
- * shall be registered to the HildonProgram with hildon_program_add_window,
- * and can be unregistered similarly with hildon_program_remove_window.
- *
- * The HildonProgram provides the programmer with commodities such
- * as applying a common toolbar and menu to all the HildonWindow
+ *
+ * Such an application is thought to have one or more #HildonWindow. These
+ * shall be registered to the #HildonProgram with hildon_program_add_window(),
+ * and can be unregistered similarly with hildon_program_remove_window().
+ *
+ * The #HildonProgram provides the programmer with commodities such
+ * as applying a common toolbar and menu to all the #HildonWindow
* registered to it. This is done with hildon_program_set_common_menu()
* and hildon_program_set_common_toolbar().
- *
- * The HildonProgram is also used to apply program-wide properties that
+ *
+ * The #HildonProgram is also used to apply program-wide properties that
* are specific to the Hildon framework. For instance
* hildon_program_set_can_hibernate() sets whether or not an application
* can be set to hibernate by the Hildon task navigator, in situations of
* low memory.
- *
+ *
+ * The #HildonProgram also contains a stack of
+ * #HildonStackableWindow. Such windows will be automatically added to
+ * the stack when shown, and removed when destroyed. The developer can
+ * use the stack with hildon_program_pop_window_stack(),
+ * hildon_program_peek_window_stack() and hildon_program_go_to_root_window().
+ *
* <example>
* <programlisting>
* HildonProgram *program;
* from the stack when they are destroyed.
*
* This function returns the #HildonStackableWindow from the top of
- * the stack or %NULL if the stack is empty. The stack is never modified.
+ * the stack, or %NULL if the stack is empty. The stack is never modified.
*
* Returns: A #HildonStackableWindow, or %NULL.
*/
/**
* hildon_program_add_window:
- * @self: The @HildonProgram to which the window should be registered
- * @window: A @HildonWindow to be added
+ * @self: The #HildonProgram to which the window should be registered
+ * @window: A #HildonWindow to be added
*
- * Registers a @HildonWindow as belonging to a given @HildonProgram. This
+ * Registers a #HildonWindow as belonging to a given #HildonProgram. This
* allows to apply program-wide settings as all the registered windows,
* such as hildon_program_set_common_menu() and
* hildon_pogram_set_common_toolbar()
* @self: The #HildonProgram in which the common menu should be used
* @menu: A GtkMenu to use as common menu for the program
*
- * Sets a GtkMenu that will appear in all the @HildonWindow registered
- * to the #HildonProgram. Only one common GtkMenu can be set, further
- * call will detach the previous common GtkMenu. A @HildonWindow
- * can use it's own GtkMenu with @hildon_window_set_menu
+ * Sets a GtkMenu that will appear in all the #HildonWindow registered
+ * with the #HildonProgram. Only one common GtkMenu can be set, further
+ * calls will detach the previous common GtkMenu. A #HildonWindow
+ * can use it's own GtkMenu with hildon_window_set_menu()
+ *
+ * This method does not support #HildonAppMenu objects.
**/
void
hildon_program_set_common_menu (HildonProgram *self,
* @self: The #HildonProgram from which to retrieve the common menu
*
* Return value: the GtkMenu that was set as common menu for this
- * #HildonProgram, or NULL of no common menu was set.
+ * #HildonProgram, or %NULL of no common menu was set.
**/
GtkMenu*
hildon_program_get_common_menu (HildonProgram *self)
* @self: The #HildonProgram in which the common toolbar should be used
* @toolbar: A GtkToolbar to use as common toolbar for the program
*
- * Sets a GtkToolbar that will appear in all the @HildonWindow registered
+ * Sets a GtkToolbar that will appear in all the #HildonWindow registered
* to the #HildonProgram. Only one common GtkToolbar can be set, further
- * call will detach the previous common GtkToolbar. A @HildonWindow
- * can use its own GtkToolbar with @hildon_window_set_toolbar. Both
- * #HildonProgram and @HildonWindow specific toolbars will be shown
+ * call will detach the previous common GtkToolbar. A #HildonWindow
+ * can use its own GtkToolbar with hildon_window_add_toolbar(). Both
+ * #HildonProgram and #HildonWindow specific toolbars will be shown
**/
void
hildon_program_set_common_toolbar (HildonProgram *self,
* @self: The #HildonProgram from which to retrieve the common toolbar
*
* Return value: the GtkToolbar that was set as common toolbar for this
- * #HildonProgram, or NULL of no common menu was set.
+ * #HildonProgram, or %NULL of no common menu was set.
**/
GtkToolbar*
hildon_program_get_common_toolbar (HildonProgram *self)
*
* Will close all windows in the #HildonProgram but the first one (the
* root window) by sending them a delete event. If any of the windows
- * refuses to close (by handling it) no further events will be
- * sent. All windows in the program must be #HildonStackableWindow for
- * this to work.
+ * refuses to close (by capturing the event) no further events will be
+ * sent. Only windows of type #HildonStackableWindow will be affected
+ * by this.
*/
void
hildon_program_go_to_root_window (HildonProgram *self)
* previous one will be automatically hidden. When the new window is
* destroyed, the previous one will appear again.
*
+ * Alternatively, you can remove a window from the top of the stack
+ * without destroying it by using
+ * hildon_program_pop_window_stack(). The window will be automatically
+ * hidden and the previous one will appear.
+ *
* <example>
* <programlisting>
* void
* window in the Hildon framework. It is derived from the GtkWindow
* and provides additional commodities specific to the Hildon
* framework.
-
+ *
* Among these windows in the Hildon framework can have a single menu
* attached, which is toggled with a hardware key or by tapping
* a custom button in the window frame. This menu can be set
* by providing a GtkMenu to the hildon_window_set_menu() method.
-
+ *
* Similarly a window in the Hildon framework can have several toolbars
* attached. These can be added to the HildonWindow with
- * hildon_window_add_toolbar()..
- *
+ * hildon_window_add_toolbar().
+ *
* <example>
* <title>Creating a HildonWindow</title>
* <programlisting>
* gtk_window_set_icon (GTK_WINDOW (window), icon_pixbuf);
* </programlisting>
* </example>
- *
*/
#include <memory.h>
projects / hildon / commitdiff