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, see <http://www.gnu.org/licenses/>.
25 * SECTION:gtkassistant
26 * @Short_description: A widget used to guide users through multi-step operations
27 * @Title: GtkAssistant
29 * A #GtkAssistant is a widget used to represent a generally complex
30 * operation splitted in several steps, guiding the user through its pages
31 * and controlling the page flow to collect the necessary data.
33 * The design of GtkAssistant is that it controls what buttons to show and
34 * to make sensitive, based on what it knows about the page sequence and
35 * the <link linkend="GtkAssistantPageType">type</link> of each page, in
36 * addition to state information like the page
37 * <link linkend="gtk-assistant-set-page-complete">completion</link> and
38 * <link linkend="gtk-assistant-commit">committed</link> status.
40 * If you have a case that doesn't quite fit in #GtkAssistants way of
41 * handling buttons, you can use the #GTK_ASSISTANT_PAGE_CUSTOM page type
42 * and handle buttons yourself.
44 * <refsect2 id="GtkAssistant-BUILDER-UI">
45 * <title>GtkAssistant as GtkBuildable</title>
47 * The GtkAssistant implementation of the GtkBuildable interface exposes the
48 * @action_area as internal children with the name "action_area".
50 * To add pages to an assistant in GtkBuilder, simply add it as a
51 * <child> to the GtkAssistant object, and set its child properties
61 #include "gtkassistant.h"
63 #include "gtkbutton.h"
66 #include "gtknotebook.h"
69 #include "gtksettings.h"
70 #include "gtksizegroup.h"
71 #include "gtksizerequest.h"
73 #include "gtktypebuiltins.h"
75 #include "gtkprivate.h"
76 #include "gtkbuildable.h"
77 #include "a11y/gtkwindowaccessible.h"
80 #define HEADER_SPACING 12
81 #define ACTION_AREA_SPACING 12
83 typedef struct _GtkAssistantPage GtkAssistantPage;
85 struct _GtkAssistantPage
87 GtkAssistantPageType type;
89 guint complete_set : 1;
94 GtkWidget *regular_title;
95 GtkWidget *current_title;
96 GdkPixbuf *header_image;
97 GdkPixbuf *sidebar_image;
100 struct _GtkAssistantPrivate
111 GtkWidget *action_area;
114 GSList *visited_pages;
115 GtkAssistantPage *current_page;
117 GtkSizeGroup *button_size_group;
118 GtkSizeGroup *title_size_group;
120 GtkAssistantPageFunc forward_function;
121 gpointer forward_function_data;
122 GDestroyNotify forward_data_destroy;
129 static void gtk_assistant_class_init (GtkAssistantClass *class);
130 static void gtk_assistant_init (GtkAssistant *assistant);
131 static void gtk_assistant_destroy (GtkWidget *widget);
132 static void gtk_assistant_map (GtkWidget *widget);
133 static void gtk_assistant_unmap (GtkWidget *widget);
134 static gboolean gtk_assistant_delete_event (GtkWidget *widget,
136 static void gtk_assistant_add (GtkContainer *container,
138 static void gtk_assistant_remove (GtkContainer *container,
140 static void gtk_assistant_set_child_property (GtkContainer *container,
145 static void gtk_assistant_get_child_property (GtkContainer *container,
151 static void gtk_assistant_buildable_interface_init (GtkBuildableIface *iface);
152 static GObject *gtk_assistant_buildable_get_internal_child (GtkBuildable *buildable,
154 const gchar *childname);
155 static gboolean gtk_assistant_buildable_custom_tag_start (GtkBuildable *buildable,
158 const gchar *tagname,
159 GMarkupParser *parser,
161 static void gtk_assistant_buildable_custom_finished (GtkBuildable *buildable,
164 const gchar *tagname,
167 static GList* find_page (GtkAssistant *assistant,
169 static void gtk_assistant_do_set_page_header_image (GtkAssistant *assistant,
172 static void gtk_assistant_do_set_page_side_image (GtkAssistant *assistant,
176 GType _gtk_assistant_accessible_get_type (void);
181 CHILD_PROP_PAGE_TYPE,
182 CHILD_PROP_PAGE_TITLE,
183 CHILD_PROP_PAGE_HEADER_IMAGE,
184 CHILD_PROP_PAGE_SIDEBAR_IMAGE,
185 CHILD_PROP_PAGE_COMPLETE
197 static guint signals [LAST_SIGNAL] = { 0 };
200 G_DEFINE_TYPE_WITH_CODE (GtkAssistant, gtk_assistant, GTK_TYPE_WINDOW,
201 G_IMPLEMENT_INTERFACE (GTK_TYPE_BUILDABLE,
202 gtk_assistant_buildable_interface_init))
206 gtk_assistant_class_init (GtkAssistantClass *class)
208 GObjectClass *gobject_class;
209 GtkWidgetClass *widget_class;
210 GtkContainerClass *container_class;
212 gobject_class = (GObjectClass *) class;
213 widget_class = (GtkWidgetClass *) class;
214 container_class = (GtkContainerClass *) class;
216 widget_class->destroy = gtk_assistant_destroy;
217 widget_class->map = gtk_assistant_map;
218 widget_class->unmap = gtk_assistant_unmap;
219 widget_class->delete_event = gtk_assistant_delete_event;
221 gtk_widget_class_set_accessible_type (widget_class, _gtk_assistant_accessible_get_type ());
223 container_class->add = gtk_assistant_add;
224 container_class->remove = gtk_assistant_remove;
225 container_class->set_child_property = gtk_assistant_set_child_property;
226 container_class->get_child_property = gtk_assistant_get_child_property;
229 * GtkAssistant::cancel:
230 * @assistant: the #GtkAssistant
232 * The ::cancel signal is emitted when then the cancel button is clicked.
237 g_signal_new (I_("cancel"),
238 G_TYPE_FROM_CLASS (gobject_class),
240 G_STRUCT_OFFSET (GtkAssistantClass, cancel),
242 g_cclosure_marshal_VOID__VOID,
246 * GtkAssistant::prepare:
247 * @assistant: the #GtkAssistant
248 * @page: the current page
250 * The ::prepare signal is emitted when a new page is set as the
251 * assistant's current page, before making the new page visible.
253 * A handler for this signal can do any preparations which are
254 * necessary before showing @page.
259 g_signal_new (I_("prepare"),
260 G_TYPE_FROM_CLASS (gobject_class),
262 G_STRUCT_OFFSET (GtkAssistantClass, prepare),
264 g_cclosure_marshal_VOID__OBJECT,
265 G_TYPE_NONE, 1, GTK_TYPE_WIDGET);
268 * GtkAssistant::apply:
269 * @assistant: the #GtkAssistant
271 * The ::apply signal is emitted when the apply button is clicked.
273 * The default behavior of the #GtkAssistant is to switch to the page
274 * after the current page, unless the current page is the last one.
276 * A handler for the ::apply signal should carry out the actions for
277 * which the wizard has collected data. If the action takes a long time
278 * to complete, you might consider putting a page of type
279 * %GTK_ASSISTANT_PAGE_PROGRESS after the confirmation page and handle
280 * this operation within the #GtkAssistant::prepare signal of the progress
286 g_signal_new (I_("apply"),
287 G_TYPE_FROM_CLASS (gobject_class),
289 G_STRUCT_OFFSET (GtkAssistantClass, apply),
291 g_cclosure_marshal_VOID__VOID,
295 * GtkAssistant::close:
296 * @assistant: the #GtkAssistant
298 * The ::close signal is emitted either when the close button of
299 * a summary page is clicked, or when the apply button in the last
300 * page in the flow (of type %GTK_ASSISTANT_PAGE_CONFIRM) is clicked.
305 g_signal_new (I_("close"),
306 G_TYPE_FROM_CLASS (gobject_class),
308 G_STRUCT_OFFSET (GtkAssistantClass, close),
310 g_cclosure_marshal_VOID__VOID,
313 gtk_widget_class_install_style_property (widget_class,
314 g_param_spec_int ("header-padding",
315 P_("Header Padding"),
316 P_("Number of pixels around the header."),
320 GTK_PARAM_READABLE));
321 gtk_widget_class_install_style_property (widget_class,
322 g_param_spec_int ("content-padding",
323 P_("Content Padding"),
324 P_("Number of pixels around the content pages."),
328 GTK_PARAM_READABLE));
331 * GtkAssistant:page-type:
333 * The type of the assistant page.
337 gtk_container_class_install_child_property (container_class,
338 CHILD_PROP_PAGE_TYPE,
339 g_param_spec_enum ("page-type",
341 P_("The type of the assistant page"),
342 GTK_TYPE_ASSISTANT_PAGE_TYPE,
343 GTK_ASSISTANT_PAGE_CONTENT,
344 GTK_PARAM_READWRITE));
347 * GtkAssistant:title:
349 * The title of the page.
353 gtk_container_class_install_child_property (container_class,
354 CHILD_PROP_PAGE_TITLE,
355 g_param_spec_string ("title",
357 P_("The title of the assistant page"),
359 GTK_PARAM_READWRITE));
362 * GtkAssistant:header-image:
364 * This image used to be displayed in the page header.
368 * Deprecated: 3.2: Since GTK+ 3.2, a header is no longer shown;
369 * add your header decoration to the page content instead.
371 gtk_container_class_install_child_property (container_class,
372 CHILD_PROP_PAGE_HEADER_IMAGE,
373 g_param_spec_object ("header-image",
375 P_("Header image for the assistant page"),
377 GTK_PARAM_READWRITE));
380 * GtkAssistant:sidebar-image:
382 * This image used to be displayed in the 'sidebar'.
386 * Deprecated: 3.2: Since GTK+ 3.2, the sidebar image is no longer shown.
388 gtk_container_class_install_child_property (container_class,
389 CHILD_PROP_PAGE_SIDEBAR_IMAGE,
390 g_param_spec_object ("sidebar-image",
392 P_("Sidebar image for the assistant page"),
394 GTK_PARAM_READWRITE));
397 * GtkAssistant:complete:
399 * Setting the "complete" child property to %TRUE marks a page as
400 * complete (i.e.: all the required fields are filled out). GTK+ uses
401 * this information to control the sensitivity of the navigation buttons.
405 gtk_container_class_install_child_property (container_class,
406 CHILD_PROP_PAGE_COMPLETE,
407 g_param_spec_boolean ("complete",
409 P_("Whether all required fields on the page have been filled out"),
413 g_type_class_add_private (gobject_class, sizeof (GtkAssistantPrivate));
417 default_forward_function (gint current_page, gpointer data)
419 GtkAssistant *assistant;
420 GtkAssistantPrivate *priv;
421 GtkAssistantPage *page_info;
424 assistant = GTK_ASSISTANT (data);
425 priv = assistant->priv;
427 page_node = g_list_nth (priv->pages, ++current_page);
432 page_info = (GtkAssistantPage *) page_node->data;
434 while (page_node && !gtk_widget_get_visible (page_info->page))
436 page_node = page_node->next;
440 page_info = (GtkAssistantPage *) page_node->data;
447 last_button_visible (GtkAssistant *assistant, GtkAssistantPage *page)
449 GtkAssistantPrivate *priv = assistant->priv;
450 GtkAssistantPage *page_info;
451 gint count, page_num, n_pages;
456 if (page->type != GTK_ASSISTANT_PAGE_CONTENT)
460 page_num = g_list_index (priv->pages, page);
461 n_pages = g_list_length (priv->pages);
464 while (page_num >= 0 && page_num < n_pages &&
465 page_info->type == GTK_ASSISTANT_PAGE_CONTENT &&
466 (count == 0 || page_info->complete) &&
469 page_num = (priv->forward_function) (page_num, priv->forward_function_data);
470 page_info = g_list_nth_data (priv->pages, page_num);
475 /* Make the last button visible if we can skip multiple
476 * pages and end on a confirmation or summary page
478 if (count > 1 && page_info &&
479 (page_info->type == GTK_ASSISTANT_PAGE_CONFIRM ||
480 page_info->type == GTK_ASSISTANT_PAGE_SUMMARY))
487 update_actions_size (GtkAssistant *assistant)
489 GtkAssistantPrivate *priv = assistant->priv;
491 GtkAssistantPage *page;
492 gint buttons, page_buttons;
494 if (!priv->current_page)
497 /* Some heuristics to find out how many buttons we should
498 * reserve space for. It is possible to trick this code
499 * with page forward functions and invisible pages, etc.
502 for (l = priv->pages; l; l = l->next)
506 if (!gtk_widget_get_visible (page->page))
509 page_buttons = 2; /* cancel, forward/apply/close */
510 if (l != priv->pages)
511 page_buttons += 1; /* back */
512 if (last_button_visible (assistant, page))
513 page_buttons += 1; /* last */
515 buttons = MAX (buttons, page_buttons);
518 buttons += priv->extra_buttons;
520 gtk_widget_set_size_request (priv->action_area,
521 buttons * gtk_widget_get_allocated_width (priv->cancel) + (buttons - 1) * 6,
526 compute_last_button_state (GtkAssistant *assistant)
528 GtkAssistantPrivate *priv = assistant->priv;
530 gtk_widget_set_sensitive (priv->last, priv->current_page->complete);
531 if (last_button_visible (assistant, priv->current_page))
532 gtk_widget_show (priv->last);
534 gtk_widget_hide (priv->last);
538 compute_progress_state (GtkAssistant *assistant)
540 GtkAssistantPrivate *priv = assistant->priv;
541 gint page_num, n_pages;
543 n_pages = gtk_assistant_get_n_pages (assistant);
544 page_num = gtk_assistant_get_current_page (assistant);
546 page_num = (priv->forward_function) (page_num, priv->forward_function_data);
548 if (page_num >= 0 && page_num < n_pages)
549 gtk_widget_show (priv->forward);
551 gtk_widget_hide (priv->forward);
555 update_buttons_state (GtkAssistant *assistant)
557 GtkAssistantPrivate *priv = assistant->priv;
559 if (!priv->current_page)
562 switch (priv->current_page->type)
564 case GTK_ASSISTANT_PAGE_INTRO:
565 gtk_widget_set_sensitive (priv->cancel, TRUE);
566 gtk_widget_set_sensitive (priv->forward, priv->current_page->complete);
567 gtk_widget_grab_default (priv->forward);
568 gtk_widget_show (priv->forward);
569 gtk_widget_hide (priv->back);
570 gtk_widget_hide (priv->apply);
571 gtk_widget_hide (priv->close);
572 compute_last_button_state (assistant);
574 case GTK_ASSISTANT_PAGE_CONFIRM:
575 gtk_widget_set_sensitive (priv->cancel, TRUE);
576 gtk_widget_set_sensitive (priv->back, TRUE);
577 gtk_widget_set_sensitive (priv->apply, priv->current_page->complete);
578 gtk_widget_grab_default (priv->apply);
579 gtk_widget_show (priv->back);
580 gtk_widget_show (priv->apply);
581 gtk_widget_hide (priv->forward);
582 gtk_widget_hide (priv->close);
583 gtk_widget_hide (priv->last);
585 case GTK_ASSISTANT_PAGE_CONTENT:
586 gtk_widget_set_sensitive (priv->cancel, TRUE);
587 gtk_widget_set_sensitive (priv->back, TRUE);
588 gtk_widget_set_sensitive (priv->forward, priv->current_page->complete);
589 gtk_widget_grab_default (priv->forward);
590 gtk_widget_show (priv->back);
591 gtk_widget_show (priv->forward);
592 gtk_widget_hide (priv->apply);
593 gtk_widget_hide (priv->close);
594 compute_last_button_state (assistant);
596 case GTK_ASSISTANT_PAGE_SUMMARY:
597 gtk_widget_set_sensitive (priv->close, priv->current_page->complete);
598 gtk_widget_grab_default (priv->close);
599 gtk_widget_show (priv->close);
600 gtk_widget_hide (priv->back);
601 gtk_widget_hide (priv->forward);
602 gtk_widget_hide (priv->apply);
603 gtk_widget_hide (priv->last);
605 case GTK_ASSISTANT_PAGE_PROGRESS:
606 gtk_widget_set_sensitive (priv->cancel, priv->current_page->complete);
607 gtk_widget_set_sensitive (priv->back, priv->current_page->complete);
608 gtk_widget_set_sensitive (priv->forward, priv->current_page->complete);
609 gtk_widget_grab_default (priv->forward);
610 gtk_widget_show (priv->back);
611 gtk_widget_hide (priv->apply);
612 gtk_widget_hide (priv->close);
613 gtk_widget_hide (priv->last);
614 compute_progress_state (assistant);
616 case GTK_ASSISTANT_PAGE_CUSTOM:
617 gtk_widget_hide (priv->cancel);
618 gtk_widget_hide (priv->back);
619 gtk_widget_hide (priv->forward);
620 gtk_widget_hide (priv->apply);
621 gtk_widget_hide (priv->last);
622 gtk_widget_hide (priv->close);
625 g_assert_not_reached ();
629 gtk_widget_hide (priv->cancel);
630 else if (priv->current_page->type == GTK_ASSISTANT_PAGE_SUMMARY ||
631 priv->current_page->type == GTK_ASSISTANT_PAGE_CUSTOM)
632 gtk_widget_hide (priv->cancel);
634 gtk_widget_show (priv->cancel);
636 /* this is quite general, we don't want to
637 * go back if it's the first page
639 if (!priv->visited_pages)
640 gtk_widget_hide (priv->back);
644 update_page_title_state (GtkAssistant *assistant, GList *list)
646 GtkAssistantPage *page, *other;
647 GtkAssistantPrivate *priv = assistant->priv;
653 if (page->title == NULL || page->title[0] == 0)
656 visible = gtk_widget_get_visible (page->page);
658 if (page == priv->current_page)
660 gtk_widget_set_visible (page->regular_title, FALSE);
661 gtk_widget_set_visible (page->current_title, visible);
665 /* If multiple consecutive pages have the same title,
666 * we only show it once, since it would otherwise look
667 * silly. We have to be a little careful, since we
668 * _always_ show the title of the current page.
672 other = list->prev->data;
673 if (g_strcmp0 (page->title, other->title) == 0)
676 for (l = list->next; l; l = l->next)
679 if (g_strcmp0 (page->title, other->title) != 0)
682 if (other == priv->current_page)
689 gtk_widget_set_visible (page->regular_title, visible);
690 gtk_widget_set_visible (page->current_title, FALSE);
697 update_title_state (GtkAssistant *assistant)
699 GtkAssistantPrivate *priv = assistant->priv;
701 gboolean show_titles;
704 for (l = priv->pages; l != NULL; l = l->next)
706 if (update_page_title_state (assistant, l))
710 gtk_widget_set_visible (priv->sidebar, show_titles);
714 set_current_page (GtkAssistant *assistant,
717 GtkAssistantPrivate *priv = assistant->priv;
719 priv->current_page = (GtkAssistantPage *)g_list_nth_data (priv->pages, page_num);
721 g_signal_emit (assistant, signals [PREPARE], 0, priv->current_page->page);
722 /* do not continue if the prepare signal handler has already changed the
724 if (priv->current_page != (GtkAssistantPage *)g_list_nth_data (priv->pages, page_num))
727 update_title_state (assistant);
729 gtk_notebook_set_current_page (GTK_NOTEBOOK (priv->content), page_num);
731 /* update buttons state, flow may have changed */
732 if (gtk_widget_get_mapped (GTK_WIDGET (assistant)))
733 update_buttons_state (assistant);
735 if (!gtk_widget_child_focus (priv->current_page->page, GTK_DIR_TAB_FORWARD))
737 GtkWidget *button[6];
740 /* find the best button to focus */
741 button[0] = priv->apply;
742 button[1] = priv->close;
743 button[2] = priv->forward;
744 button[3] = priv->back;
745 button[4] = priv->cancel;
746 button[5] = priv->last;
747 for (i = 0; i < 6; i++)
749 if (gtk_widget_get_visible (button[i]) &&
750 gtk_widget_get_sensitive (button[i]))
752 gtk_widget_grab_focus (button[i]);
758 gtk_widget_queue_resize (GTK_WIDGET (assistant));
762 compute_next_step (GtkAssistant *assistant)
764 GtkAssistantPrivate *priv = assistant->priv;
765 GtkAssistantPage *page_info;
766 gint current_page, n_pages, next_page;
768 current_page = gtk_assistant_get_current_page (assistant);
769 page_info = priv->current_page;
770 n_pages = gtk_assistant_get_n_pages (assistant);
772 next_page = (priv->forward_function) (current_page,
773 priv->forward_function_data);
775 if (next_page >= 0 && next_page < n_pages)
777 priv->visited_pages = g_slist_prepend (priv->visited_pages, page_info);
778 set_current_page (assistant, next_page);
787 on_assistant_close (GtkWidget *widget,
788 GtkAssistant *assistant)
790 g_signal_emit (assistant, signals [CLOSE], 0, NULL);
794 on_assistant_apply (GtkWidget *widget,
795 GtkAssistant *assistant)
799 g_signal_emit (assistant, signals [APPLY], 0);
801 success = compute_next_step (assistant);
803 /* if the assistant hasn't switched to another page, just emit
804 * the CLOSE signal, it't the last page in the assistant flow
807 g_signal_emit (assistant, signals [CLOSE], 0);
811 on_assistant_forward (GtkWidget *widget,
812 GtkAssistant *assistant)
814 gtk_assistant_next_page (assistant);
818 on_assistant_back (GtkWidget *widget,
819 GtkAssistant *assistant)
821 gtk_assistant_previous_page (assistant);
825 on_assistant_cancel (GtkWidget *widget,
826 GtkAssistant *assistant)
828 g_signal_emit (assistant, signals [CANCEL], 0, NULL);
832 on_assistant_last (GtkWidget *widget,
833 GtkAssistant *assistant)
835 GtkAssistantPrivate *priv = assistant->priv;
837 while (priv->current_page->type == GTK_ASSISTANT_PAGE_CONTENT &&
838 priv->current_page->complete)
839 compute_next_step (assistant);
843 alternative_button_order (GtkAssistant *assistant)
845 GtkSettings *settings;
849 screen = gtk_widget_get_screen (GTK_WIDGET (assistant));
850 settings = gtk_settings_get_for_screen (screen);
852 g_object_get (settings,
853 "gtk-alternative-button-order", &result,
859 assistant_sidebar_draw_cb (GtkWidget *widget,
864 GtkStyleContext *context;
866 width = gtk_widget_get_allocated_width (widget);
867 height = gtk_widget_get_allocated_height (widget);
868 context = gtk_widget_get_style_context (widget);
870 gtk_render_background (context, cr, 0, 0, width, height);
876 on_page_notify_visibility (GtkWidget *widget,
880 GtkAssistant *assistant = GTK_ASSISTANT (data);
882 if (gtk_widget_get_mapped (GTK_WIDGET (assistant)))
884 update_buttons_state (assistant);
885 update_title_state (assistant);
890 assistant_remove_page_cb (GtkNotebook *notebook,
892 GtkAssistant *assistant)
894 GtkAssistantPrivate *priv = assistant->priv;
895 GtkAssistantPage *page_info;
899 element = find_page (assistant, page);
903 page_info = element->data;
905 /* If this is the current page, we need to switch away. */
906 if (page_info == priv->current_page)
908 if (!compute_next_step (assistant))
910 /* The best we can do at this point is probably to pick
911 * the first visible page.
913 page_node = priv->pages;
916 !gtk_widget_get_visible (((GtkAssistantPage *) page_node->data)->page))
917 page_node = page_node->next;
919 if (page_node == element)
920 page_node = page_node->next;
923 priv->current_page = page_node->data;
925 priv->current_page = NULL;
929 g_signal_handlers_disconnect_by_func (page_info->page, on_page_notify_visibility, assistant);
931 gtk_size_group_remove_widget (priv->title_size_group, page_info->regular_title);
932 gtk_size_group_remove_widget (priv->title_size_group, page_info->current_title);
934 gtk_container_remove (GTK_CONTAINER (priv->sidebar), page_info->regular_title);
935 gtk_container_remove (GTK_CONTAINER (priv->sidebar), page_info->current_title);
937 priv->pages = g_list_remove_link (priv->pages, element);
938 priv->visited_pages = g_slist_remove_all (priv->visited_pages, page_info);
940 g_free (page_info->title);
942 g_slice_free (GtkAssistantPage, page_info);
943 g_list_free_1 (element);
945 if (gtk_widget_get_mapped (GTK_WIDGET (assistant)))
947 update_buttons_state (assistant);
948 update_actions_size (assistant);
953 gtk_assistant_init (GtkAssistant *assistant)
955 GtkAssistantPrivate *priv;
956 GtkStyleContext *context;
958 GtkWidget *content_box;
959 GtkWidget *sidebar_frame;
961 assistant->priv = G_TYPE_INSTANCE_GET_PRIVATE (assistant,
963 GtkAssistantPrivate);
964 priv = assistant->priv;
966 /* use border on inner panes instead */
967 gtk_container_set_border_width (GTK_CONTAINER (assistant), 0);
969 gtk_widget_push_composite_child ();
971 main_box = gtk_box_new (GTK_ORIENTATION_HORIZONTAL, 12);
972 priv->sidebar = gtk_box_new (GTK_ORIENTATION_VERTICAL, 6);
974 /* use a frame for the sidebar, and manually render a background
975 * in it. GtkFrame also gives us padding support for free.
977 sidebar_frame = gtk_frame_new (NULL);
978 context = gtk_widget_get_style_context (sidebar_frame);
979 gtk_style_context_add_class (context, GTK_STYLE_CLASS_SIDEBAR);
981 g_signal_connect (sidebar_frame, "draw",
982 G_CALLBACK (assistant_sidebar_draw_cb), assistant);
984 content_box = gtk_box_new (GTK_ORIENTATION_VERTICAL, 12);
985 gtk_container_set_border_width (GTK_CONTAINER (content_box), 12);
986 priv->content = gtk_notebook_new ();
987 gtk_notebook_set_show_border (GTK_NOTEBOOK (priv->content), FALSE);
988 gtk_notebook_set_show_tabs (GTK_NOTEBOOK (priv->content), FALSE);
989 priv->action_area = gtk_box_new (GTK_ORIENTATION_HORIZONTAL, 6);
991 g_signal_connect (priv->content, "remove",
992 G_CALLBACK (assistant_remove_page_cb), assistant);
994 gtk_container_add (GTK_CONTAINER (sidebar_frame), priv->sidebar);
995 gtk_box_pack_start (GTK_BOX (main_box), sidebar_frame, FALSE, FALSE, 0);
996 gtk_box_pack_start (GTK_BOX (main_box), content_box, TRUE, TRUE, 0);
997 gtk_box_pack_start (GTK_BOX (content_box), priv->content, TRUE, TRUE, 0);
998 gtk_box_pack_start (GTK_BOX (content_box), priv->action_area, FALSE, TRUE, 0);
999 gtk_widget_set_halign (priv->action_area, GTK_ALIGN_END);
1001 gtk_widget_show_all (main_box);
1003 gtk_widget_set_parent (main_box, GTK_WIDGET (assistant));
1004 _gtk_bin_set_child (GTK_BIN (assistant), main_box);
1006 priv->close = gtk_button_new_from_stock (GTK_STOCK_CLOSE);
1007 priv->apply = gtk_button_new_from_stock (GTK_STOCK_APPLY);
1008 priv->forward = gtk_button_new_with_mnemonic (_("C_ontinue"));
1009 gtk_button_set_image (GTK_BUTTON (priv->forward),
1010 gtk_image_new_from_stock (GTK_STOCK_GO_FORWARD, GTK_ICON_SIZE_BUTTON));
1011 priv->back = gtk_button_new_with_mnemonic (_("Go _Back"));
1012 gtk_button_set_image (GTK_BUTTON (priv->back),
1013 gtk_image_new_from_stock (GTK_STOCK_GO_BACK, GTK_ICON_SIZE_BUTTON));
1014 priv->cancel = gtk_button_new_from_stock (GTK_STOCK_CANCEL);
1015 priv->last = gtk_button_new_with_mnemonic (_("_Finish"));
1016 gtk_button_set_image (GTK_BUTTON (priv->last),
1017 gtk_image_new_from_stock (GTK_STOCK_GOTO_LAST, GTK_ICON_SIZE_BUTTON));
1018 gtk_widget_set_can_default (priv->close, TRUE);
1019 gtk_widget_set_can_default (priv->apply, TRUE);
1020 gtk_widget_set_can_default (priv->forward, TRUE);
1022 priv->button_size_group = gtk_size_group_new (GTK_SIZE_GROUP_HORIZONTAL);
1023 gtk_size_group_add_widget (priv->button_size_group, priv->close);
1024 gtk_size_group_add_widget (priv->button_size_group, priv->apply);
1025 gtk_size_group_add_widget (priv->button_size_group, priv->forward);
1026 gtk_size_group_add_widget (priv->button_size_group, priv->back);
1027 gtk_size_group_add_widget (priv->button_size_group, priv->cancel);
1028 gtk_size_group_add_widget (priv->button_size_group, priv->last);
1030 gtk_widget_set_no_show_all (priv->close, TRUE);
1031 gtk_widget_set_no_show_all (priv->apply, TRUE);
1032 gtk_widget_set_no_show_all (priv->forward, TRUE);
1033 gtk_widget_set_no_show_all (priv->back, TRUE);
1034 gtk_widget_set_no_show_all (priv->cancel, TRUE);
1035 gtk_widget_set_no_show_all (priv->last, TRUE);
1037 if (!alternative_button_order (assistant))
1039 gtk_box_pack_end (GTK_BOX (priv->action_area), priv->apply, FALSE, FALSE, 0);
1040 gtk_box_pack_end (GTK_BOX (priv->action_area), priv->forward, FALSE, FALSE, 0);
1041 gtk_box_pack_end (GTK_BOX (priv->action_area), priv->back, FALSE, FALSE, 0);
1042 gtk_box_pack_end (GTK_BOX (priv->action_area), priv->last, FALSE, FALSE, 0);
1043 gtk_box_pack_end (GTK_BOX (priv->action_area), priv->cancel, FALSE, FALSE, 0);
1044 gtk_box_pack_end (GTK_BOX (priv->action_area), priv->close, FALSE, FALSE, 0);
1048 gtk_box_pack_end (GTK_BOX (priv->action_area), priv->close, FALSE, FALSE, 0);
1049 gtk_box_pack_end (GTK_BOX (priv->action_area), priv->cancel, FALSE, FALSE, 0);
1050 gtk_box_pack_end (GTK_BOX (priv->action_area), priv->apply, FALSE, FALSE, 0);
1051 gtk_box_pack_end (GTK_BOX (priv->action_area), priv->forward, FALSE, FALSE, 0);
1052 gtk_box_pack_end (GTK_BOX (priv->action_area), priv->back, FALSE, FALSE, 0);
1053 gtk_box_pack_end (GTK_BOX (priv->action_area), priv->last, FALSE, FALSE, 0);
1056 gtk_widget_show (priv->forward);
1057 gtk_widget_show (priv->back);
1058 gtk_widget_show (priv->cancel);
1059 gtk_widget_show (priv->action_area);
1061 gtk_widget_pop_composite_child ();
1063 priv->title_size_group = gtk_size_group_new (GTK_SIZE_GROUP_HORIZONTAL);
1066 priv->current_page = NULL;
1067 priv->visited_pages = NULL;
1069 priv->forward_function = default_forward_function;
1070 priv->forward_function_data = assistant;
1071 priv->forward_data_destroy = NULL;
1073 g_signal_connect (G_OBJECT (priv->close), "clicked",
1074 G_CALLBACK (on_assistant_close), assistant);
1075 g_signal_connect (G_OBJECT (priv->apply), "clicked",
1076 G_CALLBACK (on_assistant_apply), assistant);
1077 g_signal_connect (G_OBJECT (priv->forward), "clicked",
1078 G_CALLBACK (on_assistant_forward), assistant);
1079 g_signal_connect (G_OBJECT (priv->back), "clicked",
1080 G_CALLBACK (on_assistant_back), assistant);
1081 g_signal_connect (G_OBJECT (priv->cancel), "clicked",
1082 G_CALLBACK (on_assistant_cancel), assistant);
1083 g_signal_connect (G_OBJECT (priv->last), "clicked",
1084 G_CALLBACK (on_assistant_last), assistant);
1088 gtk_assistant_set_child_property (GtkContainer *container,
1091 const GValue *value,
1094 switch (property_id)
1096 case CHILD_PROP_PAGE_TYPE:
1097 gtk_assistant_set_page_type (GTK_ASSISTANT (container), child,
1098 g_value_get_enum (value));
1100 case CHILD_PROP_PAGE_TITLE:
1101 gtk_assistant_set_page_title (GTK_ASSISTANT (container), child,
1102 g_value_get_string (value));
1104 case CHILD_PROP_PAGE_HEADER_IMAGE:
1105 gtk_assistant_do_set_page_header_image (GTK_ASSISTANT (container), child,
1106 g_value_get_object (value));
1108 case CHILD_PROP_PAGE_SIDEBAR_IMAGE:
1109 gtk_assistant_do_set_page_side_image (GTK_ASSISTANT (container), child,
1110 g_value_get_object (value));
1112 case CHILD_PROP_PAGE_COMPLETE:
1113 gtk_assistant_set_page_complete (GTK_ASSISTANT (container), child,
1114 g_value_get_boolean (value));
1117 GTK_CONTAINER_WARN_INVALID_CHILD_PROPERTY_ID (container, property_id, pspec);
1123 gtk_assistant_get_child_property (GtkContainer *container,
1129 GtkAssistant *assistant = GTK_ASSISTANT (container);
1131 switch (property_id)
1133 case CHILD_PROP_PAGE_TYPE:
1134 g_value_set_enum (value,
1135 gtk_assistant_get_page_type (assistant, child));
1137 case CHILD_PROP_PAGE_TITLE:
1138 g_value_set_string (value,
1139 gtk_assistant_get_page_title (assistant, child));
1141 case CHILD_PROP_PAGE_HEADER_IMAGE:
1142 g_value_set_object (value,
1143 ((GtkAssistantPage*) find_page (assistant, child))->header_image);
1145 case CHILD_PROP_PAGE_SIDEBAR_IMAGE:
1146 g_value_set_object (value,
1147 ((GtkAssistantPage*) find_page (assistant, child))->sidebar_image);
1149 case CHILD_PROP_PAGE_COMPLETE:
1150 g_value_set_boolean (value,
1151 gtk_assistant_get_page_complete (assistant, child));
1154 GTK_CONTAINER_WARN_INVALID_CHILD_PROPERTY_ID (container, property_id, pspec);
1160 gtk_assistant_destroy (GtkWidget *widget)
1162 GtkAssistant *assistant = GTK_ASSISTANT (widget);
1163 GtkAssistantPrivate *priv = assistant->priv;
1165 /* We set current to NULL so that the remove code doesn't try
1166 * to do anything funny
1168 priv->current_page = NULL;
1172 GtkNotebook *notebook;
1175 /* Remove all pages from the content notebook. */
1176 notebook = (GtkNotebook *) priv->content;
1177 while ((page = gtk_notebook_get_nth_page (notebook, 0)) != NULL)
1178 gtk_container_remove ((GtkContainer *) notebook, page);
1180 /* Our GtkAssistantPage list should be empty now. */
1181 g_warn_if_fail (priv->pages == NULL);
1183 priv->content = NULL;
1187 priv->sidebar = NULL;
1189 if (priv->action_area)
1190 priv->action_area = NULL;
1192 if (priv->button_size_group)
1194 g_object_unref (priv->button_size_group);
1195 priv->button_size_group = NULL;
1198 if (priv->title_size_group)
1200 g_object_unref (priv->title_size_group);
1201 priv->title_size_group = NULL;
1204 if (priv->forward_function)
1206 if (priv->forward_function_data &&
1207 priv->forward_data_destroy)
1208 priv->forward_data_destroy (priv->forward_function_data);
1210 priv->forward_function = NULL;
1211 priv->forward_function_data = NULL;
1212 priv->forward_data_destroy = NULL;
1215 if (priv->visited_pages)
1217 g_slist_free (priv->visited_pages);
1218 priv->visited_pages = NULL;
1221 GTK_WIDGET_CLASS (gtk_assistant_parent_class)->destroy (widget);
1225 find_page (GtkAssistant *assistant,
1228 GtkAssistantPrivate *priv = assistant->priv;
1229 GList *child = priv->pages;
1233 GtkAssistantPage *page_info = child->data;
1234 if (page_info->page == page)
1237 child = child->next;
1244 gtk_assistant_map (GtkWidget *widget)
1246 GtkAssistant *assistant = GTK_ASSISTANT (widget);
1247 GtkAssistantPrivate *priv = assistant->priv;
1249 GtkAssistantPage *page;
1252 /* if there's no default page, pick the first one */
1255 if (!priv->current_page)
1257 page_node = priv->pages;
1259 while (page_node && !gtk_widget_get_visible (((GtkAssistantPage *) page_node->data)->page))
1261 page_node = page_node->next;
1266 page = page_node->data;
1269 if (page && gtk_widget_get_visible (page->page))
1270 set_current_page (assistant, page_num);
1272 update_buttons_state (assistant);
1273 update_actions_size (assistant);
1274 update_title_state (assistant);
1276 GTK_WIDGET_CLASS (gtk_assistant_parent_class)->map (widget);
1280 gtk_assistant_unmap (GtkWidget *widget)
1282 GtkAssistant *assistant = GTK_ASSISTANT (widget);
1283 GtkAssistantPrivate *priv = assistant->priv;
1285 g_slist_free (priv->visited_pages);
1286 priv->visited_pages = NULL;
1287 priv->current_page = NULL;
1289 GTK_WIDGET_CLASS (gtk_assistant_parent_class)->unmap (widget);
1293 gtk_assistant_delete_event (GtkWidget *widget,
1296 GtkAssistant *assistant = GTK_ASSISTANT (widget);
1297 GtkAssistantPrivate *priv = assistant->priv;
1299 /* Do not allow cancelling in the middle of a progress page */
1300 if (priv->current_page &&
1301 (priv->current_page->type != GTK_ASSISTANT_PAGE_PROGRESS ||
1302 priv->current_page->complete))
1303 g_signal_emit (widget, signals [CANCEL], 0, NULL);
1309 gtk_assistant_add (GtkContainer *container,
1312 gtk_assistant_append_page (GTK_ASSISTANT (container), page);
1316 gtk_assistant_remove (GtkContainer *container,
1319 GtkAssistant *assistant = (GtkAssistant*) container;
1321 /* Forward this removal to the content notebook */
1322 if (gtk_widget_get_parent (page) == assistant->priv->content)
1324 container = (GtkContainer *) assistant->priv->content;
1325 gtk_container_remove (container, page);
1330 * gtk_assistant_new:
1332 * Creates a new #GtkAssistant.
1334 * Return value: a newly created #GtkAssistant
1339 gtk_assistant_new (void)
1341 GtkWidget *assistant;
1343 assistant = g_object_new (GTK_TYPE_ASSISTANT, NULL);
1349 * gtk_assistant_get_current_page:
1350 * @assistant: a #GtkAssistant
1352 * Returns the page number of the current page.
1354 * Return value: The index (starting from 0) of the current
1355 * page in the @assistant, or -1 if the @assistant has no pages,
1356 * or no current page.
1361 gtk_assistant_get_current_page (GtkAssistant *assistant)
1363 GtkAssistantPrivate *priv;
1365 g_return_val_if_fail (GTK_IS_ASSISTANT (assistant), -1);
1367 priv = assistant->priv;
1369 if (!priv->pages || !priv->current_page)
1372 return g_list_index (priv->pages, priv->current_page);
1376 * gtk_assistant_set_current_page:
1377 * @assistant: a #GtkAssistant
1378 * @page_num: index of the page to switch to, starting from 0.
1379 * If negative, the last page will be used. If greater
1380 * than the number of pages in the @assistant, nothing
1383 * Switches the page to @page_num.
1385 * Note that this will only be necessary in custom buttons,
1386 * as the @assistant flow can be set with
1387 * gtk_assistant_set_forward_page_func().
1392 gtk_assistant_set_current_page (GtkAssistant *assistant,
1395 GtkAssistantPrivate *priv;
1396 GtkAssistantPage *page;
1398 g_return_if_fail (GTK_IS_ASSISTANT (assistant));
1400 priv = assistant->priv;
1403 page = (GtkAssistantPage *) g_list_nth_data (priv->pages, page_num);
1406 page = (GtkAssistantPage *) g_list_last (priv->pages)->data;
1407 page_num = g_list_length (priv->pages);
1410 g_return_if_fail (page != NULL);
1412 if (priv->current_page == page)
1415 /* only add the page to the visited list if the assistant is mapped,
1416 * if not, just use it as an initial page setting, for the cases where
1417 * the initial page is != to 0
1419 if (gtk_widget_get_mapped (GTK_WIDGET (assistant)))
1420 priv->visited_pages = g_slist_prepend (priv->visited_pages,
1421 priv->current_page);
1423 set_current_page (assistant, page_num);
1427 * gtk_assistant_next_page:
1428 * @assistant: a #GtkAssistant
1430 * Navigate to the next page.
1432 * It is a programming error to call this function when
1433 * there is no next page.
1435 * This function is for use when creating pages of the
1436 * #GTK_ASSISTANT_PAGE_CUSTOM type.
1441 gtk_assistant_next_page (GtkAssistant *assistant)
1443 g_return_if_fail (GTK_IS_ASSISTANT (assistant));
1445 if (!compute_next_step (assistant))
1446 g_critical ("Page flow is broken.\n"
1447 "You may want to end it with a page of type\n"
1448 "GTK_ASSISTANT_PAGE_CONFIRM or GTK_ASSISTANT_PAGE_SUMMARY");
1452 * gtk_assistant_previous_page:
1453 * @assistant: a #GtkAssistant
1455 * Navigate to the previous visited page.
1457 * It is a programming error to call this function when
1458 * no previous page is available.
1460 * This function is for use when creating pages of the
1461 * #GTK_ASSISTANT_PAGE_CUSTOM type.
1466 gtk_assistant_previous_page (GtkAssistant *assistant)
1468 GtkAssistantPrivate *priv;
1469 GtkAssistantPage *page_info;
1472 g_return_if_fail (GTK_IS_ASSISTANT (assistant));
1474 priv = assistant->priv;
1476 /* skip the progress pages when going back */
1479 page_node = priv->visited_pages;
1481 g_return_if_fail (page_node != NULL);
1483 priv->visited_pages = priv->visited_pages->next;
1484 page_info = (GtkAssistantPage *) page_node->data;
1485 g_slist_free_1 (page_node);
1487 while (page_info->type == GTK_ASSISTANT_PAGE_PROGRESS ||
1488 !gtk_widget_get_visible (page_info->page));
1490 set_current_page (assistant, g_list_index (priv->pages, page_info));
1494 * gtk_assistant_get_n_pages:
1495 * @assistant: a #GtkAssistant
1497 * Returns the number of pages in the @assistant
1499 * Return value: the number of pages in the @assistant
1504 gtk_assistant_get_n_pages (GtkAssistant *assistant)
1506 GtkAssistantPrivate *priv;
1508 g_return_val_if_fail (GTK_IS_ASSISTANT (assistant), 0);
1510 priv = assistant->priv;
1512 return g_list_length (priv->pages);
1516 * gtk_assistant_get_nth_page:
1517 * @assistant: a #GtkAssistant
1518 * @page_num: the index of a page in the @assistant,
1519 * or -1 to get the last page
1521 * Returns the child widget contained in page number @page_num.
1523 * Return value: (transfer none): the child widget, or %NULL
1524 * if @page_num is out of bounds
1529 gtk_assistant_get_nth_page (GtkAssistant *assistant,
1532 GtkAssistantPrivate *priv;
1533 GtkAssistantPage *page;
1536 g_return_val_if_fail (GTK_IS_ASSISTANT (assistant), NULL);
1537 g_return_val_if_fail (page_num >= -1, NULL);
1539 priv = assistant->priv;
1542 elem = g_list_last (priv->pages);
1544 elem = g_list_nth (priv->pages, page_num);
1549 page = (GtkAssistantPage *) elem->data;
1555 * gtk_assistant_prepend_page:
1556 * @assistant: a #GtkAssistant
1557 * @page: a #GtkWidget
1559 * Prepends a page to the @assistant.
1561 * Return value: the index (starting at 0) of the inserted page
1566 gtk_assistant_prepend_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, 0);
1576 * gtk_assistant_append_page:
1577 * @assistant: a #GtkAssistant
1578 * @page: a #GtkWidget
1580 * Appends a page to the @assistant.
1582 * Return value: the index (starting at 0) of the inserted page
1587 gtk_assistant_append_page (GtkAssistant *assistant,
1590 g_return_val_if_fail (GTK_IS_ASSISTANT (assistant), 0);
1591 g_return_val_if_fail (GTK_IS_WIDGET (page), 0);
1593 return gtk_assistant_insert_page (assistant, page, -1);
1597 * gtk_assistant_insert_page:
1598 * @assistant: a #GtkAssistant
1599 * @page: a #GtkWidget
1600 * @position: the index (starting at 0) at which to insert the page,
1601 * or -1 to append the page to the @assistant
1603 * Inserts a page in the @assistant at a given position.
1605 * Return value: the index (starting from 0) of the inserted page
1610 gtk_assistant_insert_page (GtkAssistant *assistant,
1614 GtkAssistantPrivate *priv;
1615 GtkAssistantPage *page_info;
1617 GtkStyleContext *context;
1619 g_return_val_if_fail (GTK_IS_ASSISTANT (assistant), 0);
1620 g_return_val_if_fail (GTK_IS_WIDGET (page), 0);
1621 g_return_val_if_fail (gtk_widget_get_parent (page) == NULL, 0);
1622 g_return_val_if_fail (!gtk_widget_is_toplevel (page), 0);
1624 priv = assistant->priv;
1626 page_info = g_slice_new0 (GtkAssistantPage);
1627 page_info->page = page;
1628 page_info->regular_title = gtk_label_new (NULL);
1629 gtk_widget_set_no_show_all (page_info->regular_title, TRUE);
1630 page_info->current_title = gtk_label_new (NULL);
1631 gtk_widget_set_no_show_all (page_info->current_title, TRUE);
1633 /* Note: we need to use misc alignment here as long as GtkLabel
1634 * pays attention to it. GtkWiget::halign is ineffective, since
1635 * all the labels are getting the same size anyway, due to the
1638 gtk_misc_set_alignment (GTK_MISC (page_info->regular_title), 0, 0.5);
1639 gtk_widget_show (page_info->regular_title);
1641 gtk_misc_set_alignment (GTK_MISC (page_info->current_title), 0, 0.5);
1642 gtk_widget_hide (page_info->current_title);
1644 context = gtk_widget_get_style_context (page_info->current_title);
1645 gtk_style_context_add_class (context, GTK_STYLE_CLASS_HIGHLIGHT);
1647 gtk_size_group_add_widget (priv->title_size_group, page_info->regular_title);
1648 gtk_size_group_add_widget (priv->title_size_group, page_info->current_title);
1650 g_signal_connect (G_OBJECT (page), "notify::visible",
1651 G_CALLBACK (on_page_notify_visibility), assistant);
1653 n_pages = g_list_length (priv->pages);
1655 if (position < 0 || position > n_pages)
1658 priv->pages = g_list_insert (priv->pages, page_info, position);
1660 gtk_box_pack_start (GTK_BOX (priv->sidebar), page_info->regular_title, FALSE, FALSE, 0);
1661 gtk_box_pack_start (GTK_BOX (priv->sidebar), page_info->current_title, FALSE, FALSE, 0);
1662 gtk_box_reorder_child (GTK_BOX (priv->sidebar), page_info->regular_title, 2 * position);
1663 gtk_box_reorder_child (GTK_BOX (priv->sidebar), page_info->current_title, 2 * position + 1);
1665 gtk_notebook_insert_page (GTK_NOTEBOOK (priv->content), page, NULL, position);
1667 if (gtk_widget_get_mapped (GTK_WIDGET (assistant)))
1669 update_buttons_state (assistant);
1670 update_actions_size (assistant);
1677 * gtk_assistant_remove_page:
1678 * @assistant: a #GtkAssistant
1679 * @page_num: the index of a page in the @assistant,
1680 * or -1 to remove the last page
1682 * Removes the @page_num's page from @assistant.
1687 gtk_assistant_remove_page (GtkAssistant *assistant,
1692 g_return_if_fail (GTK_IS_ASSISTANT (assistant));
1694 page = gtk_assistant_get_nth_page (assistant, page_num);
1697 gtk_container_remove (GTK_CONTAINER (assistant), page);
1701 * gtk_assistant_set_forward_page_func:
1702 * @assistant: a #GtkAssistant
1703 * @page_func: (allow-none): the #GtkAssistantPageFunc, or %NULL
1704 * to use the default one
1705 * @data: user data for @page_func
1706 * @destroy: destroy notifier for @data
1708 * Sets the page forwarding function to be @page_func.
1710 * This function will be used to determine what will be
1711 * the next page when the user presses the forward button.
1712 * Setting @page_func to %NULL will make the assistant to
1713 * use the default forward function, which just goes to the
1714 * next visible page.
1719 gtk_assistant_set_forward_page_func (GtkAssistant *assistant,
1720 GtkAssistantPageFunc page_func,
1722 GDestroyNotify destroy)
1724 GtkAssistantPrivate *priv;
1726 g_return_if_fail (GTK_IS_ASSISTANT (assistant));
1728 priv = assistant->priv;
1730 if (priv->forward_data_destroy &&
1731 priv->forward_function_data)
1732 (*priv->forward_data_destroy) (priv->forward_function_data);
1736 priv->forward_function = page_func;
1737 priv->forward_function_data = data;
1738 priv->forward_data_destroy = destroy;
1742 priv->forward_function = default_forward_function;
1743 priv->forward_function_data = assistant;
1744 priv->forward_data_destroy = NULL;
1747 /* Page flow has possibly changed, so the
1748 * buttons state might need to change too
1750 if (gtk_widget_get_mapped (GTK_WIDGET (assistant)))
1751 update_buttons_state (assistant);
1755 * gtk_assistant_add_action_widget:
1756 * @assistant: a #GtkAssistant
1757 * @child: a #GtkWidget
1759 * Adds a widget to the action area of a #GtkAssistant.
1764 gtk_assistant_add_action_widget (GtkAssistant *assistant,
1767 GtkAssistantPrivate *priv;
1769 g_return_if_fail (GTK_IS_ASSISTANT (assistant));
1770 g_return_if_fail (GTK_IS_WIDGET (child));
1772 priv = assistant->priv;
1774 if (GTK_IS_BUTTON (child))
1776 gtk_size_group_add_widget (priv->button_size_group, child);
1777 priv->extra_buttons += 1;
1778 if (gtk_widget_get_mapped (GTK_WIDGET (assistant)))
1779 update_actions_size (assistant);
1782 gtk_box_pack_end (GTK_BOX (priv->action_area), child, FALSE, FALSE, 0);
1786 * gtk_assistant_remove_action_widget:
1787 * @assistant: a #GtkAssistant
1788 * @child: a #GtkWidget
1790 * Removes a widget from the action area of a #GtkAssistant.
1795 gtk_assistant_remove_action_widget (GtkAssistant *assistant,
1798 GtkAssistantPrivate *priv;
1800 g_return_if_fail (GTK_IS_ASSISTANT (assistant));
1801 g_return_if_fail (GTK_IS_WIDGET (child));
1803 priv = assistant->priv;
1805 if (GTK_IS_BUTTON (child))
1807 gtk_size_group_remove_widget (priv->button_size_group, child);
1808 priv->extra_buttons -= 1;
1809 if (gtk_widget_get_mapped (GTK_WIDGET (assistant)))
1810 update_actions_size (assistant);
1813 gtk_container_remove (GTK_CONTAINER (priv->action_area), child);
1817 * gtk_assistant_set_page_title:
1818 * @assistant: a #GtkAssistant
1819 * @page: a page of @assistant
1820 * @title: the new title for @page
1822 * Sets a title for @page.
1824 * The title is displayed in the header area of the assistant
1825 * when @page is the current page.
1830 gtk_assistant_set_page_title (GtkAssistant *assistant,
1834 GtkAssistantPage *page_info;
1837 g_return_if_fail (GTK_IS_ASSISTANT (assistant));
1838 g_return_if_fail (GTK_IS_WIDGET (page));
1840 child = find_page (assistant, page);
1842 g_return_if_fail (child != NULL);
1844 page_info = (GtkAssistantPage*) child->data;
1846 g_free (page_info->title);
1847 page_info->title = g_strdup (title);
1849 gtk_label_set_text ((GtkLabel*) page_info->regular_title, title);
1850 gtk_label_set_text ((GtkLabel*) page_info->current_title, title);
1852 gtk_widget_queue_resize (GTK_WIDGET (assistant));
1853 gtk_container_child_notify (GTK_CONTAINER (assistant), page, "title");
1857 * gtk_assistant_get_page_title:
1858 * @assistant: a #GtkAssistant
1859 * @page: a page of @assistant
1861 * Gets the title for @page.
1863 * Return value: the title for @page
1868 gtk_assistant_get_page_title (GtkAssistant *assistant,
1871 GtkAssistantPage *page_info;
1874 g_return_val_if_fail (GTK_IS_ASSISTANT (assistant), NULL);
1875 g_return_val_if_fail (GTK_IS_WIDGET (page), NULL);
1877 child = find_page (assistant, page);
1879 g_return_val_if_fail (child != NULL, NULL);
1881 page_info = (GtkAssistantPage*) child->data;
1883 return page_info->title;
1887 * gtk_assistant_set_page_type:
1888 * @assistant: a #GtkAssistant
1889 * @page: a page of @assistant
1890 * @type: the new type for @page
1892 * Sets the page type for @page.
1894 * The page type determines the page behavior in the @assistant.
1899 gtk_assistant_set_page_type (GtkAssistant *assistant,
1901 GtkAssistantPageType type)
1903 GtkAssistantPage *page_info;
1906 g_return_if_fail (GTK_IS_ASSISTANT (assistant));
1907 g_return_if_fail (GTK_IS_WIDGET (page));
1909 child = find_page (assistant, page);
1911 g_return_if_fail (child != NULL);
1913 page_info = (GtkAssistantPage*) child->data;
1915 if (type != page_info->type)
1917 page_info->type = type;
1919 /* backwards compatibility to the era before fixing bug 604289 */
1920 if (type == GTK_ASSISTANT_PAGE_SUMMARY && !page_info->complete_set)
1922 gtk_assistant_set_page_complete (assistant, page, TRUE);
1923 page_info->complete_set = FALSE;
1926 /* Always set buttons state, a change in a future page
1927 * might change current page buttons
1929 update_buttons_state (assistant);
1931 gtk_container_child_notify (GTK_CONTAINER (assistant), page, "page-type");
1936 * gtk_assistant_get_page_type:
1937 * @assistant: a #GtkAssistant
1938 * @page: a page of @assistant
1940 * Gets the page type of @page.
1942 * Return value: the page type of @page
1946 GtkAssistantPageType
1947 gtk_assistant_get_page_type (GtkAssistant *assistant,
1950 GtkAssistantPage *page_info;
1953 g_return_val_if_fail (GTK_IS_ASSISTANT (assistant), GTK_ASSISTANT_PAGE_CONTENT);
1954 g_return_val_if_fail (GTK_IS_WIDGET (page), GTK_ASSISTANT_PAGE_CONTENT);
1956 child = find_page (assistant, page);
1958 g_return_val_if_fail (child != NULL, GTK_ASSISTANT_PAGE_CONTENT);
1960 page_info = (GtkAssistantPage*) child->data;
1962 return page_info->type;
1966 * gtk_assistant_set_page_header_image:
1967 * @assistant: a #GtkAssistant
1968 * @page: a page of @assistant
1969 * @pixbuf: (allow-none): the new header image @page
1971 * Sets a header image for @page.
1975 * Deprecated: 3.2: Since GTK+ 3.2, a header is no longer shown;
1976 * add your header decoration to the page content instead.
1979 gtk_assistant_set_page_header_image (GtkAssistant *assistant,
1983 g_return_if_fail (GTK_IS_ASSISTANT (assistant));
1984 g_return_if_fail (GTK_IS_WIDGET (page));
1985 g_return_if_fail (pixbuf == NULL || GDK_IS_PIXBUF (pixbuf));
1987 gtk_assistant_do_set_page_header_image (assistant, page, pixbuf);
1991 gtk_assistant_do_set_page_header_image (GtkAssistant *assistant,
1995 GtkAssistantPage *page_info;
1998 child = find_page (assistant, page);
2000 g_return_if_fail (child != NULL);
2002 page_info = (GtkAssistantPage*) child->data;
2004 if (pixbuf != page_info->header_image)
2006 if (page_info->header_image)
2008 g_object_unref (page_info->header_image);
2009 page_info->header_image = NULL;
2013 page_info->header_image = g_object_ref (pixbuf);
2015 gtk_container_child_notify (GTK_CONTAINER (assistant), page, "header-image");
2020 * gtk_assistant_get_page_header_image:
2021 * @assistant: a #GtkAssistant
2022 * @page: a page of @assistant
2024 * Gets the header image for @page.
2026 * Return value: (transfer none): the header image for @page,
2027 * or %NULL if there's no header image for the page
2031 * Deprecated: 3.2: Since GTK+ 3.2, a header is no longer shown;
2032 * add your header decoration to the page content instead.
2035 gtk_assistant_get_page_header_image (GtkAssistant *assistant,
2038 GtkAssistantPage *page_info;
2041 g_return_val_if_fail (GTK_IS_ASSISTANT (assistant), NULL);
2042 g_return_val_if_fail (GTK_IS_WIDGET (page), NULL);
2044 child = find_page (assistant, page);
2046 g_return_val_if_fail (child != NULL, NULL);
2048 page_info = (GtkAssistantPage*) child->data;
2050 return page_info->header_image;
2054 * gtk_assistant_set_page_side_image:
2055 * @assistant: a #GtkAssistant
2056 * @page: a page of @assistant
2057 * @pixbuf: (allow-none): the new side image @page
2059 * Sets a side image for @page.
2061 * This image used to be displayed in the side area of the assistant
2062 * when @page is the current page.
2066 * Deprecated: 3.2: Since GTK+ 3.2, sidebar images are not
2070 gtk_assistant_set_page_side_image (GtkAssistant *assistant,
2074 g_return_if_fail (GTK_IS_ASSISTANT (assistant));
2075 g_return_if_fail (GTK_IS_WIDGET (page));
2076 g_return_if_fail (pixbuf == NULL || GDK_IS_PIXBUF (pixbuf));
2078 gtk_assistant_do_set_page_side_image (assistant, page, pixbuf);
2082 gtk_assistant_do_set_page_side_image (GtkAssistant *assistant,
2086 GtkAssistantPage *page_info;
2089 child = find_page (assistant, page);
2091 g_return_if_fail (child != NULL);
2093 page_info = (GtkAssistantPage*) child->data;
2095 if (pixbuf != page_info->sidebar_image)
2097 if (page_info->sidebar_image)
2099 g_object_unref (page_info->sidebar_image);
2100 page_info->sidebar_image = NULL;
2104 page_info->sidebar_image = g_object_ref (pixbuf);
2106 gtk_container_child_notify (GTK_CONTAINER (assistant), page, "sidebar-image");
2111 * gtk_assistant_get_page_side_image:
2112 * @assistant: a #GtkAssistant
2113 * @page: a page of @assistant
2115 * Gets the side image for @page.
2117 * Return value: (transfer none): the side image for @page,
2118 * or %NULL if there's no side image for the page
2122 * Deprecated: 3.2: Since GTK+ 3.2, sidebar images are not
2126 gtk_assistant_get_page_side_image (GtkAssistant *assistant,
2129 GtkAssistantPage *page_info;
2132 g_return_val_if_fail (GTK_IS_ASSISTANT (assistant), NULL);
2133 g_return_val_if_fail (GTK_IS_WIDGET (page), NULL);
2135 child = find_page (assistant, page);
2137 g_return_val_if_fail (child != NULL, NULL);
2139 page_info = (GtkAssistantPage*) child->data;
2141 return page_info->sidebar_image;
2145 * gtk_assistant_set_page_complete:
2146 * @assistant: a #GtkAssistant
2147 * @page: a page of @assistant
2148 * @complete: the completeness status of the page
2150 * Sets whether @page contents are complete.
2152 * This will make @assistant update the buttons state
2153 * to be able to continue the task.
2158 gtk_assistant_set_page_complete (GtkAssistant *assistant,
2162 GtkAssistantPage *page_info;
2165 g_return_if_fail (GTK_IS_ASSISTANT (assistant));
2166 g_return_if_fail (GTK_IS_WIDGET (page));
2168 child = find_page (assistant, page);
2170 g_return_if_fail (child != NULL);
2172 page_info = (GtkAssistantPage*) child->data;
2174 if (complete != page_info->complete)
2176 page_info->complete = complete;
2177 page_info->complete_set = TRUE;
2179 /* Always set buttons state, a change in a future page
2180 * might change current page buttons
2182 update_buttons_state (assistant);
2184 gtk_container_child_notify (GTK_CONTAINER (assistant), page, "complete");
2189 * gtk_assistant_get_page_complete:
2190 * @assistant: a #GtkAssistant
2191 * @page: a page of @assistant
2193 * Gets whether @page is complete.
2195 * Return value: %TRUE if @page is complete.
2200 gtk_assistant_get_page_complete (GtkAssistant *assistant,
2203 GtkAssistantPage *page_info;
2206 g_return_val_if_fail (GTK_IS_ASSISTANT (assistant), FALSE);
2207 g_return_val_if_fail (GTK_IS_WIDGET (page), FALSE);
2209 child = find_page (assistant, page);
2211 g_return_val_if_fail (child != NULL, FALSE);
2213 page_info = (GtkAssistantPage*) child->data;
2215 return page_info->complete;
2219 * gtk_assistant_update_buttons_state:
2220 * @assistant: a #GtkAssistant
2222 * Forces @assistant to recompute the buttons state.
2224 * GTK+ automatically takes care of this in most situations,
2225 * e.g. when the user goes to a different page, or when the
2226 * visibility or completeness of a page changes.
2228 * One situation where it can be necessary to call this
2229 * function is when changing a value on the current page
2230 * affects the future page flow of the assistant.
2235 gtk_assistant_update_buttons_state (GtkAssistant *assistant)
2237 g_return_if_fail (GTK_IS_ASSISTANT (assistant));
2239 update_buttons_state (assistant);
2243 * gtk_assistant_commit:
2244 * @assistant: a #GtkAssistant
2246 * Erases the visited page history so the back button is not
2247 * shown on the current page, and removes the cancel button
2248 * from subsequent pages.
2250 * Use this when the information provided up to the current
2251 * page is hereafter deemed permanent and cannot be modified
2252 * or undone. For example, showing a progress page to track
2253 * a long-running, unreversible operation after the user has
2254 * clicked apply on a confirmation page.
2259 gtk_assistant_commit (GtkAssistant *assistant)
2261 g_return_if_fail (GTK_IS_ASSISTANT (assistant));
2263 g_slist_free (assistant->priv->visited_pages);
2264 assistant->priv->visited_pages = NULL;
2266 assistant->priv->committed = TRUE;
2268 update_buttons_state (assistant);
2271 /* accessible implementation */
2273 /* dummy typedefs */
2274 typedef GtkWindowAccessible GtkAssistantAccessible;
2275 typedef GtkWindowAccessibleClass GtkAssistantAccessibleClass;
2277 G_DEFINE_TYPE (GtkAssistantAccessible, _gtk_assistant_accessible, GTK_TYPE_WINDOW_ACCESSIBLE);
2280 gtk_assistant_accessible_get_n_children (AtkObject *accessible)
2284 widget = gtk_accessible_get_widget (GTK_ACCESSIBLE (accessible));
2288 return g_list_length (GTK_ASSISTANT (widget)->priv->pages) + 1;
2292 gtk_assistant_accessible_ref_child (AtkObject *accessible,
2295 GtkAssistant *assistant;
2296 GtkAssistantPrivate *priv;
2297 GtkWidget *widget, *child;
2302 widget = gtk_accessible_get_widget (GTK_ACCESSIBLE (accessible));
2306 assistant = GTK_ASSISTANT (widget);
2307 priv = assistant->priv;
2308 n_pages = g_list_length (priv->pages);
2312 else if (index < n_pages)
2314 GtkAssistantPage *page = g_list_nth_data (priv->pages, index);
2317 title = gtk_assistant_get_page_title (assistant, child);
2319 else if (index == n_pages)
2321 child = priv->action_area;
2327 obj = gtk_widget_get_accessible (child);
2330 atk_object_set_name (obj, title);
2332 return g_object_ref (obj);
2336 _gtk_assistant_accessible_class_init (GtkAssistantAccessibleClass *klass)
2338 AtkObjectClass *atk_class = ATK_OBJECT_CLASS (klass);
2340 atk_class->get_n_children = gtk_assistant_accessible_get_n_children;
2341 atk_class->ref_child = gtk_assistant_accessible_ref_child;
2345 _gtk_assistant_accessible_init (GtkAssistantAccessible *self)
2349 /* buildable implementation */
2351 static GtkBuildableIface *parent_buildable_iface;
2354 gtk_assistant_buildable_interface_init (GtkBuildableIface *iface)
2356 parent_buildable_iface = g_type_interface_peek_parent (iface);
2357 iface->get_internal_child = gtk_assistant_buildable_get_internal_child;
2358 iface->custom_tag_start = gtk_assistant_buildable_custom_tag_start;
2359 iface->custom_finished = gtk_assistant_buildable_custom_finished;
2363 gtk_assistant_buildable_get_internal_child (GtkBuildable *buildable,
2364 GtkBuilder *builder,
2365 const gchar *childname)
2367 if (strcmp (childname, "action_area") == 0)
2368 return G_OBJECT (GTK_ASSISTANT (buildable)->priv->action_area);
2370 return parent_buildable_iface->get_internal_child (buildable,
2376 gtk_assistant_buildable_custom_tag_start (GtkBuildable *buildable,
2377 GtkBuilder *builder,
2379 const gchar *tagname,
2380 GMarkupParser *parser,
2383 return parent_buildable_iface->custom_tag_start (buildable, builder, child,
2384 tagname, parser, data);
2388 gtk_assistant_buildable_custom_finished (GtkBuildable *buildable,
2389 GtkBuilder *builder,
2391 const gchar *tagname,
2394 parent_buildable_iface->custom_finished (buildable, builder, child,
2395 tagname, user_data);