2 * GTK - The GIMP Toolkit
3 * Copyright (C) 1999 Red Hat, Inc.
4 * Copyright (C) 2002 Anders Carlsson <andersca@gnu.org>
5 * Copyright (C) 2003 Matthias Clasen <mclasen@redhat.com>
6 * Copyright (C) 2005 Carlos Garnacho Parro <carlosg@gnome.org>
10 * This library is free software; you can redistribute it and/or
11 * modify it under the terms of the GNU Lesser General Public
12 * License as published by the Free Software Foundation; either
13 * version 2 of the License, or (at your option) any later version.
15 * This library is distributed in the hope that it will be useful,
16 * but WITHOUT ANY WARRANTY; without even the implied warranty of
17 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
18 * Lesser General Public License for more details.
20 * You should have received a copy of the GNU Lesser General Public
21 * License along with this library; if not, write to the
22 * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
23 * Boston, MA 02111-1307, USA.
27 * SECTION:gtkassistant
28 * @Short_description: A widget used to guide users through multi-step operations
29 * @Title: GtkAssistant
31 * A #GtkAssistant is a widget used to represent a generally complex
32 * operation splitted in several steps, guiding the user through its pages
33 * and controlling the page flow to collect the necessary data.
35 * The design of GtkAssistant is that it controls what buttons to show and
36 * to make sensitive, based on what it knows about the page sequence and
37 * the <link linkend="GtkAssistantPageType">type</link> of each page, in
38 * addition to state information like the page
39 * <link linkend="gtk-assistant-set-page-complete">completion</link> and
40 * <link linkend="gtk-assistant-commit">committed</link> status.
42 * If you have a case that doesn't quite fit in #GtkAssistants way of
43 * handling buttons, you can use the #GTK_ASSISTANT_PAGE_CUSTOM page type
44 * and handle buttons yourself.
46 * <refsect2 id="GtkAssistant-BUILDER-UI">
47 * <title>GtkAssistant as GtkBuildable</title>
49 * The GtkAssistant implementation of the GtkBuildable interface exposes the
50 * @action_area as internal children with the name "action_area".
52 * To add pages to an assistant in GtkBuilder, simply add it as a
53 * <child> to the GtkAssistant object, and set its child properties
63 #include "gtkassistant.h"
65 #include "gtkbutton.h"
68 #include "gtknotebook.h"
71 #include "gtksizegroup.h"
72 #include "gtksizerequest.h"
74 #include "gtktypebuiltins.h"
76 #include "gtkprivate.h"
77 #include "gtkbuildable.h"
78 #include "a11y/gtkwindowaccessible.h"
81 #define HEADER_SPACING 12
82 #define ACTION_AREA_SPACING 12
84 typedef struct _GtkAssistantPage GtkAssistantPage;
86 struct _GtkAssistantPage
88 GtkAssistantPageType type;
90 guint complete_set : 1;
95 GtkWidget *regular_title;
96 GtkWidget *current_title;
97 GdkPixbuf *header_image;
98 GdkPixbuf *sidebar_image;
101 struct _GtkAssistantPrivate
112 GtkWidget *action_area;
115 GSList *visited_pages;
116 GtkAssistantPage *current_page;
118 GtkSizeGroup *button_size_group;
119 GtkSizeGroup *title_size_group;
121 GtkAssistantPageFunc forward_function;
122 gpointer forward_function_data;
123 GDestroyNotify forward_data_destroy;
130 static void gtk_assistant_class_init (GtkAssistantClass *class);
131 static void gtk_assistant_init (GtkAssistant *assistant);
132 static void gtk_assistant_destroy (GtkWidget *widget);
133 static void gtk_assistant_map (GtkWidget *widget);
134 static void gtk_assistant_unmap (GtkWidget *widget);
135 static gboolean gtk_assistant_delete_event (GtkWidget *widget,
137 static void gtk_assistant_add (GtkContainer *container,
139 static void gtk_assistant_remove (GtkContainer *container,
141 static void gtk_assistant_set_child_property (GtkContainer *container,
146 static void gtk_assistant_get_child_property (GtkContainer *container,
152 static void gtk_assistant_buildable_interface_init (GtkBuildableIface *iface);
153 static GObject *gtk_assistant_buildable_get_internal_child (GtkBuildable *buildable,
155 const gchar *childname);
156 static gboolean gtk_assistant_buildable_custom_tag_start (GtkBuildable *buildable,
159 const gchar *tagname,
160 GMarkupParser *parser,
162 static void gtk_assistant_buildable_custom_finished (GtkBuildable *buildable,
165 const gchar *tagname,
168 static GList* find_page (GtkAssistant *assistant,
171 GType _gtk_assistant_accessible_get_type (void);
176 CHILD_PROP_PAGE_TYPE,
177 CHILD_PROP_PAGE_TITLE,
178 CHILD_PROP_PAGE_HEADER_IMAGE,
179 CHILD_PROP_PAGE_SIDEBAR_IMAGE,
180 CHILD_PROP_PAGE_COMPLETE
192 static guint signals [LAST_SIGNAL] = { 0 };
195 G_DEFINE_TYPE_WITH_CODE (GtkAssistant, gtk_assistant, GTK_TYPE_WINDOW,
196 G_IMPLEMENT_INTERFACE (GTK_TYPE_BUILDABLE,
197 gtk_assistant_buildable_interface_init))
201 gtk_assistant_class_init (GtkAssistantClass *class)
203 GObjectClass *gobject_class;
204 GtkWidgetClass *widget_class;
205 GtkContainerClass *container_class;
207 gobject_class = (GObjectClass *) class;
208 widget_class = (GtkWidgetClass *) class;
209 container_class = (GtkContainerClass *) class;
211 widget_class->destroy = gtk_assistant_destroy;
212 widget_class->map = gtk_assistant_map;
213 widget_class->unmap = gtk_assistant_unmap;
214 widget_class->delete_event = gtk_assistant_delete_event;
216 gtk_widget_class_set_accessible_type (widget_class, _gtk_assistant_accessible_get_type ());
218 container_class->add = gtk_assistant_add;
219 container_class->remove = gtk_assistant_remove;
220 container_class->set_child_property = gtk_assistant_set_child_property;
221 container_class->get_child_property = gtk_assistant_get_child_property;
224 * GtkAssistant::cancel:
225 * @assistant: the #GtkAssistant
227 * The ::cancel signal is emitted when then the cancel button is clicked.
232 g_signal_new (I_("cancel"),
233 G_TYPE_FROM_CLASS (gobject_class),
235 G_STRUCT_OFFSET (GtkAssistantClass, cancel),
237 g_cclosure_marshal_VOID__VOID,
241 * GtkAssistant::prepare:
242 * @assistant: the #GtkAssistant
243 * @page: the current page
245 * The ::prepare signal is emitted when a new page is set as the
246 * assistant's current page, before making the new page visible.
248 * A handler for this signal can do any preparations which are
249 * necessary before showing @page.
254 g_signal_new (I_("prepare"),
255 G_TYPE_FROM_CLASS (gobject_class),
257 G_STRUCT_OFFSET (GtkAssistantClass, prepare),
259 g_cclosure_marshal_VOID__OBJECT,
260 G_TYPE_NONE, 1, GTK_TYPE_WIDGET);
263 * GtkAssistant::apply:
264 * @assistant: the #GtkAssistant
266 * The ::apply signal is emitted when the apply button is clicked.
268 * The default behavior of the #GtkAssistant is to switch to the page
269 * after the current page, unless the current page is the last one.
271 * A handler for the ::apply signal should carry out the actions for
272 * which the wizard has collected data. If the action takes a long time
273 * to complete, you might consider putting a page of type
274 * %GTK_ASSISTANT_PAGE_PROGRESS after the confirmation page and handle
275 * this operation within the #GtkAssistant::prepare signal of the progress
281 g_signal_new (I_("apply"),
282 G_TYPE_FROM_CLASS (gobject_class),
284 G_STRUCT_OFFSET (GtkAssistantClass, apply),
286 g_cclosure_marshal_VOID__VOID,
290 * GtkAssistant::close:
291 * @assistant: the #GtkAssistant
293 * The ::close signal is emitted either when the close button of
294 * a summary page is clicked, or when the apply button in the last
295 * page in the flow (of type %GTK_ASSISTANT_PAGE_CONFIRM) is clicked.
300 g_signal_new (I_("close"),
301 G_TYPE_FROM_CLASS (gobject_class),
303 G_STRUCT_OFFSET (GtkAssistantClass, close),
305 g_cclosure_marshal_VOID__VOID,
308 gtk_widget_class_install_style_property (widget_class,
309 g_param_spec_int ("header-padding",
310 P_("Header Padding"),
311 P_("Number of pixels around the header."),
315 GTK_PARAM_READABLE));
316 gtk_widget_class_install_style_property (widget_class,
317 g_param_spec_int ("content-padding",
318 P_("Content Padding"),
319 P_("Number of pixels around the content pages."),
323 GTK_PARAM_READABLE));
326 * GtkAssistant:page-type:
328 * The type of the assistant page.
332 gtk_container_class_install_child_property (container_class,
333 CHILD_PROP_PAGE_TYPE,
334 g_param_spec_enum ("page-type",
336 P_("The type of the assistant page"),
337 GTK_TYPE_ASSISTANT_PAGE_TYPE,
338 GTK_ASSISTANT_PAGE_CONTENT,
339 GTK_PARAM_READWRITE));
342 * GtkAssistant:title:
344 * The title of the page.
348 gtk_container_class_install_child_property (container_class,
349 CHILD_PROP_PAGE_TITLE,
350 g_param_spec_string ("title",
352 P_("The title of the assistant page"),
354 GTK_PARAM_READWRITE));
357 * GtkAssistant:header-image:
359 * This image used to be displayed in the page header.
363 * Deprecated: 3.2: Since GTK+ 3.2, a header is no longer shown;
364 * add your header decoration to the page content instead.
366 gtk_container_class_install_child_property (container_class,
367 CHILD_PROP_PAGE_HEADER_IMAGE,
368 g_param_spec_object ("header-image",
370 P_("Header image for the assistant page"),
372 GTK_PARAM_READWRITE));
375 * GtkAssistant:sidebar-image:
377 * This image used to be displayed in the 'sidebar'.
381 * Deprecated: 3.2: Since GTK+ 3.2, the sidebar image is no longer shown.
383 gtk_container_class_install_child_property (container_class,
384 CHILD_PROP_PAGE_SIDEBAR_IMAGE,
385 g_param_spec_object ("sidebar-image",
387 P_("Sidebar image for the assistant page"),
389 GTK_PARAM_READWRITE));
392 * GtkAssistant:complete:
394 * Setting the "complete" child property to %TRUE marks a page as
395 * complete (i.e.: all the required fields are filled out). GTK+ uses
396 * this information to control the sensitivity of the navigation buttons.
400 gtk_container_class_install_child_property (container_class,
401 CHILD_PROP_PAGE_COMPLETE,
402 g_param_spec_boolean ("complete",
404 P_("Whether all required fields on the page have been filled out"),
408 g_type_class_add_private (gobject_class, sizeof (GtkAssistantPrivate));
412 default_forward_function (gint current_page, gpointer data)
414 GtkAssistant *assistant;
415 GtkAssistantPrivate *priv;
416 GtkAssistantPage *page_info;
419 assistant = GTK_ASSISTANT (data);
420 priv = assistant->priv;
422 page_node = g_list_nth (priv->pages, ++current_page);
427 page_info = (GtkAssistantPage *) page_node->data;
429 while (page_node && !gtk_widget_get_visible (page_info->page))
431 page_node = page_node->next;
435 page_info = (GtkAssistantPage *) page_node->data;
442 last_button_visible (GtkAssistant *assistant, GtkAssistantPage *page)
444 GtkAssistantPrivate *priv = assistant->priv;
445 GtkAssistantPage *page_info;
446 gint count, page_num, n_pages;
451 if (page->type != GTK_ASSISTANT_PAGE_CONTENT)
455 page_num = g_list_index (priv->pages, page);
456 n_pages = g_list_length (priv->pages);
459 while (page_num >= 0 && page_num < n_pages &&
460 page_info->type == GTK_ASSISTANT_PAGE_CONTENT &&
461 (count == 0 || page_info->complete) &&
464 page_num = (priv->forward_function) (page_num, priv->forward_function_data);
465 page_info = g_list_nth_data (priv->pages, page_num);
470 /* Make the last button visible if we can skip multiple
471 * pages and end on a confirmation or summary page
473 if (count > 1 && page_info &&
474 (page_info->type == GTK_ASSISTANT_PAGE_CONFIRM ||
475 page_info->type == GTK_ASSISTANT_PAGE_SUMMARY))
482 update_actions_size (GtkAssistant *assistant)
484 GtkAssistantPrivate *priv = assistant->priv;
486 GtkAssistantPage *page;
487 gint buttons, page_buttons;
489 if (!priv->current_page)
492 /* Some heuristics to find out how many buttons we should
493 * reserve space for. It is possible to trick this code
494 * with page forward functions and invisible pages, etc.
497 for (l = priv->pages; l; l = l->next)
501 if (!gtk_widget_get_visible (page->page))
504 page_buttons = 2; /* cancel, forward/apply/close */
505 if (l != priv->pages)
506 page_buttons += 1; /* back */
507 if (last_button_visible (assistant, page))
508 page_buttons += 1; /* last */
510 buttons = MAX (buttons, page_buttons);
513 buttons += priv->extra_buttons;
515 gtk_widget_set_size_request (priv->action_area,
516 buttons * gtk_widget_get_allocated_width (priv->cancel) + (buttons - 1) * 6,
521 compute_last_button_state (GtkAssistant *assistant)
523 GtkAssistantPrivate *priv = assistant->priv;
525 gtk_widget_set_sensitive (priv->last, priv->current_page->complete);
526 if (last_button_visible (assistant, priv->current_page))
527 gtk_widget_show (priv->last);
529 gtk_widget_hide (priv->last);
533 compute_progress_state (GtkAssistant *assistant)
535 GtkAssistantPrivate *priv = assistant->priv;
536 gint page_num, n_pages;
538 n_pages = gtk_assistant_get_n_pages (assistant);
539 page_num = gtk_assistant_get_current_page (assistant);
541 page_num = (priv->forward_function) (page_num, priv->forward_function_data);
543 if (page_num >= 0 && page_num < n_pages)
544 gtk_widget_show (priv->forward);
546 gtk_widget_hide (priv->forward);
550 update_buttons_state (GtkAssistant *assistant)
552 GtkAssistantPrivate *priv = assistant->priv;
554 if (!priv->current_page)
557 switch (priv->current_page->type)
559 case GTK_ASSISTANT_PAGE_INTRO:
560 gtk_widget_set_sensitive (priv->cancel, TRUE);
561 gtk_widget_set_sensitive (priv->forward, priv->current_page->complete);
562 gtk_widget_grab_default (priv->forward);
563 gtk_widget_show (priv->forward);
564 gtk_widget_hide (priv->back);
565 gtk_widget_hide (priv->apply);
566 gtk_widget_hide (priv->close);
567 compute_last_button_state (assistant);
569 case GTK_ASSISTANT_PAGE_CONFIRM:
570 gtk_widget_set_sensitive (priv->cancel, TRUE);
571 gtk_widget_set_sensitive (priv->back, TRUE);
572 gtk_widget_set_sensitive (priv->apply, priv->current_page->complete);
573 gtk_widget_grab_default (priv->apply);
574 gtk_widget_show (priv->back);
575 gtk_widget_show (priv->apply);
576 gtk_widget_hide (priv->forward);
577 gtk_widget_hide (priv->close);
578 gtk_widget_hide (priv->last);
580 case GTK_ASSISTANT_PAGE_CONTENT:
581 gtk_widget_set_sensitive (priv->cancel, TRUE);
582 gtk_widget_set_sensitive (priv->back, TRUE);
583 gtk_widget_set_sensitive (priv->forward, priv->current_page->complete);
584 gtk_widget_grab_default (priv->forward);
585 gtk_widget_show (priv->back);
586 gtk_widget_show (priv->forward);
587 gtk_widget_hide (priv->apply);
588 gtk_widget_hide (priv->close);
589 compute_last_button_state (assistant);
591 case GTK_ASSISTANT_PAGE_SUMMARY:
592 gtk_widget_set_sensitive (priv->close, priv->current_page->complete);
593 gtk_widget_grab_default (priv->close);
594 gtk_widget_show (priv->close);
595 gtk_widget_hide (priv->back);
596 gtk_widget_hide (priv->forward);
597 gtk_widget_hide (priv->apply);
598 gtk_widget_hide (priv->last);
600 case GTK_ASSISTANT_PAGE_PROGRESS:
601 gtk_widget_set_sensitive (priv->cancel, priv->current_page->complete);
602 gtk_widget_set_sensitive (priv->back, priv->current_page->complete);
603 gtk_widget_set_sensitive (priv->forward, priv->current_page->complete);
604 gtk_widget_grab_default (priv->forward);
605 gtk_widget_show (priv->back);
606 gtk_widget_hide (priv->apply);
607 gtk_widget_hide (priv->close);
608 gtk_widget_hide (priv->last);
609 compute_progress_state (assistant);
611 case GTK_ASSISTANT_PAGE_CUSTOM:
612 gtk_widget_hide (priv->cancel);
613 gtk_widget_hide (priv->back);
614 gtk_widget_hide (priv->forward);
615 gtk_widget_hide (priv->apply);
616 gtk_widget_hide (priv->last);
617 gtk_widget_hide (priv->close);
620 g_assert_not_reached ();
624 gtk_widget_hide (priv->cancel);
625 else if (priv->current_page->type == GTK_ASSISTANT_PAGE_SUMMARY ||
626 priv->current_page->type == GTK_ASSISTANT_PAGE_CUSTOM)
627 gtk_widget_hide (priv->cancel);
629 gtk_widget_show (priv->cancel);
631 /* this is quite general, we don't want to
632 * go back if it's the first page
634 if (!priv->visited_pages)
635 gtk_widget_hide (priv->back);
639 update_page_title_state (GtkAssistant *assistant, GList *list)
641 GtkAssistantPage *page, *other;
642 GtkAssistantPrivate *priv = assistant->priv;
648 if (page->title == NULL || page->title[0] == 0)
651 visible = gtk_widget_get_visible (page->page);
653 if (page == priv->current_page)
655 gtk_widget_set_visible (page->regular_title, FALSE);
656 gtk_widget_set_visible (page->current_title, visible);
660 /* If multiple consecutive pages have the same title,
661 * we only show it once, since it would otherwise look
662 * silly. We have to be a little careful, since we
663 * _always_ show the title of the current page.
667 other = list->prev->data;
668 if (g_strcmp0 (page->title, other->title) == 0)
671 for (l = list->next; l; l = l->next)
674 if (g_strcmp0 (page->title, other->title) != 0)
677 if (other == priv->current_page)
684 gtk_widget_set_visible (page->regular_title, visible);
685 gtk_widget_set_visible (page->current_title, FALSE);
692 update_title_state (GtkAssistant *assistant)
694 GtkAssistantPrivate *priv = assistant->priv;
696 gboolean show_titles;
699 for (l = priv->pages; l != NULL; l = l->next)
701 if (update_page_title_state (assistant, l))
705 gtk_widget_set_visible (priv->sidebar, show_titles);
709 set_current_page (GtkAssistant *assistant,
712 GtkAssistantPrivate *priv = assistant->priv;
714 priv->current_page = (GtkAssistantPage *)g_list_nth_data (priv->pages, page_num);
716 g_signal_emit (assistant, signals [PREPARE], 0, priv->current_page->page);
718 update_title_state (assistant);
720 gtk_notebook_set_current_page (GTK_NOTEBOOK (priv->content), page_num);
722 /* update buttons state, flow may have changed */
723 if (gtk_widget_get_mapped (GTK_WIDGET (assistant)))
724 update_buttons_state (assistant);
726 if (!gtk_widget_child_focus (priv->current_page->page, GTK_DIR_TAB_FORWARD))
728 GtkWidget *button[6];
731 /* find the best button to focus */
732 button[0] = priv->apply;
733 button[1] = priv->close;
734 button[2] = priv->forward;
735 button[3] = priv->back;
736 button[4] = priv->cancel;
737 button[5] = priv->last;
738 for (i = 0; i < 6; i++)
740 if (gtk_widget_get_visible (button[i]) &&
741 gtk_widget_get_sensitive (button[i]))
743 gtk_widget_grab_focus (button[i]);
749 gtk_widget_queue_resize (GTK_WIDGET (assistant));
753 compute_next_step (GtkAssistant *assistant)
755 GtkAssistantPrivate *priv = assistant->priv;
756 GtkAssistantPage *page_info;
757 gint current_page, n_pages, next_page;
759 current_page = gtk_assistant_get_current_page (assistant);
760 page_info = priv->current_page;
761 n_pages = gtk_assistant_get_n_pages (assistant);
763 next_page = (priv->forward_function) (current_page,
764 priv->forward_function_data);
766 if (next_page >= 0 && next_page < n_pages)
768 priv->visited_pages = g_slist_prepend (priv->visited_pages, page_info);
769 set_current_page (assistant, next_page);
778 on_assistant_close (GtkWidget *widget,
779 GtkAssistant *assistant)
781 g_signal_emit (assistant, signals [CLOSE], 0, NULL);
785 on_assistant_apply (GtkWidget *widget,
786 GtkAssistant *assistant)
790 g_signal_emit (assistant, signals [APPLY], 0);
792 success = compute_next_step (assistant);
794 /* if the assistant hasn't switched to another page, just emit
795 * the CLOSE signal, it't the last page in the assistant flow
798 g_signal_emit (assistant, signals [CLOSE], 0);
802 on_assistant_forward (GtkWidget *widget,
803 GtkAssistant *assistant)
805 gtk_assistant_next_page (assistant);
809 on_assistant_back (GtkWidget *widget,
810 GtkAssistant *assistant)
812 gtk_assistant_previous_page (assistant);
816 on_assistant_cancel (GtkWidget *widget,
817 GtkAssistant *assistant)
819 g_signal_emit (assistant, signals [CANCEL], 0, NULL);
823 on_assistant_last (GtkWidget *widget,
824 GtkAssistant *assistant)
826 GtkAssistantPrivate *priv = assistant->priv;
828 while (priv->current_page->type == GTK_ASSISTANT_PAGE_CONTENT &&
829 priv->current_page->complete)
830 compute_next_step (assistant);
834 alternative_button_order (GtkAssistant *assistant)
836 GtkSettings *settings;
840 screen = gtk_widget_get_screen (GTK_WIDGET (assistant));
841 settings = gtk_settings_get_for_screen (screen);
843 g_object_get (settings,
844 "gtk-alternative-button-order", &result,
850 assistant_sidebar_draw_cb (GtkWidget *widget,
855 GtkStyleContext *context;
857 width = gtk_widget_get_allocated_width (widget);
858 height = gtk_widget_get_allocated_height (widget);
859 context = gtk_widget_get_style_context (widget);
861 gtk_render_background (context, cr, 0, 0, width, height);
867 on_page_notify_visibility (GtkWidget *widget,
871 GtkAssistant *assistant = GTK_ASSISTANT (data);
873 if (gtk_widget_get_mapped (GTK_WIDGET (assistant)))
875 update_buttons_state (assistant);
876 update_title_state (assistant);
881 assistant_remove_page_cb (GtkNotebook *notebook,
883 GtkAssistant *assistant)
885 GtkAssistantPrivate *priv = assistant->priv;
886 GtkAssistantPage *page_info;
890 element = find_page (assistant, page);
894 page_info = element->data;
896 /* If this is the current page, we need to switch away. */
897 if (page_info == priv->current_page)
899 if (!compute_next_step (assistant))
901 /* The best we can do at this point is probably to pick
902 * the first visible page.
904 page_node = priv->pages;
907 !gtk_widget_get_visible (((GtkAssistantPage *) page_node->data)->page))
908 page_node = page_node->next;
910 if (page_node == element)
911 page_node = page_node->next;
914 priv->current_page = page_node->data;
916 priv->current_page = NULL;
920 g_signal_handlers_disconnect_by_func (page_info->page, on_page_notify_visibility, assistant);
922 gtk_size_group_remove_widget (priv->title_size_group, page_info->regular_title);
923 gtk_size_group_remove_widget (priv->title_size_group, page_info->current_title);
925 gtk_container_remove (GTK_CONTAINER (priv->sidebar), page_info->regular_title);
926 gtk_container_remove (GTK_CONTAINER (priv->sidebar), page_info->current_title);
928 priv->pages = g_list_remove_link (priv->pages, element);
929 priv->visited_pages = g_slist_remove_all (priv->visited_pages, page_info);
931 g_free (page_info->title);
933 g_slice_free (GtkAssistantPage, page_info);
934 g_list_free_1 (element);
936 if (gtk_widget_get_mapped (GTK_WIDGET (assistant)))
938 update_buttons_state (assistant);
939 update_actions_size (assistant);
944 gtk_assistant_init (GtkAssistant *assistant)
946 GtkAssistantPrivate *priv;
947 GtkStyleContext *context;
949 GtkWidget *content_box;
950 GtkWidget *sidebar_frame;
952 assistant->priv = G_TYPE_INSTANCE_GET_PRIVATE (assistant,
954 GtkAssistantPrivate);
955 priv = assistant->priv;
957 /* use border on inner panes instead */
958 gtk_container_set_border_width (GTK_CONTAINER (assistant), 0);
960 gtk_widget_push_composite_child ();
962 main_box = gtk_box_new (GTK_ORIENTATION_HORIZONTAL, 12);
963 priv->sidebar = gtk_box_new (GTK_ORIENTATION_VERTICAL, 6);
965 /* use a frame for the sidebar, and manually render a background
966 * in it. GtkFrame also gives us padding support for free.
968 sidebar_frame = gtk_frame_new (NULL);
969 context = gtk_widget_get_style_context (sidebar_frame);
970 gtk_style_context_add_class (context, GTK_STYLE_CLASS_SIDEBAR);
972 g_signal_connect (sidebar_frame, "draw",
973 G_CALLBACK (assistant_sidebar_draw_cb), assistant);
975 content_box = gtk_box_new (GTK_ORIENTATION_VERTICAL, 12);
976 gtk_container_set_border_width (GTK_CONTAINER (content_box), 12);
977 priv->content = gtk_notebook_new ();
978 gtk_notebook_set_show_border (GTK_NOTEBOOK (priv->content), FALSE);
979 gtk_notebook_set_show_tabs (GTK_NOTEBOOK (priv->content), FALSE);
980 priv->action_area = gtk_box_new (GTK_ORIENTATION_HORIZONTAL, 6);
982 g_signal_connect (priv->content, "remove",
983 G_CALLBACK (assistant_remove_page_cb), assistant);
985 gtk_container_add (GTK_CONTAINER (sidebar_frame), priv->sidebar);
986 gtk_box_pack_start (GTK_BOX (main_box), sidebar_frame, FALSE, FALSE, 0);
987 gtk_box_pack_start (GTK_BOX (main_box), content_box, TRUE, TRUE, 0);
988 gtk_box_pack_start (GTK_BOX (content_box), priv->content, TRUE, TRUE, 0);
989 gtk_box_pack_start (GTK_BOX (content_box), priv->action_area, FALSE, TRUE, 0);
990 gtk_widget_set_halign (priv->action_area, GTK_ALIGN_END);
992 gtk_widget_show_all (main_box);
994 gtk_widget_set_parent (main_box, GTK_WIDGET (assistant));
995 _gtk_bin_set_child (GTK_BIN (assistant), main_box);
997 priv->close = gtk_button_new_from_stock (GTK_STOCK_CLOSE);
998 priv->apply = gtk_button_new_from_stock (GTK_STOCK_APPLY);
999 priv->forward = gtk_button_new_with_mnemonic (_("C_ontinue"));
1000 gtk_button_set_image (GTK_BUTTON (priv->forward),
1001 gtk_image_new_from_stock (GTK_STOCK_GO_FORWARD, GTK_ICON_SIZE_BUTTON));
1002 priv->back = gtk_button_new_with_mnemonic (_("Go _Back"));
1003 gtk_button_set_image (GTK_BUTTON (priv->forward),
1004 gtk_image_new_from_stock (GTK_STOCK_GO_BACK, GTK_ICON_SIZE_BUTTON));
1005 priv->cancel = gtk_button_new_from_stock (GTK_STOCK_CANCEL);
1006 priv->last = gtk_button_new_with_mnemonic (_("_Finish"));
1007 gtk_button_set_image (GTK_BUTTON (priv->forward),
1008 gtk_image_new_from_stock (GTK_STOCK_GOTO_LAST, GTK_ICON_SIZE_BUTTON));
1009 gtk_widget_set_can_default (priv->close, TRUE);
1010 gtk_widget_set_can_default (priv->apply, TRUE);
1011 gtk_widget_set_can_default (priv->forward, TRUE);
1013 priv->button_size_group = gtk_size_group_new (GTK_SIZE_GROUP_HORIZONTAL);
1014 gtk_size_group_add_widget (priv->button_size_group, priv->close);
1015 gtk_size_group_add_widget (priv->button_size_group, priv->apply);
1016 gtk_size_group_add_widget (priv->button_size_group, priv->forward);
1017 gtk_size_group_add_widget (priv->button_size_group, priv->back);
1018 gtk_size_group_add_widget (priv->button_size_group, priv->cancel);
1019 gtk_size_group_add_widget (priv->button_size_group, priv->last);
1021 if (!alternative_button_order (assistant))
1023 gtk_box_pack_end (GTK_BOX (priv->action_area), priv->apply, FALSE, FALSE, 0);
1024 gtk_box_pack_end (GTK_BOX (priv->action_area), priv->forward, FALSE, FALSE, 0);
1025 gtk_box_pack_end (GTK_BOX (priv->action_area), priv->back, FALSE, FALSE, 0);
1026 gtk_box_pack_end (GTK_BOX (priv->action_area), priv->last, FALSE, FALSE, 0);
1027 gtk_box_pack_end (GTK_BOX (priv->action_area), priv->cancel, FALSE, FALSE, 0);
1028 gtk_box_pack_end (GTK_BOX (priv->action_area), priv->close, FALSE, FALSE, 0);
1032 gtk_box_pack_end (GTK_BOX (priv->action_area), priv->close, FALSE, FALSE, 0);
1033 gtk_box_pack_end (GTK_BOX (priv->action_area), priv->cancel, FALSE, FALSE, 0);
1034 gtk_box_pack_end (GTK_BOX (priv->action_area), priv->apply, FALSE, FALSE, 0);
1035 gtk_box_pack_end (GTK_BOX (priv->action_area), priv->forward, FALSE, FALSE, 0);
1036 gtk_box_pack_end (GTK_BOX (priv->action_area), priv->back, FALSE, FALSE, 0);
1037 gtk_box_pack_end (GTK_BOX (priv->action_area), priv->last, FALSE, FALSE, 0);
1040 gtk_widget_show (priv->forward);
1041 gtk_widget_show (priv->back);
1042 gtk_widget_show (priv->cancel);
1043 gtk_widget_show (priv->action_area);
1045 gtk_widget_pop_composite_child ();
1047 priv->title_size_group = gtk_size_group_new (GTK_SIZE_GROUP_HORIZONTAL);
1050 priv->current_page = NULL;
1051 priv->visited_pages = NULL;
1053 priv->forward_function = default_forward_function;
1054 priv->forward_function_data = assistant;
1055 priv->forward_data_destroy = NULL;
1057 g_signal_connect (G_OBJECT (priv->close), "clicked",
1058 G_CALLBACK (on_assistant_close), assistant);
1059 g_signal_connect (G_OBJECT (priv->apply), "clicked",
1060 G_CALLBACK (on_assistant_apply), assistant);
1061 g_signal_connect (G_OBJECT (priv->forward), "clicked",
1062 G_CALLBACK (on_assistant_forward), assistant);
1063 g_signal_connect (G_OBJECT (priv->back), "clicked",
1064 G_CALLBACK (on_assistant_back), assistant);
1065 g_signal_connect (G_OBJECT (priv->cancel), "clicked",
1066 G_CALLBACK (on_assistant_cancel), assistant);
1067 g_signal_connect (G_OBJECT (priv->last), "clicked",
1068 G_CALLBACK (on_assistant_last), assistant);
1072 gtk_assistant_set_child_property (GtkContainer *container,
1075 const GValue *value,
1078 switch (property_id)
1080 case CHILD_PROP_PAGE_TYPE:
1081 gtk_assistant_set_page_type (GTK_ASSISTANT (container), child,
1082 g_value_get_enum (value));
1084 case CHILD_PROP_PAGE_TITLE:
1085 gtk_assistant_set_page_title (GTK_ASSISTANT (container), child,
1086 g_value_get_string (value));
1088 case CHILD_PROP_PAGE_HEADER_IMAGE:
1089 gtk_assistant_set_page_header_image (GTK_ASSISTANT (container), child,
1090 g_value_get_object (value));
1092 case CHILD_PROP_PAGE_SIDEBAR_IMAGE:
1093 gtk_assistant_set_page_side_image (GTK_ASSISTANT (container), child,
1094 g_value_get_object (value));
1096 case CHILD_PROP_PAGE_COMPLETE:
1097 gtk_assistant_set_page_complete (GTK_ASSISTANT (container), child,
1098 g_value_get_boolean (value));
1101 GTK_CONTAINER_WARN_INVALID_CHILD_PROPERTY_ID (container, property_id, pspec);
1107 gtk_assistant_get_child_property (GtkContainer *container,
1113 switch (property_id)
1115 case CHILD_PROP_PAGE_TYPE:
1116 g_value_set_enum (value,
1117 gtk_assistant_get_page_type (GTK_ASSISTANT (container), child));
1119 case CHILD_PROP_PAGE_TITLE:
1120 g_value_set_string (value,
1121 gtk_assistant_get_page_title (GTK_ASSISTANT (container), child));
1123 case CHILD_PROP_PAGE_HEADER_IMAGE:
1124 g_value_set_object (value,
1125 gtk_assistant_get_page_header_image (GTK_ASSISTANT (container), child));
1127 case CHILD_PROP_PAGE_SIDEBAR_IMAGE:
1128 g_value_set_object (value,
1129 gtk_assistant_get_page_side_image (GTK_ASSISTANT (container), child));
1131 case CHILD_PROP_PAGE_COMPLETE:
1132 g_value_set_boolean (value,
1133 gtk_assistant_get_page_complete (GTK_ASSISTANT (container), child));
1136 GTK_CONTAINER_WARN_INVALID_CHILD_PROPERTY_ID (container, property_id, pspec);
1142 gtk_assistant_destroy (GtkWidget *widget)
1144 GtkAssistant *assistant = GTK_ASSISTANT (widget);
1145 GtkAssistantPrivate *priv = assistant->priv;
1147 /* We set current to NULL so that the remove code doesn't try
1148 * to do anything funny
1150 priv->current_page = NULL;
1154 GtkNotebook *notebook;
1157 /* Remove all pages from the content notebook. */
1158 notebook = (GtkNotebook *) priv->content;
1159 while ((page = gtk_notebook_get_nth_page (notebook, 0)) != NULL)
1160 gtk_container_remove ((GtkContainer *) notebook, page);
1162 /* Our GtkAssistantPage list should be empty now. */
1163 g_warn_if_fail (priv->pages == NULL);
1165 priv->content = NULL;
1169 priv->sidebar = NULL;
1171 if (priv->action_area)
1172 priv->action_area = NULL;
1174 if (priv->button_size_group)
1176 g_object_unref (priv->button_size_group);
1177 priv->button_size_group = NULL;
1180 if (priv->title_size_group)
1182 g_object_unref (priv->title_size_group);
1183 priv->title_size_group = NULL;
1186 if (priv->forward_function)
1188 if (priv->forward_function_data &&
1189 priv->forward_data_destroy)
1190 priv->forward_data_destroy (priv->forward_function_data);
1192 priv->forward_function = NULL;
1193 priv->forward_function_data = NULL;
1194 priv->forward_data_destroy = NULL;
1197 if (priv->visited_pages)
1199 g_slist_free (priv->visited_pages);
1200 priv->visited_pages = NULL;
1203 GTK_WIDGET_CLASS (gtk_assistant_parent_class)->destroy (widget);
1207 find_page (GtkAssistant *assistant,
1210 GtkAssistantPrivate *priv = assistant->priv;
1211 GList *child = priv->pages;
1215 GtkAssistantPage *page_info = child->data;
1216 if (page_info->page == page)
1219 child = child->next;
1226 gtk_assistant_map (GtkWidget *widget)
1228 GtkAssistant *assistant = GTK_ASSISTANT (widget);
1229 GtkAssistantPrivate *priv = assistant->priv;
1231 GtkAssistantPage *page;
1234 /* if there's no default page, pick the first one */
1237 if (!priv->current_page)
1239 page_node = priv->pages;
1241 while (page_node && !gtk_widget_get_visible (((GtkAssistantPage *) page_node->data)->page))
1243 page_node = page_node->next;
1248 page = page_node->data;
1251 if (page && gtk_widget_get_visible (page->page))
1252 set_current_page (assistant, page_num);
1254 update_buttons_state (assistant);
1255 update_actions_size (assistant);
1256 update_title_state (assistant);
1258 GTK_WIDGET_CLASS (gtk_assistant_parent_class)->map (widget);
1262 gtk_assistant_unmap (GtkWidget *widget)
1264 GtkAssistant *assistant = GTK_ASSISTANT (widget);
1265 GtkAssistantPrivate *priv = assistant->priv;
1267 g_slist_free (priv->visited_pages);
1268 priv->visited_pages = NULL;
1269 priv->current_page = NULL;
1271 GTK_WIDGET_CLASS (gtk_assistant_parent_class)->unmap (widget);
1275 gtk_assistant_delete_event (GtkWidget *widget,
1278 GtkAssistant *assistant = GTK_ASSISTANT (widget);
1279 GtkAssistantPrivate *priv = assistant->priv;
1281 /* Do not allow cancelling in the middle of a progress page */
1282 if (priv->current_page &&
1283 (priv->current_page->type != GTK_ASSISTANT_PAGE_PROGRESS ||
1284 priv->current_page->complete))
1285 g_signal_emit (widget, signals [CANCEL], 0, NULL);
1291 gtk_assistant_add (GtkContainer *container,
1294 gtk_assistant_append_page (GTK_ASSISTANT (container), page);
1298 gtk_assistant_remove (GtkContainer *container,
1301 GtkAssistant *assistant = (GtkAssistant*) container;
1303 /* Forward this removal to the content notebook. */
1304 container = (GtkContainer *) assistant->priv->content;
1305 gtk_container_remove (container, page);
1309 * gtk_assistant_new:
1311 * Creates a new #GtkAssistant.
1313 * Return value: a newly created #GtkAssistant
1318 gtk_assistant_new (void)
1320 GtkWidget *assistant;
1322 assistant = g_object_new (GTK_TYPE_ASSISTANT, NULL);
1328 * gtk_assistant_get_current_page:
1329 * @assistant: a #GtkAssistant
1331 * Returns the page number of the current page.
1333 * Return value: The index (starting from 0) of the current
1334 * page in the @assistant, or -1 if the @assistant has no pages,
1335 * or no current page.
1340 gtk_assistant_get_current_page (GtkAssistant *assistant)
1342 GtkAssistantPrivate *priv;
1344 g_return_val_if_fail (GTK_IS_ASSISTANT (assistant), -1);
1346 priv = assistant->priv;
1348 if (!priv->pages || !priv->current_page)
1351 return g_list_index (priv->pages, priv->current_page);
1355 * gtk_assistant_set_current_page:
1356 * @assistant: a #GtkAssistant
1357 * @page_num: index of the page to switch to, starting from 0.
1358 * If negative, the last page will be used. If greater
1359 * than the number of pages in the @assistant, nothing
1362 * Switches the page to @page_num.
1364 * Note that this will only be necessary in custom buttons,
1365 * as the @assistant flow can be set with
1366 * gtk_assistant_set_forward_page_func().
1371 gtk_assistant_set_current_page (GtkAssistant *assistant,
1374 GtkAssistantPrivate *priv;
1375 GtkAssistantPage *page;
1377 g_return_if_fail (GTK_IS_ASSISTANT (assistant));
1379 priv = assistant->priv;
1382 page = (GtkAssistantPage *) g_list_nth_data (priv->pages, page_num);
1385 page = (GtkAssistantPage *) g_list_last (priv->pages)->data;
1386 page_num = g_list_length (priv->pages);
1389 g_return_if_fail (page != NULL);
1391 if (priv->current_page == page)
1394 /* only add the page to the visited list if the assistant is mapped,
1395 * if not, just use it as an initial page setting, for the cases where
1396 * the initial page is != to 0
1398 if (gtk_widget_get_mapped (GTK_WIDGET (assistant)))
1399 priv->visited_pages = g_slist_prepend (priv->visited_pages,
1400 priv->current_page);
1402 set_current_page (assistant, page_num);
1406 * gtk_assistant_next_page:
1407 * @assistant: a #GtkAssistant
1409 * Navigate to the next page.
1411 * It is a programming error to call this function when
1412 * there is no next page.
1414 * This function is for use when creating pages of the
1415 * #GTK_ASSISTANT_PAGE_CUSTOM type.
1420 gtk_assistant_next_page (GtkAssistant *assistant)
1422 g_return_if_fail (GTK_IS_ASSISTANT (assistant));
1424 if (!compute_next_step (assistant))
1425 g_critical ("Page flow is broken.\n"
1426 "You may want to end it with a page of type\n"
1427 "GTK_ASSISTANT_PAGE_CONFIRM or GTK_ASSISTANT_PAGE_SUMMARY");
1431 * gtk_assistant_previous_page:
1432 * @assistant: a #GtkAssistant
1434 * Navigate to the previous visited page.
1436 * It is a programming error to call this function when
1437 * no previous page is available.
1439 * This function is for use when creating pages of the
1440 * #GTK_ASSISTANT_PAGE_CUSTOM type.
1445 gtk_assistant_previous_page (GtkAssistant *assistant)
1447 GtkAssistantPrivate *priv;
1448 GtkAssistantPage *page_info;
1451 g_return_if_fail (GTK_IS_ASSISTANT (assistant));
1453 priv = assistant->priv;
1455 /* skip the progress pages when going back */
1458 page_node = priv->visited_pages;
1460 g_return_if_fail (page_node != NULL);
1462 priv->visited_pages = priv->visited_pages->next;
1463 page_info = (GtkAssistantPage *) page_node->data;
1464 g_slist_free_1 (page_node);
1466 while (page_info->type == GTK_ASSISTANT_PAGE_PROGRESS ||
1467 !gtk_widget_get_visible (page_info->page));
1469 set_current_page (assistant, g_list_index (priv->pages, page_info));
1473 * gtk_assistant_get_n_pages:
1474 * @assistant: a #GtkAssistant
1476 * Returns the number of pages in the @assistant
1478 * Return value: the number of pages in the @assistant
1483 gtk_assistant_get_n_pages (GtkAssistant *assistant)
1485 GtkAssistantPrivate *priv;
1487 g_return_val_if_fail (GTK_IS_ASSISTANT (assistant), 0);
1489 priv = assistant->priv;
1491 return g_list_length (priv->pages);
1495 * gtk_assistant_get_nth_page:
1496 * @assistant: a #GtkAssistant
1497 * @page_num: the index of a page in the @assistant,
1498 * or -1 to get the last page
1500 * Returns the child widget contained in page number @page_num.
1502 * Return value: (transfer none): the child widget, or %NULL
1503 * if @page_num is out of bounds
1508 gtk_assistant_get_nth_page (GtkAssistant *assistant,
1511 GtkAssistantPrivate *priv;
1512 GtkAssistantPage *page;
1515 g_return_val_if_fail (GTK_IS_ASSISTANT (assistant), NULL);
1516 g_return_val_if_fail (page_num >= -1, NULL);
1518 priv = assistant->priv;
1521 elem = g_list_last (priv->pages);
1523 elem = g_list_nth (priv->pages, page_num);
1528 page = (GtkAssistantPage *) elem->data;
1534 * gtk_assistant_prepend_page:
1535 * @assistant: a #GtkAssistant
1536 * @page: a #GtkWidget
1538 * Prepends a page to the @assistant.
1540 * Return value: the index (starting at 0) of the inserted page
1545 gtk_assistant_prepend_page (GtkAssistant *assistant,
1548 g_return_val_if_fail (GTK_IS_ASSISTANT (assistant), 0);
1549 g_return_val_if_fail (GTK_IS_WIDGET (page), 0);
1551 return gtk_assistant_insert_page (assistant, page, 0);
1555 * gtk_assistant_append_page:
1556 * @assistant: a #GtkAssistant
1557 * @page: a #GtkWidget
1559 * Appends a page to the @assistant.
1561 * Return value: the index (starting at 0) of the inserted page
1566 gtk_assistant_append_page (GtkAssistant *assistant,
1569 g_return_val_if_fail (GTK_IS_ASSISTANT (assistant), 0);
1570 g_return_val_if_fail (GTK_IS_WIDGET (page), 0);
1572 return gtk_assistant_insert_page (assistant, page, -1);
1576 * gtk_assistant_insert_page:
1577 * @assistant: a #GtkAssistant
1578 * @page: a #GtkWidget
1579 * @position: the index (starting at 0) at which to insert the page,
1580 * or -1 to append the page to the @assistant
1582 * Inserts a page in the @assistant at a given position.
1584 * Return value: the index (starting from 0) of the inserted page
1589 gtk_assistant_insert_page (GtkAssistant *assistant,
1593 GtkAssistantPrivate *priv;
1594 GtkAssistantPage *page_info;
1596 GtkStyleContext *context;
1598 g_return_val_if_fail (GTK_IS_ASSISTANT (assistant), 0);
1599 g_return_val_if_fail (GTK_IS_WIDGET (page), 0);
1600 g_return_val_if_fail (gtk_widget_get_parent (page) == NULL, 0);
1601 g_return_val_if_fail (!gtk_widget_is_toplevel (page), 0);
1603 priv = assistant->priv;
1605 page_info = g_slice_new0 (GtkAssistantPage);
1606 page_info->page = page;
1607 page_info->regular_title = gtk_label_new (NULL);
1608 page_info->current_title = gtk_label_new (NULL);
1610 gtk_widget_set_halign (page_info->regular_title, GTK_ALIGN_START);
1611 gtk_widget_set_valign (page_info->regular_title, GTK_ALIGN_CENTER);
1612 gtk_widget_show (page_info->regular_title);
1614 gtk_widget_set_halign (page_info->current_title, GTK_ALIGN_START);
1615 gtk_widget_set_valign (page_info->current_title, GTK_ALIGN_CENTER);
1616 gtk_widget_hide (page_info->current_title);
1618 context = gtk_widget_get_style_context (page_info->current_title);
1619 gtk_style_context_add_class (context, GTK_STYLE_CLASS_HIGHLIGHT);
1621 gtk_size_group_add_widget (priv->title_size_group, page_info->regular_title);
1622 gtk_size_group_add_widget (priv->title_size_group, page_info->current_title);
1624 g_signal_connect (G_OBJECT (page), "notify::visible",
1625 G_CALLBACK (on_page_notify_visibility), assistant);
1627 n_pages = g_list_length (priv->pages);
1629 if (position < 0 || position > n_pages)
1632 priv->pages = g_list_insert (priv->pages, page_info, position);
1634 gtk_box_pack_start (GTK_BOX (priv->sidebar), page_info->regular_title, FALSE, FALSE, 0);
1635 gtk_box_pack_start (GTK_BOX (priv->sidebar), page_info->current_title, FALSE, FALSE, 0);
1636 gtk_box_reorder_child (GTK_BOX (priv->sidebar), page_info->regular_title, 2 * position);
1637 gtk_box_reorder_child (GTK_BOX (priv->sidebar), page_info->current_title, 2 * position + 1);
1639 gtk_notebook_insert_page (GTK_NOTEBOOK (priv->content), page, NULL, position);
1641 if (gtk_widget_get_mapped (GTK_WIDGET (assistant)))
1643 update_buttons_state (assistant);
1644 update_actions_size (assistant);
1651 * gtk_assistant_remove_page:
1652 * @assistant: a #GtkAssistant
1653 * @page_num: the index of a page in the @assistant,
1654 * or -1 to get the last page
1656 * Removes the @page_num's page from @assistant.
1661 gtk_assistant_remove_page (GtkAssistant *assistant,
1666 g_return_if_fail (GTK_IS_ASSISTANT (assistant));
1668 page = gtk_assistant_get_nth_page (assistant, page_num);
1671 gtk_assistant_remove (assistant, page);
1675 * gtk_assistant_set_forward_page_func:
1676 * @assistant: a #GtkAssistant
1677 * @page_func: (allow-none): the #GtkAssistantPageFunc, or %NULL
1678 * to use the default one
1679 * @data: user data for @page_func
1680 * @destroy: destroy notifier for @data
1682 * Sets the page forwarding function to be @page_func.
1684 * This function will be used to determine what will be
1685 * the next page when the user presses the forward button.
1686 * Setting @page_func to %NULL will make the assistant to
1687 * use the default forward function, which just goes to the
1688 * next visible page.
1693 gtk_assistant_set_forward_page_func (GtkAssistant *assistant,
1694 GtkAssistantPageFunc page_func,
1696 GDestroyNotify destroy)
1698 GtkAssistantPrivate *priv;
1700 g_return_if_fail (GTK_IS_ASSISTANT (assistant));
1702 priv = assistant->priv;
1704 if (priv->forward_data_destroy &&
1705 priv->forward_function_data)
1706 (*priv->forward_data_destroy) (priv->forward_function_data);
1710 priv->forward_function = page_func;
1711 priv->forward_function_data = data;
1712 priv->forward_data_destroy = destroy;
1716 priv->forward_function = default_forward_function;
1717 priv->forward_function_data = assistant;
1718 priv->forward_data_destroy = NULL;
1721 /* Page flow has possibly changed, so the
1722 * buttons state might need to change too
1724 if (gtk_widget_get_mapped (GTK_WIDGET (assistant)))
1725 update_buttons_state (assistant);
1729 * gtk_assistant_add_action_widget:
1730 * @assistant: a #GtkAssistant
1731 * @child: a #GtkWidget
1733 * Adds a widget to the action area of a #GtkAssistant.
1738 gtk_assistant_add_action_widget (GtkAssistant *assistant,
1741 GtkAssistantPrivate *priv;
1743 g_return_if_fail (GTK_IS_ASSISTANT (assistant));
1744 g_return_if_fail (GTK_IS_WIDGET (child));
1746 priv = assistant->priv;
1748 if (GTK_IS_BUTTON (child))
1750 gtk_size_group_add_widget (priv->button_size_group, child);
1751 priv->extra_buttons += 1;
1752 if (gtk_widget_get_mapped (GTK_WIDGET (assistant)))
1753 update_actions_size (assistant);
1756 gtk_box_pack_end (GTK_BOX (priv->action_area), child, FALSE, FALSE, 0);
1760 * gtk_assistant_remove_action_widget:
1761 * @assistant: a #GtkAssistant
1762 * @child: a #GtkWidget
1764 * Removes a widget from the action area of a #GtkAssistant.
1769 gtk_assistant_remove_action_widget (GtkAssistant *assistant,
1772 GtkAssistantPrivate *priv;
1774 g_return_if_fail (GTK_IS_ASSISTANT (assistant));
1775 g_return_if_fail (GTK_IS_WIDGET (child));
1777 priv = assistant->priv;
1779 if (GTK_IS_BUTTON (child))
1781 gtk_size_group_remove_widget (priv->button_size_group, child);
1782 priv->extra_buttons -= 1;
1783 if (gtk_widget_get_mapped (GTK_WIDGET (assistant)))
1784 update_actions_size (assistant);
1787 gtk_container_remove (GTK_CONTAINER (priv->action_area), child);
1791 * gtk_assistant_set_page_title:
1792 * @assistant: a #GtkAssistant
1793 * @page: a page of @assistant
1794 * @title: the new title for @page
1796 * Sets a title for @page.
1798 * The title is displayed in the header area of the assistant
1799 * when @page is the current page.
1804 gtk_assistant_set_page_title (GtkAssistant *assistant,
1808 GtkAssistantPage *page_info;
1811 g_return_if_fail (GTK_IS_ASSISTANT (assistant));
1812 g_return_if_fail (GTK_IS_WIDGET (page));
1814 child = find_page (assistant, page);
1816 g_return_if_fail (child != NULL);
1818 page_info = (GtkAssistantPage*) child->data;
1820 g_free (page_info->title);
1821 page_info->title = g_strdup (title);
1823 gtk_label_set_text ((GtkLabel*) page_info->regular_title, title);
1824 gtk_label_set_text ((GtkLabel*) page_info->current_title, title);
1826 gtk_widget_queue_resize (GTK_WIDGET (assistant));
1827 gtk_container_child_notify (GTK_CONTAINER (assistant), page, "title");
1831 * gtk_assistant_get_page_title:
1832 * @assistant: a #GtkAssistant
1833 * @page: a page of @assistant
1835 * Gets the title for @page.
1837 * Return value: the title for @page
1842 gtk_assistant_get_page_title (GtkAssistant *assistant,
1845 GtkAssistantPage *page_info;
1848 g_return_val_if_fail (GTK_IS_ASSISTANT (assistant), NULL);
1849 g_return_val_if_fail (GTK_IS_WIDGET (page), NULL);
1851 child = find_page (assistant, page);
1853 g_return_val_if_fail (child != NULL, NULL);
1855 page_info = (GtkAssistantPage*) child->data;
1857 return page_info->title;
1861 * gtk_assistant_set_page_type:
1862 * @assistant: a #GtkAssistant
1863 * @page: a page of @assistant
1864 * @type: the new type for @page
1866 * Sets the page type for @page.
1868 * The page type determines the page behavior in the @assistant.
1873 gtk_assistant_set_page_type (GtkAssistant *assistant,
1875 GtkAssistantPageType type)
1877 GtkAssistantPage *page_info;
1880 g_return_if_fail (GTK_IS_ASSISTANT (assistant));
1881 g_return_if_fail (GTK_IS_WIDGET (page));
1883 child = find_page (assistant, page);
1885 g_return_if_fail (child != NULL);
1887 page_info = (GtkAssistantPage*) child->data;
1889 if (type != page_info->type)
1891 page_info->type = type;
1893 /* backwards compatibility to the era before fixing bug 604289 */
1894 if (type == GTK_ASSISTANT_PAGE_SUMMARY && !page_info->complete_set)
1896 gtk_assistant_set_page_complete (assistant, page, TRUE);
1897 page_info->complete_set = FALSE;
1900 /* Always set buttons state, a change in a future page
1901 * might change current page buttons
1903 update_buttons_state (assistant);
1905 gtk_container_child_notify (GTK_CONTAINER (assistant), page, "page-type");
1910 * gtk_assistant_get_page_type:
1911 * @assistant: a #GtkAssistant
1912 * @page: a page of @assistant
1914 * Gets the page type of @page.
1916 * Return value: the page type of @page
1920 GtkAssistantPageType
1921 gtk_assistant_get_page_type (GtkAssistant *assistant,
1924 GtkAssistantPage *page_info;
1927 g_return_val_if_fail (GTK_IS_ASSISTANT (assistant), GTK_ASSISTANT_PAGE_CONTENT);
1928 g_return_val_if_fail (GTK_IS_WIDGET (page), GTK_ASSISTANT_PAGE_CONTENT);
1930 child = find_page (assistant, page);
1932 g_return_val_if_fail (child != NULL, GTK_ASSISTANT_PAGE_CONTENT);
1934 page_info = (GtkAssistantPage*) child->data;
1936 return page_info->type;
1940 * gtk_assistant_set_page_header_image:
1941 * @assistant: a #GtkAssistant
1942 * @page: a page of @assistant
1943 * @pixbuf: (allow-none): the new header image @page
1945 * Sets a header image for @page.
1949 * Deprecated: 3.2: Since GTK+ 3.2, a header is no longer shown;
1950 * add your header decoration to the page content instead.
1953 gtk_assistant_set_page_header_image (GtkAssistant *assistant,
1957 GtkAssistantPage *page_info;
1960 g_return_if_fail (GTK_IS_ASSISTANT (assistant));
1961 g_return_if_fail (GTK_IS_WIDGET (page));
1962 g_return_if_fail (pixbuf == NULL || GDK_IS_PIXBUF (pixbuf));
1964 child = find_page (assistant, page);
1966 g_return_if_fail (child != NULL);
1968 page_info = (GtkAssistantPage*) child->data;
1970 if (pixbuf != page_info->header_image)
1972 if (page_info->header_image)
1974 g_object_unref (page_info->header_image);
1975 page_info->header_image = NULL;
1979 page_info->header_image = g_object_ref (pixbuf);
1981 gtk_container_child_notify (GTK_CONTAINER (assistant), page, "header-image");
1986 * gtk_assistant_get_page_header_image:
1987 * @assistant: a #GtkAssistant
1988 * @page: a page of @assistant
1990 * Gets the header image for @page.
1992 * Return value: (transfer none): the header image for @page,
1993 * or %NULL if there's no header image for the page
1997 * Deprecated: 3.2: Since GTK+ 3.2, a header is no longer shown;
1998 * add your header decoration to the page content instead.
2001 gtk_assistant_get_page_header_image (GtkAssistant *assistant,
2004 GtkAssistantPage *page_info;
2007 g_return_val_if_fail (GTK_IS_ASSISTANT (assistant), NULL);
2008 g_return_val_if_fail (GTK_IS_WIDGET (page), NULL);
2010 child = find_page (assistant, page);
2012 g_return_val_if_fail (child != NULL, NULL);
2014 page_info = (GtkAssistantPage*) child->data;
2016 return page_info->header_image;
2020 * gtk_assistant_set_page_side_image:
2021 * @assistant: a #GtkAssistant
2022 * @page: a page of @assistant
2023 * @pixbuf: (allow-none): the new side image @page
2025 * Sets a side image for @page.
2027 * This image used to be displayed in the side area of the assistant
2028 * when @page is the current page.
2032 * Deprecated: 3.2: Since GTK+ 3.2, sidebar images are not
2036 gtk_assistant_set_page_side_image (GtkAssistant *assistant,
2040 GtkAssistantPage *page_info;
2043 g_return_if_fail (GTK_IS_ASSISTANT (assistant));
2044 g_return_if_fail (GTK_IS_WIDGET (page));
2045 g_return_if_fail (pixbuf == NULL || GDK_IS_PIXBUF (pixbuf));
2047 child = find_page (assistant, page);
2049 g_return_if_fail (child != NULL);
2051 page_info = (GtkAssistantPage*) child->data;
2053 if (pixbuf != page_info->sidebar_image)
2055 if (page_info->sidebar_image)
2057 g_object_unref (page_info->sidebar_image);
2058 page_info->sidebar_image = NULL;
2062 page_info->sidebar_image = g_object_ref (pixbuf);
2064 gtk_container_child_notify (GTK_CONTAINER (assistant), page, "sidebar-image");
2069 * gtk_assistant_get_page_side_image:
2070 * @assistant: a #GtkAssistant
2071 * @page: a page of @assistant
2073 * Gets the side image for @page.
2075 * Return value: (transfer none): the side image for @page,
2076 * or %NULL if there's no side image for the page
2080 * Deprecated: 3.2: Since GTK+ 3.2, sidebar images are not
2084 gtk_assistant_get_page_side_image (GtkAssistant *assistant,
2087 GtkAssistantPage *page_info;
2090 g_return_val_if_fail (GTK_IS_ASSISTANT (assistant), NULL);
2091 g_return_val_if_fail (GTK_IS_WIDGET (page), NULL);
2093 child = find_page (assistant, page);
2095 g_return_val_if_fail (child != NULL, NULL);
2097 page_info = (GtkAssistantPage*) child->data;
2099 return page_info->sidebar_image;
2103 * gtk_assistant_set_page_complete:
2104 * @assistant: a #GtkAssistant
2105 * @page: a page of @assistant
2106 * @complete: the completeness status of the page
2108 * Sets whether @page contents are complete.
2110 * This will make @assistant update the buttons state
2111 * to be able to continue the task.
2116 gtk_assistant_set_page_complete (GtkAssistant *assistant,
2120 GtkAssistantPage *page_info;
2123 g_return_if_fail (GTK_IS_ASSISTANT (assistant));
2124 g_return_if_fail (GTK_IS_WIDGET (page));
2126 child = find_page (assistant, page);
2128 g_return_if_fail (child != NULL);
2130 page_info = (GtkAssistantPage*) child->data;
2132 if (complete != page_info->complete)
2134 page_info->complete = complete;
2135 page_info->complete_set = TRUE;
2137 /* Always set buttons state, a change in a future page
2138 * might change current page buttons
2140 update_buttons_state (assistant);
2142 gtk_container_child_notify (GTK_CONTAINER (assistant), page, "complete");
2147 * gtk_assistant_get_page_complete:
2148 * @assistant: a #GtkAssistant
2149 * @page: a page of @assistant
2151 * Gets whether @page is complete.
2153 * Return value: %TRUE if @page is complete.
2158 gtk_assistant_get_page_complete (GtkAssistant *assistant,
2161 GtkAssistantPage *page_info;
2164 g_return_val_if_fail (GTK_IS_ASSISTANT (assistant), FALSE);
2165 g_return_val_if_fail (GTK_IS_WIDGET (page), FALSE);
2167 child = find_page (assistant, page);
2169 g_return_val_if_fail (child != NULL, FALSE);
2171 page_info = (GtkAssistantPage*) child->data;
2173 return page_info->complete;
2177 * gtk_assistant_update_buttons_state:
2178 * @assistant: a #GtkAssistant
2180 * Forces @assistant to recompute the buttons state.
2182 * GTK+ automatically takes care of this in most situations,
2183 * e.g. when the user goes to a different page, or when the
2184 * visibility or completeness of a page changes.
2186 * One situation where it can be necessary to call this
2187 * function is when changing a value on the current page
2188 * affects the future page flow of the assistant.
2193 gtk_assistant_update_buttons_state (GtkAssistant *assistant)
2195 g_return_if_fail (GTK_IS_ASSISTANT (assistant));
2197 update_buttons_state (assistant);
2201 * gtk_assistant_commit:
2202 * @assistant: a #GtkAssistant
2204 * Erases the visited page history so the back button is not
2205 * shown on the current page, and removes the cancel button
2206 * from subsequent pages.
2208 * Use this when the information provided up to the current
2209 * page is hereafter deemed permanent and cannot be modified
2210 * or undone. For example, showing a progress page to track
2211 * a long-running, unreversible operation after the user has
2212 * clicked apply on a confirmation page.
2217 gtk_assistant_commit (GtkAssistant *assistant)
2219 g_return_if_fail (GTK_IS_ASSISTANT (assistant));
2221 g_slist_free (assistant->priv->visited_pages);
2222 assistant->priv->visited_pages = NULL;
2224 assistant->priv->committed = TRUE;
2226 update_buttons_state (assistant);
2229 /* accessible implementation */
2231 /* dummy typedefs */
2232 typedef GtkWindowAccessible GtkAssistantAccessible;
2233 typedef GtkWindowAccessibleClass GtkAssistantAccessibleClass;
2235 G_DEFINE_TYPE (GtkAssistantAccessible, _gtk_assistant_accessible, GTK_TYPE_WINDOW_ACCESSIBLE);
2238 gtk_assistant_accessible_get_n_children (AtkObject *accessible)
2242 widget = gtk_accessible_get_widget (GTK_ACCESSIBLE (accessible));
2246 return g_list_length (GTK_ASSISTANT (widget)->priv->pages) + 1;
2250 gtk_assistant_accessible_ref_child (AtkObject *accessible,
2253 GtkAssistant *assistant;
2254 GtkAssistantPrivate *priv;
2255 GtkWidget *widget, *child;
2260 widget = gtk_accessible_get_widget (GTK_ACCESSIBLE (accessible));
2264 assistant = GTK_ASSISTANT (widget);
2265 priv = assistant->priv;
2266 n_pages = g_list_length (priv->pages);
2270 else if (index < n_pages)
2272 GtkAssistantPage *page = g_list_nth_data (priv->pages, index);
2275 title = gtk_assistant_get_page_title (assistant, child);
2277 else if (index == n_pages)
2279 child = priv->action_area;
2285 obj = gtk_widget_get_accessible (child);
2288 atk_object_set_name (obj, title);
2290 return g_object_ref (obj);
2294 _gtk_assistant_accessible_class_init (GtkAssistantAccessibleClass *klass)
2296 AtkObjectClass *atk_class = ATK_OBJECT_CLASS (klass);
2298 atk_class->get_n_children = gtk_assistant_accessible_get_n_children;
2299 atk_class->ref_child = gtk_assistant_accessible_ref_child;
2303 _gtk_assistant_accessible_init (GtkAssistantAccessible *self)
2307 /* buildable implementation */
2309 static GtkBuildableIface *parent_buildable_iface;
2312 gtk_assistant_buildable_interface_init (GtkBuildableIface *iface)
2314 parent_buildable_iface = g_type_interface_peek_parent (iface);
2315 iface->get_internal_child = gtk_assistant_buildable_get_internal_child;
2316 iface->custom_tag_start = gtk_assistant_buildable_custom_tag_start;
2317 iface->custom_finished = gtk_assistant_buildable_custom_finished;
2321 gtk_assistant_buildable_get_internal_child (GtkBuildable *buildable,
2322 GtkBuilder *builder,
2323 const gchar *childname)
2325 if (strcmp (childname, "action_area") == 0)
2326 return G_OBJECT (GTK_ASSISTANT (buildable)->priv->action_area);
2328 return parent_buildable_iface->get_internal_child (buildable,
2334 gtk_assistant_buildable_custom_tag_start (GtkBuildable *buildable,
2335 GtkBuilder *builder,
2337 const gchar *tagname,
2338 GMarkupParser *parser,
2341 return parent_buildable_iface->custom_tag_start (buildable, builder, child,
2342 tagname, parser, data);
2346 gtk_assistant_buildable_custom_finished (GtkBuildable *buildable,
2347 GtkBuilder *builder,
2349 const gchar *tagname,
2352 parent_buildable_iface->custom_finished (buildable, builder, child,
2353 tagname, user_data);