From 5c9192d464868f298838bc762f921ea1ff79d5f8 Mon Sep 17 00:00:00 2001 From: Alberto Garcia Date: Thu, 3 Sep 2009 19:53:35 +0200 Subject: [PATCH] Documentation updates * 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 --- ChangeLog | 11 +++++++++++ doc/hildon-sections.txt | 2 +- hildon/hildon-button.c | 12 ++++++------ hildon/hildon-edit-toolbar.c | 6 +++++- hildon/hildon-gtk.c | 18 +++++++++--------- hildon/hildon-gtk.h | 22 +++++++++++++++++++++- hildon/hildon-main.c | 10 +++++----- hildon/hildon-program.c | 2 -- hildon/hildon-stackable-window.c | 29 +++++++++++++++++------------ 9 files changed, 75 insertions(+), 37 deletions(-) diff --git a/ChangeLog b/ChangeLog index 1121c04..b3b347e 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,14 @@ +2009-09-03 Alberto Garcia + + * 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 * hildon/hildon-app-menu.c diff --git a/doc/hildon-sections.txt b/doc/hildon-sections.txt index abded58..91d97a3 100644 --- a/doc/hildon-sections.txt +++ b/doc/hildon-sections.txt @@ -1232,6 +1232,7 @@ HILDON_CHECK_VERSION
hildon-gtk Additions to GTK+ +HildonPortraitFlags hildon_gtk_menu_new hildon_gtk_button_new hildon_gtk_toggle_button_new @@ -1246,7 +1247,6 @@ hildon_gtk_icon_view_set_ui_mode 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 diff --git a/hildon/hildon-button.c b/hildon/hildon-button.c index bd2b8e3..58639e5 100644 --- a/hildon/hildon-button.c +++ b/hildon/hildon-button.c @@ -1,7 +1,7 @@ /* * 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 * @@ -20,16 +20,16 @@ * 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 @@ -829,7 +829,7 @@ hildon_button_set_image_position (HildonButton *button, * 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. diff --git a/hildon/hildon-edit-toolbar.c b/hildon/hildon-edit-toolbar.c index 9b8d910..7db0ecc 100644 --- a/hildon/hildon-edit-toolbar.c +++ b/hildon/hildon-edit-toolbar.c @@ -1,7 +1,7 @@ /* * 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 @@ -33,6 +33,10 @@ * 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(). + * * * HildonEditToolbar example * diff --git a/hildon/hildon-gtk.c b/hildon/hildon-gtk.c index e1b6f3d..2583682 100644 --- a/hildon/hildon-gtk.c +++ b/hildon/hildon-gtk.c @@ -1,7 +1,7 @@ /* * 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 @@ -114,8 +114,8 @@ hildon_gtk_menu_new (void) * 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 @@ -140,8 +140,8 @@ hildon_gtk_button_new (HildonSizeType size) * 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 @@ -168,8 +168,8 @@ hildon_gtk_toggle_button_new (HildonSizeType size) * 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 @@ -196,8 +196,8 @@ hildon_gtk_radio_button_new (HildonSizeType size, * 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 diff --git a/hildon/hildon-gtk.h b/hildon/hildon-gtk.h index 4816bfc..49b3d46 100644 --- a/hildon/hildon-gtk.h +++ b/hildon/hildon-gtk.h @@ -1,7 +1,7 @@ /* * 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 @@ -70,6 +70,26 @@ void 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 diff --git a/hildon/hildon-main.c b/hildon/hildon-main.c index 194af14..65cd4dd 100644 --- a/hildon/hildon-main.c +++ b/hildon/hildon-main.c @@ -1,7 +1,7 @@ /* * 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 @@ -28,10 +28,10 @@ * 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. * * * Typical <function>main</function> function for a Hildon application diff --git a/hildon/hildon-program.c b/hildon/hildon-program.c index ccac791..86e866c 100644 --- a/hildon/hildon-program.c +++ b/hildon/hildon-program.c @@ -593,8 +593,6 @@ hildon_program_get_can_hibernate (HildonProgram *self) * * This method does not support #HildonAppMenus. See * hildon_program_set_common_app_menu() for that. - * - * Since: 2.2 **/ void hildon_program_set_common_menu (HildonProgram *self, diff --git a/hildon/hildon-stackable-window.c b/hildon/hildon-stackable-window.c index 1b2d6bb..c10d433 100644 --- a/hildon/hildon-stackable-window.c +++ b/hildon/hildon-stackable-window.c @@ -1,7 +1,7 @@ /* * 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 * @@ -27,27 +27,32 @@ * @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 #HildonStackableWindows on + * a stack are always mapped and visible (from the Gtk point of view) + * and all visible #HildonStackableWindows are always on a + * stack. + * + * To see how to manage multiple stacks per application and for other + * advanced details on stack handling, see #HildonWindowStack * * * Basic HildonStackableWindow example -- 1.7.9.5