Editing Legacy Maemo 5 Documentation/Graphical UI Tutorial/Windows and dialogs
Warning: You are not logged in.
Your IP address will be recorded in this page's edit history.
Warning: This page is 37 kilobytes long; some browsers may have problems editing pages approaching or longer than 32kb. Please consider breaking the page into smaller sections.
The edit can be undone.
Please check the comparison below to verify that this is what you want to do, and then save the changes below to finish undoing the edit.
Latest revision | Your text | ||
Line 1: | Line 1: | ||
{{Legacy documentation}} | {{Legacy documentation}} | ||
+ | = Windows and dialogs = | ||
When creating applications for hand-held devices, you should take into account several issues about usability and device limitations. Screen size is a particularly large restriction; a simple interface is essential. | When creating applications for hand-held devices, you should take into account several issues about usability and device limitations. Screen size is a particularly large restriction; a simple interface is essential. | ||
Line 13: | Line 14: | ||
Views work in a tree-like hierarchy. Root View acts as the "root" for the tree, and the subsequent Sub Views branch down the hierarchy. | Views work in a tree-like hierarchy. Root View acts as the "root" for the tree, and the subsequent Sub Views branch down the hierarchy. | ||
- | [[Image:Rootview.png | + | [[Image:Rootview.png|400px]] [[Image:Subview.png|400px]] |
- | The view concept is implemented by the widget | + | The view concept is implemented by the widget HildonStackableWindow. This widget allows building a navigable hierarchy of windows with less code. |
- | |||
- | The | + | ==Stackable windows == |
+ | The HildonStackableWindow is a GTK+ widget which represents a top-level window in the Hildon framework. Stackable windows can be organized in a hierarchical way. | ||
A stack sets the hierarchical relationships between windows. A child window is on top of its parent window. That allows navigation to previous window by removing the topmost window. | A stack sets the hierarchical relationships between windows. A child window is on top of its parent window. That allows navigation to previous window by removing the topmost window. | ||
Line 31: | Line 32: | ||
'''Example 2.1. Example of stackable windows''' | '''Example 2.1. Example of stackable windows''' | ||
- | + | #include <hildon/hildon.h> | |
- | #include <hildon/hildon.h> | + | |
+ | static void | ||
+ | show_new_window (void) | ||
+ | { | ||
+ | GtkWidget *win; | ||
+ | GtkWidget *vbox; | ||
+ | GtkWidget *label; | ||
+ | |||
+ | /* Create the main window */ | ||
+ | win = hildon_stackable_window_new(); | ||
+ | gtk_window_set_title ( GTK_WINDOW (win), "Subview"); | ||
+ | |||
+ | /* Setting a label in the new window */ | ||
+ | label = gtk_label_new ("This is a subview"); | ||
+ | |||
+ | vbox = gtk_vbox_new (FALSE, 0); | ||
+ | gtk_box_pack_start (GTK_BOX (vbox), | ||
+ | label, | ||
+ | TRUE, | ||
+ | TRUE, | ||
+ | 0); | ||
+ | |||
+ | gtk_container_add (GTK_CONTAINER (win), | ||
+ | vbox); | ||
+ | |||
+ | /* This call show the window and also add the window to the stack */ | ||
+ | gtk_widget_show_all (win); | ||
+ | } | ||
+ | |||
+ | |||
+ | int | ||
+ | main (int argc, | ||
+ | char **argv) | ||
+ | { | ||
+ | HildonProgram *program; | ||
+ | |||
+ | GtkWidget *win; | ||
+ | GtkWidget *button; | ||
+ | |||
+ | hildon_gtk_init (&argc, &argv); | ||
+ | |||
+ | program = hildon_program_get_instance (); | ||
+ | |||
+ | /* Create the main window */ | ||
+ | win = hildon_stackable_window_new (); | ||
+ | gtk_window_set_title ( GTK_WINDOW (win), "Main window"); | ||
+ | |||
+ | button = gtk_button_new_with_label ("Go to subview"); | ||
+ | gtk_container_add ( GTK_CONTAINER (win), | ||
+ | button); | ||
+ | |||
+ | g_signal_connect (button, "clicked", G_CALLBACK (show_new_window), NULL); | ||
+ | |||
+ | g_signal_connect (win, "destroy", G_CALLBACK (gtk_main_quit), NULL); | ||
+ | |||
+ | /* This call show the window and also add the window to the stack */ | ||
+ | gtk_widget_show_all (win); | ||
+ | gtk_main(); | ||
+ | |||
+ | return 0; | ||
+ | } | ||
- | |||
- | |||
- | |||
- | |||
- | |||
- | |||
- | |||
- | |||
- | |||
- | |||
- | |||
- | |||
- | |||
- | |||
- | |||
- | |||
- | |||
- | |||
- | |||
- | |||
- | |||
- | |||
- | |||
- | |||
- | |||
- | |||
- | |||
- | |||
- | |||
- | |||
- | |||
- | |||
- | |||
- | |||
- | |||
- | |||
- | |||
- | |||
- | |||
- | |||
- | |||
- | |||
- | |||
- | |||
- | |||
- | |||
- | |||
- | |||
- | |||
- | |||
- | |||
- | |||
- | |||
- | |||
- | |||
- | |||
- | |||
- | |||
- | |||
- | |||
- | |||
The function <code>show_new_window()</code> is set up as a handler for when the signal "clicked" is emitted. This function creates a new stackable window which is added on top of the stack by calling <code>gtk_widget_show()</code>. | The function <code>show_new_window()</code> is set up as a handler for when the signal "clicked" is emitted. This function creates a new stackable window which is added on top of the stack by calling <code>gtk_widget_show()</code>. | ||
Line 105: | Line 105: | ||
==Advanced stack handling == | ==Advanced stack handling == | ||
- | + | The object which represents a stack of windows in the Hildon framework is the HildonWindowStack. This object provides functions to push and/or pop windows on the stack, functions to access the topmost window or retrieve the current size of the stack are provided as well. Usual operations | |
- | The object which represents a stack of windows in the Hildon framework is the | + | |
To access the default stack, use the function <code>hildon_window_stack_get_default()</code>. To access the stack that contains a particular window, use <code>hildon_stackable_window_get_stack()</code>. | To access the default stack, use the function <code>hildon_window_stack_get_default()</code>. To access the stack that contains a particular window, use <code>hildon_stackable_window_get_stack()</code>. | ||
- | < | + | <tt>HildonWindowStack<span><font color="#990000"><nowiki>*</nowiki></font></span> <span>'''<span><font color="#000000">hildon_window_stack_get_default</font></span>'''</span> <span><font color="#990000">(</font></span><span><font color="#009900">void</font></span><span><font color="#990000">);</font></span></tt> |
- | + | ||
- | </ | + | |
The following functions are available to push and/or pop windows on a stack: | The following functions are available to push and/or pop windows on a stack: | ||
- | < | + | <tt> <span><font color="#009900">void</font></span> <span>'''<span><font color="#000000">hildon_window_stack_push</font></span>'''</span> <span><font color="#990000">(</font></span>HildonWindowStack <span><font color="#990000"><nowiki>*</nowiki></font></span>stack<span><font color="#990000">,</font></span> |
- | void hildon_window_stack_push (HildonWindowStack *stack, | + | HildonStackableWindow <span><font color="#990000"><nowiki>*</nowiki></font></span>win1<span><font color="#990000">,</font></span> |
- | + | <span><font color="#990000">...);</font></span> | |
- | + | <span><font color="#009900">void</font></span> <span>'''<span><font color="#000000">hildon_window_stack_push_list</font></span>'''</span> <span><font color="#990000">(</font></span>HildonWindowStack <span><font color="#990000"><nowiki>*</nowiki></font></span>stack<span><font color="#990000">,</font></span> | |
- | void hildon_window_stack_push_list (HildonWindowStack *stack, | + | GList <span><font color="#990000"><nowiki>*</nowiki></font></span>list<span><font color="#990000">);</font></span> |
- | + | <span><font color="#009900">void</font></span> <span>'''<span><font color="#000000">hildon_window_stack_push_1</font></span>'''</span> <span><font color="#990000">(</font></span>HildonWindowStack <span><font color="#990000"><nowiki>*</nowiki></font></span>stack<span><font color="#990000">,</font></span> | |
- | void hildon_window_stack_push_1 (HildonWindowStack *stack, | + | HildonStackableWindow <span><font color="#990000"><nowiki>*</nowiki></font></span>win<span><font color="#990000">);</font></span> |
- | + | <span><font color="#009900">void</font></span> <span>'''<span><font color="#000000">hildon_window_stack_pop</font></span>'''</span> <span><font color="#990000">(</font></span>HildonWindowStack <span><font color="#990000"><nowiki>*</nowiki></font></span>stack<span><font color="#990000">,</font></span> | |
- | void hildon_window_stack_pop (HildonWindowStack *stack, | + | gint nwindows<span><font color="#990000">,</font></span> |
- | + | GList <span><font color="#990000"><nowiki>**</nowiki></font></span>popped_windows<span><font color="#990000">);</font></span> | |
- | + | GtkWidget<span><font color="#990000"><nowiki>*</nowiki></font></span> <span>'''<span><font color="#000000">hildon_window_stack_pop_1</font></span>'''</span> <span><font color="#990000">(</font></span>HildonWindowStack <span><font color="#990000"><nowiki>*</nowiki></font></span>stack<span><font color="#990000">);</font></span> | |
- | GtkWidget* hildon_window_stack_pop_1 (HildonWindowStack *stack); | + | <span><font color="#009900">void</font></span> <span>'''<span><font color="#000000">hildon_window_stack_pop_and_push</font></span>'''</span> <span><font color="#990000">(</font></span>HildonWindowStack <span><font color="#990000"><nowiki>*</nowiki></font></span>stack<span><font color="#990000">,</font></span> |
- | void hildon_window_stack_pop_and_push (HildonWindowStack *stack, | + | gint nwindows<span><font color="#990000">,</font></span> |
- | + | GList <span><font color="#990000"><nowiki>**</nowiki></font></span>popped_windows<span><font color="#990000">,</font></span> | |
- | + | HildonStackableWindow <span><font color="#990000"><nowiki>*</nowiki></font></span>win1<span><font color="#990000">,</font></span> | |
- | + | <span><font color="#990000">...);</font></span> | |
- | + | <span><font color="#009900">void</font></span> <span>'''<span><font color="#000000">hildon_window_stack_pop_and_push_list</font></span>'''</span> <span><font color="#990000">(</font></span>HildonWindowStack <span><font color="#990000"><nowiki>*</nowiki></font></span>stack<span><font color="#990000">,</font></span> | |
- | void hildon_window_stack_pop_and_push_list (HildonWindowStack *stack, | + | gint nwindows<span><font color="#990000">,</font></span> |
- | + | GList <span><font color="#990000"><nowiki>**</nowiki></font></span>popped_windows<span><font color="#990000">,</font></span> | |
- | + | GList <span><font color="#990000"><nowiki>*</nowiki></font></span>list<span><font color="#990000">);</font></span></tt> | |
- | + | ||
- | </ | + | |
The example shows how to get the default stack and push a newly created window on the stack. (Note that you also can do the same in a single stack by calling <code>gtk_widget_show()</code>). | The example shows how to get the default stack and push a newly created window on the stack. (Note that you also can do the same in a single stack by calling <code>gtk_widget_show()</code>). | ||
Line 143: | Line 138: | ||
'''Example 2.2. Pushing a new window into a stack''' | '''Example 2.2. Pushing a new window into a stack''' | ||
- | < | + | <tt> HildonWindowStack <span><font color="#990000"><nowiki>*</nowiki></font></span>stack <span><font color="#990000"><nowiki>=</nowiki></font></span> NULL<span><font color="#990000"><nowiki>;</nowiki></font></span> |
- | + | GtkWidget <span><font color="#990000"><nowiki>*</nowiki></font></span>window<span><font color="#990000"><nowiki>;</nowiki></font></span> | |
- | GtkWidget *window; | + | window <span><font color="#990000"><nowiki>=</nowiki></font></span> <span>'''<span><font color="#000000">hildon_stackable_window_new</font></span>'''</span> <span><font color="#990000">();</font></span> |
- | window = hildon_stackable_window_new (); | + | stack <span><font color="#990000"><nowiki>=</nowiki></font></span> <span>'''<span><font color="#000000">hildon_window_stack_get_default</font></span>'''</span> <span><font color="#990000">();</font></span> |
- | stack = hildon_window_stack_get_default (); | + | <span>'''<span><font color="#000000">hildon_window_stack_push_1</font></span>'''</span> <span><font color="#990000">(</font></span>stack<span><font color="#990000">,</font></span> <span>'''<span><font color="#000000">HILDON_STACKABLE_WINDOW</font></span>'''</span> <span><font color="#990000">(</font></span>window<span><font color="#990000">));</font></span></tt> |
- | hildon_window_stack_push_1 (stack, HILDON_STACKABLE_WINDOW (window)); | + | |
- | </ | + | |
The push functions also displays the window. <code>gdk_window_show()</code> is not needed after a push operation. | The push functions also displays the window. <code>gdk_window_show()</code> is not needed after a push operation. | ||
Line 157: | Line 150: | ||
'''Example 2.3. Pushing a list of windows into a stack''' | '''Example 2.3. Pushing a list of windows into a stack''' | ||
- | + | GList *list = NULL; | |
- | GList *list = NULL; | + | HildonWindowStack *stack = NULL; |
- | HildonWindowStack *stack = NULL; | + | HildonStackableWindow *window; |
- | HildonStackableWindow *window; | + | gint nwindows = 10; |
- | gint nwindows = 10; | + | |
- | + | stack = hildon_stackable_window_get_stack (window); | |
- | stack = hildon_stackable_window_get_stack (window); | + | |
- | + | while (nwindows > 0) { | |
- | while (nwindows > 0) { | + | parent = hildon_stackable_window_new (); |
- | + | list = g_list_append (list, window); | |
- | + | nwindows--; | |
- | + | } | |
- | } | + | hildon_window_stack_push_list (stack, list); |
- | hildon_window_stack_push_list (stack, list); | + | g_list_free (list); |
- | g_list_free (list); | + | |
- | + | ||
Similar functions exist for the pop operation. The example uses <code>hildon_window_stack_pop_list()</code> to pop N windows from the default stack and stores them in the list of arguments. Notice that <code>hildon_stackable_window_size()</code> is used to check the size of the stack. | Similar functions exist for the pop operation. The example uses <code>hildon_window_stack_pop_list()</code> to pop N windows from the default stack and stores them in the list of arguments. Notice that <code>hildon_stackable_window_size()</code> is used to check the size of the stack. | ||
Line 178: | Line 169: | ||
'''Example 2.4. Popping a number of windows from a stack into a list''' | '''Example 2.4. Popping a number of windows from a stack into a list''' | ||
- | < | + | <tt> GList <span><font color="#990000"><nowiki>*</nowiki></font></span>list <span><font color="#990000"><nowiki>=</nowiki></font></span> NULL<span><font color="#990000"><nowiki>;</nowiki></font></span> |
- | + | HildonWindowStack <span><font color="#990000"><nowiki>*</nowiki></font></span>stack<span><font color="#990000"><nowiki>;</nowiki></font></span> | |
- | HildonWindowStack *stack; | + | HildonStackableWindow <span><font color="#990000"><nowiki>*</nowiki></font></span>window<span><font color="#990000"><nowiki>;</nowiki></font></span> |
- | HildonStackableWindow *window; | + | gint nwindows <span><font color="#990000"><nowiki>=</nowiki></font></span> <span><font color="#993399">10</font></span><span><font color="#990000"><nowiki>;</nowiki></font></span> |
- | gint nwindows = 10; | + | stack <span><font color="#990000"><nowiki>=</nowiki></font></span> <span>'''<span><font color="#000000">hildon_stackable_window_get_default</font></span>'''</span> <span><font color="#990000">();</font></span> |
- | stack = hildon_stackable_window_get_default (); | + | <span>'''<span><font color="#0000FF">if</font></span>'''</span> <span><font color="#990000">(</font></span><span>'''<span><font color="#000000">hildon_stackable_window_size</font></span>'''</span> <span><font color="#990000">(</font></span>stack<span><font color="#990000">)</font></span> <span><font color="#990000">></font></span> nwindows<span><font color="#990000">)</font></span><span><font color="#FF0000">{</font></span> |
- | if (hildon_stackable_window_size (stack) > nwindows){ | + | <span>'''<span><font color="#000000">hildon_window_stack_pop</font></span>'''</span> <span><font color="#990000">(</font></span>stack<span><font color="#990000">,</font></span> nwindows<span><font color="#990000">,</font></span> list<span><font color="#990000">);</font></span> |
- | + | <span><font color="#FF0000">}</font></span></tt> | |
- | } | + | |
- | </ | + | |
HildonWindowStack object also provides more advanced functions to perform both pop and push operations at once such as, for example, <code>hildon_window_stack_pop_and_push()</code> or <code>hildon_window_stack_pop_and_push_list()</code>. These functions do everything in a single transition, so the user only sees the last pushed window. | HildonWindowStack object also provides more advanced functions to perform both pop and push operations at once such as, for example, <code>hildon_window_stack_pop_and_push()</code> or <code>hildon_window_stack_pop_and_push_list()</code>. These functions do everything in a single transition, so the user only sees the last pushed window. | ||
Line 209: | Line 198: | ||
==Dialogs == | ==Dialogs == | ||
- | |||
Dialog boxes are a convenient way to prompt the user for a small amount of input, for example to display a message, ask a question, or anything else that does not require extensive effort on the user's part. | Dialog boxes are a convenient way to prompt the user for a small amount of input, for example to display a message, ask a question, or anything else that does not require extensive effort on the user's part. | ||
- | Hildon provides specialized widgets to cover the most common dialog's use cases: | + | Hildon provides specialized widgets to cover the most common dialog's use cases: HildonNote and HildonBanner. |
- | + | HildonNote is useful to ask users a question and HildonBanner is used to show textual information which automatically disappear after a certain period of time without user interaction. For more information on these widgets, see [[Documentation/Maemo_5_Developer_Guide/Application_Development/Controls#Notification_widgets |Notification widgets]] . | |
- | Besides those widgets, Hildon provides also specialized GtkDialogs designed to cover different use cases: | + | Besides those widgets, Hildon provides also specialized GtkDialogs designed to cover different use cases: HildonPickerDialog and HildonWizardDialog. |
- | The widget | + | The widget HildonPickerDialog is used along with HildonPickerButton and HildonTouchSelector to give a way to make data selections. [[Documentation/Maemo_5_Developer_Guide/Application_Development/Data_selection|Data Selection]] explains the use of such widgets. |
- | To create a guided process which helps users accomplish complex tasks step by step, Hildon provides the | + | To create a guided process which helps users accomplish complex tasks step by step, Hildon provides the HildonWizardDialog widget. |
===HildonWizardDialog=== | ===HildonWizardDialog=== | ||
- | + | HildonWizardDialog is a widget that allows one to create a guided process. The dialog has three standard buttons, previous, next and finish, and contains several pages. Users can close the dialog by tapping the dimmed area outside the dialog's window. | |
- | + | ||
A good example of a guided process which can be implemented with this widget is the setup of a new e-mail account in an e-mail client. Users have to fill several entries through several steps to accomplish the setup of the new account. The process of installing an application is another example of the uses of this widget. | A good example of a guided process which can be implemented with this widget is the setup of a new e-mail account in an e-mail client. Users have to fill several entries through several steps to accomplish the setup of the new account. The process of installing an application is another example of the uses of this widget. | ||
- | This widget uses a | + | This widget uses a GtkNotebook that contains the actual wizard pages. The notebook widget is pointed by the property "wizard-notebook" of the wizard. You need to create the notebook as well as the pages that are displayed. For more information on GtkNotebook, see the GTK+ Reference Manual. |
To create a new wizard dialog, call: | To create a new wizard dialog, call: | ||
- | < | + | <tt>GtkWidget<span><font color="#990000"><nowiki>*</nowiki></font></span> <span>'''<span><font color="#000000">hildon_wizard_dialog_new</font></span>'''</span> <span><font color="#990000">(</font></span>GtkWindow <span><font color="#990000"><nowiki>*</nowiki></font></span>parent<span><font color="#990000">,</font></span> |
- | + | <span>'''<span><font color="#0000FF">const</font></span>'''</span> <span><font color="#009900">char</font></span> <span><font color="#990000"><nowiki>*</nowiki></font></span>wizard_name<span><font color="#990000">,</font></span> | |
- | + | GtkNotebook <span><font color="#990000"><nowiki>*</nowiki></font></span>notebook<span><font color="#990000">);</font></span> | |
- | + | </tt> | |
- | </ | + | |
The parent window is usually the current visible view. The wizard name is displayed as title in the wizard dialog. | The parent window is usually the current visible view. The wizard name is displayed as title in the wizard dialog. | ||
Line 242: | Line 228: | ||
Usually, you want to validate user input to decide whether it should move to the next step or not. To do that, set a user function by using: | Usually, you want to validate user input to decide whether it should move to the next step or not. To do that, set a user function by using: | ||
- | < | + | <tt><span>'''<span><font color="#000000">gboolean</font></span>'''</span> <span><font color="#990000">(*</font></span>HildonWizardDialogPageFunc<span><font color="#990000">)</font></span> <span><font color="#990000">(</font></span>GtkNotebook <span><font color="#990000"><nowiki>*</nowiki></font></span>notebook<span><font color="#990000">,</font></span> |
- | gboolean (*HildonWizardDialogPageFunc) (GtkNotebook *notebook, | + | gint current_page<span><font color="#990000">,</font></span> |
- | + | gpointer data<span><font color="#990000">);</font></span> | |
- | + | </tt> | |
- | </ | + | |
- | The function above sets the function " | + | The function above sets the function "page_func" to be used to decide whether the user can go to the next page when pressing the forward button. The function must have the following signature: |
- | < | + | <tt><span>'''<span><font color="#000000">gboolean</font></span>'''</span> <span><font color="#990000">(*</font></span>HildonWizardDialogPageFunc<span><font color="#990000">)</font></span> <span><font color="#990000">(</font></span>GtkNotebook <span><font color="#990000"><nowiki>*</nowiki></font></span>notebook<span><font color="#990000">,</font></span> |
- | gboolean (*HildonWizardDialogPageFunc) (GtkNotebook *notebook, | + | gint current_page<span><font color="#990000">,</font></span> |
- | + | gpointer data<span><font color="#990000">);</font></span> | |
- | + | </tt> | |
- | </ | + | |
- | Here, an example of using a | + | Here, an example of using a HildonWizardDialog |
- | [[Image:example_wizard_dialog.png| | + | [[Image:example_wizard_dialog.png | 400px]] |
'''Example 2.5. Example of a Hildon wizard dialog''' | '''Example 2.5. Example of a Hildon wizard dialog''' | ||
- | < | + | <tt><span>'''<span><font color="#000080"><nowiki>#include</nowiki></font></span>'''</span> <span><font color="#FF0000"><stdio.h></font></span> |
- | #include <stdio.h> | + | <span>'''<span><font color="#000080"><nowiki>#include</nowiki></font></span>'''</span> <span><font color="#FF0000"><stdlib.h></font></span> |
- | #include <stdlib.h> | + | <span>'''<span><font color="#000080"><nowiki>#include</nowiki></font></span>'''</span> <span><font color="#FF0000"><string.h></font></span> |
- | #include <string.h> | + | <span>'''<span><font color="#000080"><nowiki>#include</nowiki></font></span>'''</span> <span><font color="#FF0000"><hildon/hildon.h></font></span> |
- | #include <hildon/hildon.h> | + | gboolean |
- | + | <span>'''<span><font color="#000000">on_page_switch</font></span>'''</span> <span><font color="#990000">(</font></span>GtkNotebook <span><font color="#990000"><nowiki>*</nowiki></font></span>notebook<span><font color="#990000">,</font></span> | |
- | on_page_switch (GtkNotebook *notebook, | + | GtkNotebookPage <span><font color="#990000"><nowiki>*</nowiki></font></span>page<span><font color="#990000">,</font></span> |
- | + | guint num<span><font color="#990000">,</font></span> | |
- | + | HildonWizardDialog <span><font color="#990000"><nowiki>*</nowiki></font></span>dialog<span><font color="#990000">)</font></span> | |
- | + | <span><font color="#FF0000">{</font></span> | |
- | { | + | <span>'''<span><font color="#000000">g_debug</font></span>'''</span> <span><font color="#990000">(</font></span><span><font color="#FF0000">"Page %d"</font></span><span><font color="#990000">,</font></span> num<span><font color="#990000">);</font></span> |
- | + | <span>'''<span><font color="#0000FF">return</font></span>'''</span> TRUE<span><font color="#990000"><nowiki>;</nowiki></font></span> | |
- | + | <span><font color="#FF0000">}</font></span> | |
- | } | + | <span>'''<span><font color="#0000FF"> static</font></span>'''</span> gboolean |
- | + | <span>'''<span><font color="#000000">some_page_func</font></span>'''</span> <span><font color="#990000">(</font></span>GtkNotebook <span><font color="#990000"><nowiki>*</nowiki></font></span>nb<span><font color="#990000">,</font></span> | |
- | some_page_func (GtkNotebook *nb, | + | gint current<span><font color="#990000">,</font></span> |
- | + | gpointer userdata<span><font color="#990000">)</font></span> | |
- | + | <span><font color="#FF0000">{</font></span> | |
- | { | + | HildonEntry <span><font color="#990000"><nowiki>*</nowiki></font></span>entry<span><font color="#990000"><nowiki>;</nowiki></font></span> |
- | + | <span>''<span><font color="#9A1900">/* Validate data only for the third page. */</font></span>''</span> | |
- | + | <span>'''<span><font color="#0000FF">switch</font></span>'''</span> <span><font color="#990000">(</font></span>current<span><font color="#990000">)</font></span> <span><font color="#FF0000">{</font></span> | |
- | + | <span>'''<span><font color="#0000FF">case</font></span>'''</span> <span><font color="#993399">2</font></span><span><font color="#990000"><nowiki>:</nowiki></font></span> | |
- | + | entry <span><font color="#990000"><nowiki>=</nowiki></font></span> <span>'''<span><font color="#000000">HILDON_ENTRY</font></span>'''</span> <span><font color="#990000">(</font></span><span>'''<span><font color="#000000">gtk_notebook_get_nth_page</font></span>'''</span> <span><font color="#990000">(</font></span>nb<span><font color="#990000">,</font></span> current<span><font color="#990000">));</font></span> | |
- | + | <span>'''<span><font color="#0000FF">return</font></span>'''</span> <span><font color="#990000">(</font></span><span>'''<span><font color="#000000">strlen</font></span>'''</span> <span><font color="#990000">(</font></span><span>'''<span><font color="#000000">hildon_entry_get_text</font></span>'''</span> <span><font color="#990000">(</font></span>entry<span><font color="#990000">))</font></span> <span><font color="#990000"><nowiki>!=</nowiki></font></span> <span><font color="#993399">0</font></span><span><font color="#990000">);</font></span> | |
- | + | <span>'''<span><font color="#0000FF">default</font></span>'''</span><span><font color="#990000"><nowiki>:</nowiki></font></span> | |
- | + | <span>'''<span><font color="#0000FF">return</font></span>'''</span> TRUE<span><font color="#990000"><nowiki>;</nowiki></font></span> | |
- | + | <span><font color="#FF0000">}</font></span> | |
- | + | <span><font color="#FF0000">}</font></span> | |
- | } | + | <span><font color="#009900">int</font></span> |
- | + | <span>'''<span><font color="#000000">main</font></span>'''</span> <span><font color="#990000">(</font></span><span><font color="#009900">int</font></span> argc<span><font color="#990000">,</font></span> <span><font color="#009900">char</font></span> <span><font color="#990000"><nowiki>**</nowiki></font></span>argv<span><font color="#990000">)</font></span> | |
- | main (int argc, char **argv) | + | <span><font color="#FF0000">{</font></span> |
- | { | + | <span>'''<span><font color="#000000">hildon_gtk_init</font></span>'''</span> <span><font color="#990000">(&</font></span>argc<span><font color="#990000">,</font></span> <span><font color="#990000">&</font></span>argv<span><font color="#990000">);</font></span> |
- | + | GtkWidget <span><font color="#990000"><nowiki>*</nowiki></font></span>dialog<span><font color="#990000">,*</font></span>notebook<span><font color="#990000">,</font></span> <span><font color="#990000"><nowiki>*</nowiki></font></span>label_1<span><font color="#990000">,</font></span> <span><font color="#990000"><nowiki>*</nowiki></font></span>label_2<span><font color="#990000">,</font></span> <span><font color="#990000"><nowiki>*</nowiki></font></span>entry_3<span><font color="#990000">,</font></span> <span><font color="#990000"><nowiki>*</nowiki></font></span>label_4<span><font color="#990000"><nowiki>;</nowiki></font></span> | |
- | + | <span>''<span><font color="#9A1900">/* Create a notebook */</font></span>''</span> | |
- | + | notebook <span><font color="#990000"><nowiki>=</nowiki></font></span> <span>'''<span><font color="#000000">gtk_notebook_new</font></span>'''</span> <span><font color="#990000">();</font></span> | |
- | + | <span>''<span><font color="#9A1900">/* Create widgets to palce into the notebook's pages */</font></span>''</span> | |
- | + | label_1 <span><font color="#990000"><nowiki>=</nowiki></font></span> <span>'''<span><font color="#000000">gtk_label_new</font></span>'''</span> <span><font color="#990000">(</font></span><span><font color="#FF0000">"Page 1"</font></span><span><font color="#990000">);</font></span> | |
- | + | label_2 <span><font color="#990000"><nowiki>=</nowiki></font></span> <span>'''<span><font color="#000000">gtk_label_new</font></span>'''</span> <span><font color="#990000">(</font></span><span><font color="#FF0000">"Page 2"</font></span><span><font color="#990000">);</font></span> | |
- | + | entry_3 <span><font color="#990000"><nowiki>=</nowiki></font></span> <span>'''<span><font color="#000000">hildon_entry_new</font></span>'''</span> <span><font color="#990000">(</font></span>HILDON_SIZE_AUTO<span><font color="#990000">);</font></span> | |
- | + | <span>'''<span><font color="#000000">hildon_entry_set_placeholder</font></span>'''</span> <span><font color="#990000">(</font></span><span>'''<span><font color="#000000">HILDON_ENTRY</font></span>'''</span> <span><font color="#990000">(</font></span>entry_3<span><font color="#990000">),</font></span> | |
- | + | <span><font color="#FF0000">" Write something to continue"</font></span><span><font color="#990000">);</font></span> | |
- | + | label_4 <span><font color="#990000"><nowiki>=</nowiki></font></span> <span>'''<span><font color="#000000">gtk_label_new</font></span>'''</span> <span><font color="#990000">(</font></span><span><font color="#FF0000">"Page 4"</font></span><span><font color="#990000">);</font></span> | |
- | + | <span>''<span><font color="#9A1900">/* Append pages */</font></span>''</span> | |
- | + | <span>'''<span><font color="#000000">gtk_notebook_append_page</font></span>'''</span> <span><font color="#990000">(</font></span><span>'''<span><font color="#000000">GTK_NOTEBOOK</font></span>'''</span> <span><font color="#990000">(</font></span>notebook<span><font color="#990000">),</font></span> label_1<span><font color="#990000">,</font></span> NULL<span><font color="#990000">);</font></span> | |
- | + | <span>'''<span><font color="#000000">gtk_notebook_append_page</font></span>'''</span> <span><font color="#990000">(</font></span><span>'''<span><font color="#000000">GTK_NOTEBOOK</font></span>'''</span> <span><font color="#990000">(</font></span>notebook<span><font color="#990000">),</font></span> label_2<span><font color="#990000">,</font></span> NULL<span><font color="#990000">);</font></span> | |
- | + | <span>'''<span><font color="#000000">gtk_notebook_append_page</font></span>'''</span> <span><font color="#990000">(</font></span><span>'''<span><font color="#000000">GTK_NOTEBOOK</font></span>'''</span> <span><font color="#990000">(</font></span>notebook<span><font color="#990000">),</font></span> entry_3<span><font color="#990000">,</font></span> NULL<span><font color="#990000">);</font></span> | |
- | + | <span>'''<span><font color="#000000">gtk_notebook_append_page</font></span>'''</span> <span><font color="#990000">(</font></span><span>'''<span><font color="#000000">GTK_NOTEBOOK</font></span>'''</span> <span><font color="#990000">(</font></span>notebook<span><font color="#990000">),</font></span> label_4<span><font color="#990000">,</font></span> NULL<span><font color="#990000">);</font></span> | |
- | + | <span>''<span><font color="#9A1900">/* Create wizard dialog */</font></span>''</span> | |
- | + | dialog <span><font color="#990000"><nowiki>=</nowiki></font></span> <span>'''<span><font color="#000000">hildon_wizard_dialog_new</font></span>'''</span> <span><font color="#990000">(</font></span>NULL<span><font color="#990000">,</font></span> <span><font color="#FF0000">"Wizard"</font></span><span><font color="#990000">,</font></span> | |
- | + | <span>'''<span><font color="#000000">GTK_NOTEBOOK</font></span>'''</span> <span><font color="#990000">(</font></span>notebook<span><font color="#990000">));</font></span> | |
- | + | <span>''<span><font color="#9A1900">/* Set a handler for "switch-page" signal */</font></span>''</span> | |
- | + | <span>'''<span><font color="#000000">g_signal_connect</font></span>'''</span> <span><font color="#990000">(</font></span><span>'''<span><font color="#000000">G_OBJECT</font></span>'''</span> <span><font color="#990000">(</font></span>notebook<span><font color="#990000">),</font></span> | |
- | + | <span><font color="#FF0000">"switch-page"</font></span><span><font color="#990000">,</font></span> | |
- | + | <span>'''<span><font color="#000000">G_CALLBACK</font></span>'''</span> <span><font color="#990000">(</font></span>on_page_switch<span><font color="#990000">),</font></span> | |
- | + | dialog<span><font color="#990000">);</font></span> | |
- | + | <span>''<span><font color="#9A1900">/* Set a function to decide if user can go to next page */</font></span>''</span> | |
- | + | <span>'''<span><font color="#000000">hildon_wizard_dialog_set_forward_page_func</font></span>'''</span> <span><font color="#990000">(</font></span><span>'''<span><font color="#000000">HILDON_WIZARD_DIALOG</font></span>'''</span> <span><font color="#990000">(</font></span>dialog<span><font color="#990000">),</font></span> | |
- | + | some_page_func<span><font color="#990000">,</font></span> NULL<span><font color="#990000">,</font></span> NULL<span><font color="#990000">);</font></span> | |
- | + | <span>'''<span><font color="#000000">gtk_widget_show_all</font></span>'''</span> <span><font color="#990000">(</font></span>dialog<span><font color="#990000">);</font></span> | |
- | + | <span>'''<span><font color="#000000">gtk_dialog_run</font></span>'''</span> <span><font color="#990000">(</font></span><span>'''<span><font color="#000000">GTK_DIALOG</font></span>'''</span> <span><font color="#990000">(</font></span>dialog<span><font color="#990000">));</font></span> | |
- | + | <span>'''<span><font color="#0000FF">return</font></span>'''</span> <span><font color="#993399">0</font></span><span><font color="#990000"><nowiki>;</nowiki></font></span> | |
- | + | <span><font color="#FF0000">}</font></span> | |
- | } | + | </tt> |
- | </ | + | |
- | Apart from how to create and use a wizard dialog, this example also sets up a handler to catch the signal " | + | Apart from how to create and use a wizard dialog, this example also sets up a handler to catch the signal "switch-page" from the notepad. This signal is emitted by the widget GtkNotebook when the user or a function changes the current page. |
===Using GtkDialogs in Hildon applications=== | ===Using GtkDialogs in Hildon applications=== | ||
+ | In general, you can use GtkDialog much like you use it in a GTK+ application, but consider the following: | ||
- | + | * In Hildon applications, buttons "cancel", "reject" and "close" are allowed. However, buttons which emit the signal "response" with GTK_RESPONSE_CANCEL, GTK_RESPONSE_REJECT or GTK_RESPONSE_CLOSE as the response's identifier are not displayed. Therefore, if you need to deal with the action of closing a GtkDialog in a Hildon application, be aware of this detail and handle the GTK_RESPONSE_DELETE_EVENT response identifier properly. | |
- | + | * Another detail to take care of is that GtkDialogs can work in two modalities in a Hildon application: task-model or system-model. A dialog is task-modal if it is transient for the main window. That is the case when the function <code>gtk_window_set_transient_for()</code> is used or the dialog was created by calling gtk_dialog_new_with_buttons() specifying a parent window. Otherwise, the dialog is system-modal. | |
- | * In Hildon applications, buttons "cancel", "reject" and "close" are allowed. However, buttons which emit the signal " | + | |
- | * Another detail to take care of is that | + | |
If the dialog is task-modal, the Platform UI (Task button and Status area) are visible on top and can be used normally to switch between tasks. | If the dialog is task-modal, the Platform UI (Task button and Status area) are visible on top and can be used normally to switch between tasks. | ||
Line 344: | Line 326: | ||
'''Example 2.6. Application modal dialog example''' | '''Example 2.6. Application modal dialog example''' | ||
- | < | + | <tt><span>'''<span><font color="#000080"><nowiki>#include</nowiki></font></span>'''</span> <span><font color="#FF0000"><hildon/hildon.h></font></span> |
- | #include <hildon/hildon.h> | + | <span><font color="#009900">int</font></span> |
- | int | + | <span>'''<span><font color="#000000">main</font></span>'''</span> <span><font color="#990000">(</font></span><span><font color="#009900">int</font></span> argc<span><font color="#990000">,</font></span> |
- | main (int argc, | + | <span><font color="#009900">char</font></span> <span><font color="#990000"><nowiki>**</nowiki></font></span>argv<span><font color="#990000">)</font></span> |
- | + | <span><font color="#FF0000">{</font></span> | |
- | { | + | GtkWidget <span><font color="#990000"><nowiki>*</nowiki></font></span>dialog<span><font color="#990000"><nowiki>;</nowiki></font></span> |
- | + | GtkWidget <span><font color="#990000"><nowiki>*</nowiki></font></span>win<span><font color="#990000"><nowiki>;</nowiki></font></span> | |
- | + | <span>'''<span><font color="#000000">hildon_gtk_init</font></span>'''</span> <span><font color="#990000">(&</font></span>argc<span><font color="#990000">,</font></span> <span><font color="#990000">&</font></span>argv<span><font color="#990000">);</font></span> | |
- | + | win <span><font color="#990000"><nowiki>=</nowiki></font></span> <span>'''<span><font color="#000000">hildon_stackable_window_new</font></span>'''</span> <span><font color="#990000">()</font></span> <span><font color="#990000"><nowiki>;</nowiki></font></span> | |
- | + | <span>'''<span><font color="#000000">gtk_widget_show</font></span>'''</span> <span><font color="#990000">(</font></span>win<span><font color="#990000">);</font></span> | |
- | + | dialog <span><font color="#990000"><nowiki>=</nowiki></font></span> <span>'''<span><font color="#000000">gtk_dialog_new</font></span>'''</span> <span><font color="#990000">();</font></span> | |
- | + | <span>'''<span><font color="#000000">gtk_window_set_transient_for</font></span>'''</span> <span><font color="#990000">(</font></span><span>'''<span><font color="#000000">GTK_WINDOW</font></span>'''</span> <span><font color="#990000">(</font></span>dialog<span><font color="#990000">),</font></span> | |
- | + | <span>'''<span><font color="#000000">GTK_WINDOW</font></span>'''</span> <span><font color="#990000">(</font></span>win<span><font color="#990000">));</font></span> | |
- | + | <span>'''<span><font color="#000000">gtk_window_set_title</font></span>'''</span> <span><font color="#990000">(</font></span><span>'''<span><font color="#000000">GTK_WINDOW</font></span>'''</span> <span><font color="#990000">(</font></span>dialog<span><font color="#990000">),</font></span> <span><font color="#FF0000">"Hello!"</font></span><span><font color="#990000">);</font></span> | |
- | + | <span>'''<span><font color="#000000">gtk_widget_show_all</font></span>'''</span> <span><font color="#990000">(</font></span><span>'''<span><font color="#000000">GTK_WIDGET</font></span>'''</span> <span><font color="#990000">(</font></span>dialog<span><font color="#990000">));</font></span> | |
- | + | <span>'''<span><font color="#000000">gtk_dialog_run</font></span>'''</span> <span><font color="#990000">(</font></span><span>'''<span><font color="#000000">GTK_DIALOG</font></span>'''</span> <span><font color="#990000">(</font></span>dialog<span><font color="#990000">));</font></span> | |
- | + | <span>'''<span><font color="#0000FF">return</font></span>'''</span> <span><font color="#993399">0</font></span><span><font color="#990000"><nowiki>;</nowiki></font></span> | |
- | + | <span><font color="#FF0000">}</font></span> | |
- | } | + | </tt> |
- | </ | + | |
<hr/> | <hr/> |
Learn more about Contributing to the wiki.