HildonWindowStack

HildonWindowStack — A stack of windows in Hildon applications.

Synopsis


#include <hildon/hildon.h>

                    HildonWindowStack;
HildonWindowStack*  hildon_window_stack_get_default     (void);
HildonWindowStack*  hildon_window_stack_new             (void);
gint                hildon_window_stack_size            (HildonWindowStack *stack);
GList*              hildon_window_stack_get_windows     (HildonWindowStack *stack);
GtkWidget*          hildon_window_stack_peek            (HildonWindowStack *stack);
void                hildon_window_stack_push            (HildonWindowStack *stack,
                                                         HildonStackableWindow *win1,
                                                         ...);
void                hildon_window_stack_push_list       (HildonWindowStack *stack,
                                                         GList *list);
void                hildon_window_stack_push_1          (HildonWindowStack *stack,
                                                         HildonStackableWindow *win);
void                hildon_window_stack_pop             (HildonWindowStack *stack,
                                                         gint nwindows,
                                                         GList **popped_windows);
GtkWidget*          hildon_window_stack_pop_1           (HildonWindowStack *stack);
void                hildon_window_stack_pop_and_push    (HildonWindowStack *stack,
                                                         gint nwindows,
                                                         GList **popped_windows,
                                                         HildonStackableWindow *win1,
                                                         ...);
void                hildon_window_stack_pop_and_push_list
                                                        (HildonWindowStack *stack,
                                                         gint nwindows,
                                                         GList **popped_windows,
                                                         GList *list);

Object Hierarchy

  GObject
   +----HildonWindowStack

Properties

  "window-group"             GtkWindowGroup*       : Read / Write / Construct Only

Description

The HildonWindowStack is a stack of top-level windows.

Stacks contain all HildonStackableWindows that are being shown. The user can only interact with the topmost window from each stack (as it covers all the others), but all of them are mapped and visible from the Gtk point of view.

Each window can only be in one stack at a time. All stacked windows are visible and all visible windows are stacked.

Each application has a default stack, and windows are automatically added to it when they are shown with gtk_widget_show().

Additional stacks can be created at any time using hildon_window_stack_new(). To add a window to a specific stack, use hildon_window_stack_push_1() (remember that, for the default stack, gtk_widget_show() can be used instead).

To remove a window from a stack use hildon_window_stack_pop_1(), or simply gtk_widget_hide().

For more complex layout changes, applications can push and/or pop several windows at the same time in a single step. See hildon_window_stack_push(), hildon_window_stack_pop() and hildon_window_stack_pop_and_push() for more details.

Details

HildonWindowStack

typedef struct _HildonWindowStack HildonWindowStack;


hildon_window_stack_get_default ()

HildonWindowStack*  hildon_window_stack_get_default     (void);

Returns the default window stack. This stack always exists and doesn't need to be created by the application.

Returns : the default HildonWindowStack

Since 2.2


hildon_window_stack_new ()

HildonWindowStack*  hildon_window_stack_new             (void);

Creates a new HildonWindowStack. The stack is initially empty.

Returns : a new HildonWindowStack

Since 2.2


hildon_window_stack_size ()

gint                hildon_window_stack_size            (HildonWindowStack *stack);

Returns the number of windows in stack

stack : A HildonWindowStack
Returns : Number of windows in stack

Since 2.2


hildon_window_stack_get_windows ()

GList*              hildon_window_stack_get_windows     (HildonWindowStack *stack);

Returns the list of windows on this stack (topmost first). The widgets in the list are not individually referenced. Once you are done with the list you must call g_list_free().

stack : a HildonWindowStack
Returns : a newly-allocated list of HildonStackableWindows

Since 2.2


hildon_window_stack_peek ()

GtkWidget*          hildon_window_stack_peek            (HildonWindowStack *stack);

Returns the window on top of stack. The stack is never modified.

stack : A HildonWindowStack
Returns : the window on top of the stack, or NULL if the stack is empty.

Since 2.2


hildon_window_stack_push ()

void                hildon_window_stack_push            (HildonWindowStack *stack,
                                                         HildonStackableWindow *win1,
                                                         ...);

Pushes all windows to the top of stack, and shows them. Everything is done in a single transition, so the user will only see the last window. None of the windows must be already stacked.

stack : A HildonWindowStack
win1 : The first window to push
... : A NULL-terminated list of additional HildonStackableWindows to push.

Since 2.2


hildon_window_stack_push_list ()

void                hildon_window_stack_push_list       (HildonWindowStack *stack,
                                                         GList *list);

Pushes all windows in list to the top of stack, and shows them. Everything is done in a single transition, so the user will only see the last window in list during this operation. None of the windows must be already stacked.

stack : A HildonWindowStack
list : A list of HildonStackableWindows to push

Since 2.2


hildon_window_stack_push_1 ()

void                hildon_window_stack_push_1          (HildonWindowStack *stack,
                                                         HildonStackableWindow *win);

Adds win to the top of stack, and shows it. The window must not be already stacked.

Since 2.2


hildon_window_stack_pop ()

void                hildon_window_stack_pop             (HildonWindowStack *stack,
                                                         gint nwindows,
                                                         GList **popped_windows);

Pops nwindows windows from stack, and hides them. Everything is done in a single transition, so the user will not see any of the windows being popped in this operation.

If popped_windows is not NULL, the list of popped windows is stored there (ordered bottom-up). That list must be freed by the user.

stack : A HildonWindowStack
nwindows : Number of windows to pop
popped_windows : if non-NULL, the list of popped windows is stored here

Since 2.2


hildon_window_stack_pop_1 ()

GtkWidget*          hildon_window_stack_pop_1           (HildonWindowStack *stack);

Removes the window on top of stack, and hides it. If the stack is empty nothing happens.

stack : A HildonWindowStack
Returns : the window on top of the stack, or NULL if the stack is empty.

Since 2.2


hildon_window_stack_pop_and_push ()

void                hildon_window_stack_pop_and_push    (HildonWindowStack *stack,
                                                         gint nwindows,
                                                         GList **popped_windows,
                                                         HildonStackableWindow *win1,
                                                         ...);

Pops nwindows windows from stack (and hides them), then pushes all passed windows (and shows them). Everything is done in a single transition, so the user will only see the last pushed window. None of the pushed windows must be already stacked.

If popped_windows is not NULL, the list of popped windows is stored there (ordered bottom-up). That list must be freed by the user.

stack : A HildonWindowStack
nwindows : Number of windows to pop.
popped_windows : if non-NULL, the list of popped windows is stored here
win1 : The first window to push
... : A NULL-terminated list of additional HildonStackableWindows to push.

Since 2.2


hildon_window_stack_pop_and_push_list ()

void                hildon_window_stack_pop_and_push_list
                                                        (HildonWindowStack *stack,
                                                         gint nwindows,
                                                         GList **popped_windows,
                                                         GList *list);

Pops nwindows windows from stack (and hides them), then pushes all windows in list (and shows them). Everything is done in a single transition, so the user will only see the last window from list. None of the pushed windows must be already stacked.

If popped_windows is not NULL, the list of popped windows is stored there (ordered bottom-up). That list must be freed by the user.

stack : A HildonWindowStack
nwindows : Number of windows to pop.
popped_windows : if non-NULL, the list of popped windows is stored here
list : A list of HildonStackableWindows to push

Since 2.2

Property Details

The "window-group" property

  "window-group"             GtkWindowGroup*       : Read / Write / Construct Only

GtkWindowGroup that all windows on this stack belong to.

See Also

HildonStackableWindow