+2009-09-03 Alberto Garcia <agarcia@igalia.com>
+
+ * doc/hildon-sections.txt
+ * hildon/hildon-button.c
+ * hildon/hildon-edit-toolbar.c
+ * hildon/hildon-gtk.[ch]
+ * hildon/hildon-main.c
+ * hildon/hildon-program.c
+ * hildon/hildon-stackable-window.c:
+ Documentation updates
+
2009-08-28 Alberto Garcia <agarcia@igalia.com>
* hildon/hildon-app-menu.c
<SECTION>
<FILE>hildon-gtk</FILE>
<TITLE>Additions to GTK+</TITLE>
+HildonPortraitFlags
hildon_gtk_menu_new
hildon_gtk_button_new
hildon_gtk_toggle_button_new
hildon_gtk_window_set_do_not_disturb
hildon_gtk_window_set_progress_indicator
hildon_gtk_window_take_screenshot
-HildonPortraitFlags
hildon_gtk_window_set_portrait_flags
hildon_gtk_hscale_new
hildon_gtk_vscale_new
/*
* This file is a part of hildon
*
- * Copyright (C) 2008 Nokia Corporation, all rights reserved.
+ * Copyright (C) 2008, 2009 Nokia Corporation, all rights reserved.
*
* Contact: Rodrigo Novo <rodrigo.novo@nokia.com>
*
* SECTION:hildon-button
* @short_description: Two-label buttons in the Hildon framework.
*
- * The #HildonButton is a clickable button for Hildon applications.
- * It is derived from the #GtkButton widget and provides
- * additional commodities specific to the Hildon framework.
+ * #HildonButton is a clickable button for Hildon applications. It is
+ * derived from the #GtkButton widget and provides additional
+ * commodities specific to the Hildon framework.
*
* The height of a #HildonButton can be set to either "finger" height
* or "thumb" height. It can also be configured to use halfscreen or
* fullscreen width. Alternatively, either dimension can be set to
* "auto" so it behaves like a standard #GtkButton.
*
- * The #HildonButton can hold any valid child widget, but it usually
+ * A #HildonButton can hold any valid child widget, but it usually
* contains two labels, named title and value, and it can also contain
* an image. The contents of the button are packed together inside a
* #GtkAlignment and they do not expand by default (they don't use the
* to change @xscale or @yscale you can just use
* gtk_button_set_alignment() instead.
*
- * Note that for this method to work properly the, child widget of
+ * Note that for this method to work properly, the child widget of
* @button must be a #GtkAlignment. That's what #HildonButton uses by
* default, so this function will work unless you add a custom widget
* to @button.
/*
* This file is a part of hildon
*
- * Copyright (C) 2008 Nokia Corporation, all rights reserved.
+ * Copyright (C) 2008, 2009 Nokia Corporation, all rights reserved.
*
* This program is free software; you can redistribute it and/or modify
* it under the terms of the GNU Lesser Public License as published by
* To add a #HildonEditToolbar to a window use
* hildon_window_set_edit_toolbar().
*
+ * This toolbar is meant to replace the window title bar by emulating
+ * its appearance, so you should put the window in full screen mode
+ * with gtk_window_fullscreen().
+ *
* <example>
* <title>HildonEditToolbar example</title>
* <programlisting>
/*
* This file is a part of hildon
*
- * Copyright (C) 2008 Nokia Corporation, all rights reserved.
+ * Copyright (C) 2008, 2009 Nokia Corporation, all rights reserved.
*
* This program is free software; you can redistribute it and/or modify
* it under the terms of the GNU Lesser Public License as published by
* This is a convenience function to create a #GtkButton setting its
* size to one of the pre-defined Hildon sizes.
*
- * Buttons created with this function also override the
- * "gtk-button-images" setting. Images set using
+ * Buttons created with this function also override
+ * #GtkSettings:gtk-button-images. Images set using
* gtk_button_set_image() are always shown.
*
* Buttons created using this function have #GtkButton:focus-on-click
* This is a convenience function to create a #GtkToggleButton setting
* its size to one of the pre-defined Hildon sizes.
*
- * Buttons created with this function also override the
- * "gtk-button-images" setting. Images set using
+ * Buttons created with this function also override
+ * #GtkSettings:gtk-button-images. Images set using
* gtk_button_set_image() are always shown.
*
* Buttons created using this function have #GtkButton:focus-on-click
* This is a convenience function to create a #GtkRadioButton setting
* its size to one of the pre-defined Hildon sizes.
*
- * Buttons created with this function also override the
- * "gtk-button-images" setting. Images set using
+ * Buttons created with this function also override
+ * #GtkSettings:gtk-button-images. Images set using
* gtk_button_set_image() are always shown.
*
* Buttons created using this function have #GtkButton:focus-on-click
* This is a convenience function to create a #GtkRadioButton setting
* its size to one of the pre-defined Hildon sizes.
*
- * Buttons created with this function also override the
- * "gtk-button-images" setting. Images set using
+ * Buttons created with this function also override
+ * #GtkSettings:gtk-button-images. Images set using
* gtk_button_set_image() are always shown.
*
* Buttons created using this function have #GtkButton:focus-on-click
/*
* This file is a part of hildon
*
- * Copyright (C) 2008 Nokia Corporation, all rights reserved.
+ * Copyright (C) 2008, 2009 Nokia Corporation, all rights reserved.
*
* This program is free software; you can redistribute it and/or modify
* it under the terms of the GNU Lesser Public License as published by
hildon_gtk_window_set_do_not_disturb (GtkWindow *window,
gboolean dndflag);
+/**
+ * HildonPortraitFlags:
+ *
+ * These flags are used to tell the window manager whether the current
+ * window needs to be in portrait or landscape mode.
+ *
+ * If no flags are set then the window is meant to be used in
+ * landscape mode only.
+ *
+ * If %HILDON_PORTRAIT_MODE_REQUEST is set then the window is meant to
+ * be used in portrait mode only.
+ *
+ * If only %HILDON_PORTRAIT_MODE_SUPPORT is set then the current
+ * orientation will be kept, no matter if it's portrait or landscape.
+ *
+ * It is important to note that, while these flags can be used to
+ * change between portrait and landscape according to the physical
+ * orientation of the display, Hildon does not provide any method to
+ * obtain this information.
+ **/
typedef enum {
HILDON_PORTRAIT_MODE_REQUEST = 1 << 0,
HILDON_PORTRAIT_MODE_SUPPORT = 1 << 1
/*
* This file is part of the hildon library
*
- * Copyright (C) 2008 Nokia Corporation, all rights reserved.
+ * Copyright (C) 2008, 2009 Nokia Corporation, all rights reserved.
*
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public License
* to the window system display, and parses some standard command line
* arguments. See also gtk_init() to know more details on this topic.
*
- * Hildon should be initialized by using hildon_gtk_init(). Notice this function
- * also initialize gtk by calling gtk_init(). In case you need a customized
- * initialization of GTK+ library you could use hildon_init() after the
- * customized GTK+ initialization.
+ * Hildon should be initialized by using hildon_gtk_init(). Note that
+ * this function also initializes gtk by calling gtk_init(). In case
+ * you need a customized initialization of the GTK+ library you have
+ * to use hildon_init() after the customized GTK+ initialization.
*
* <example>
* <title>Typical <function>main</function> function for a Hildon application</title>
*
* This method does not support #HildonAppMenu<!-- -->s. See
* hildon_program_set_common_app_menu() for that.
- *
- * Since: 2.2
**/
void
hildon_program_set_common_menu (HildonProgram *self,
/*
* This file is a part of hildon
*
- * Copyright (C) 2008 Nokia Corporation, all rights reserved.
+ * Copyright (C) 2008, 2009 Nokia Corporation, all rights reserved.
*
* Contact: Rodrigo Novo <rodrigo.novo@nokia.com>
*
* @short_description: Stackable top-level window in the Hildon framework.
* @see_also: #HildonWindowStack, #HildonProgram, #HildonWindow
*
- * The #HildonStackableWindow is a
- * top-level window that can be stacked in a #HildonWindowStack. It is derived
- * from #HildonWindow. Applications that use stackable windows are organized
- * in a hierarchical way so users can go from any window back to the
- * application's root window.
+ * #HildonStackableWindow is a top-level window that can be stacked on
+ * top of others. It is derived from #HildonWindow. Applications that
+ * use stackable windows are organized in a hierarchical way so users
+ * can go from any window back to the previous one or directly to the
+ * stack's root window.
*
* The user can only see and interact with the window on top of the
* stack. Although all other windows are mapped and visible, they are
- * obscured by the topmost one so in practice they appear as if they
- * were hidden.
+ * obscured by the topmost one so in practice the user will see the
+ * whole stack as if it was a single window.
*
* To add a window to the stack, just use gtk_widget_show(). The
* previous one will be obscured by the new one. 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_window_stack_pop(). The
- * window will be automatically hidden and the previous one will
- * appear.
+ * without destroying it by using gtk_widget_hide(). The window will
+ * be hidden and the previous one will appear automatically.
*
- * For advanced details on stack handling, see #HildonWindowStack
+ * It is important to note that all #HildonStackableWindow<!-- -->s on
+ * a stack are always mapped and visible (from the Gtk point of view)
+ * and all visible #HildonStackableWindow<!-- -->s are always on a
+ * stack.
+ *
+ * To see how to manage multiple stacks per application and for other
+ * advanced details on stack handling, see #HildonWindowStack
*
* <example>
* <title>Basic HildonStackableWindow example</title>
projects / hildon / commitdiff