GtkAssistant stuff

ChangeLog

@@ -1,3 +1,14 @@
+2006-01-29  Matthias Clasen  <mclasen@redhat.com>
+
+	More GtkAssistant work, by Carlos Garnacho.
+	
+	* tests/testassistant.c: Additions.
+
+	* gtk/gtkassistant.c: Handle page visibility, other 
+	small fixes.
+
+	* docs/tools/widgets.c: Add GtkAssistant.
+
 2006-01-28  Behdad Esfahbod  <behdad@gnome.org>
 
 	* configure.in: If major.minor of required and available glib versions

ChangeLog.pre-2-10

@@ -1,3 +1,14 @@
+2006-01-29  Matthias Clasen  <mclasen@redhat.com>
+
+	More GtkAssistant work, by Carlos Garnacho.
+	
+	* tests/testassistant.c: Additions.
+
+	* gtk/gtkassistant.c: Handle page visibility, other 
+	small fixes.
+
+	* docs/tools/widgets.c: Add GtkAssistant.
+
 2006-01-28  Behdad Esfahbod  <behdad@gnome.org>
 
 	* configure.in: If major.minor of required and available glib versions

docs/reference/ChangeLog

@@ -1,3 +1,13 @@
+2006-01-29  Matthias Clasen  <mclasen@redhat.com>
+
+	* gtk/visual_index.xml: Add GtkAssistant
+
+	* gtk/images/assistant.png: New image.
+
+	* gtk/tmpl/gtkassistant.sgml: More docs, by Carlos Garnacho.
+
+	* gtk/Makefile.am: Add new files.
+
 2006-01-28  Matthias Clasen  <mclasen@redhat.com>
 
 	* gtk/gtk-sections.txt: Add gtk_link_button_set_uri_hook

docs/reference/gtk/Makefile.am

@@ -106,6 +106,7 @@ content_files =					\
 	migrating-GtkIconView.sgml		\
 	migrating-GtkAboutDialog.sgml		\
 	migrating-GtkColorButton.sgml		\
+	migrating-GtkAssistant.sgml		\
 	objects_grouped.sgml			\
 	question_index.sgml			\
 	resources.sgml				\
@@ -126,6 +127,7 @@ expand_content_files = 				\
 	migrating-GtkIconView.sgml		\
 	migrating-GtkAboutDialog.sgml		\
 	migrating-GtkColorButton.sgml		\
+	migrating-GtkAssistant.sgml		\
 	tree_widget.sgml			\
 	text_widget.sgml			\
 	question_index.sgml
@@ -243,6 +245,7 @@ HTML_IMAGES = \
 	$(top_srcdir)/gtk/stock-icons/24/gtk-leave-fullscreen.png	\
 	$(top_srcdir)/gtk/stock-icons/24/gtk-info.png			\
 	$(srcdir)/images/accel-label.png				\
+	$(srcdir)/images/assistant.png					\
 	$(srcdir)/images/button.png					\
 	$(srcdir)/images/check-button.png				\
 	$(srcdir)/images/color-button.png				\

docs/reference/gtk/tmpl/gtkassistant.sgml

@@ -2,11 +2,13 @@
 GtkAssistant
 
 <!-- ##### SECTION Short_Description ##### -->
-guiding users through multi-step operations
+A widget used to guide users through multi-step operations
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>
-
+A #GtkAssistant is a widget used to represent a generally complex
+operation splitted in several steps, guiding the user through its pages
+and controlling the page flow to collect the necessary data.
 </para>
 
 <!-- ##### SECTION See_Also ##### -->
@@ -165,12 +167,15 @@ guiding users through multi-step operations
 
 <!-- ##### USER_FUNCTION GtkAssistantPageFunc ##### -->
 <para>
-
+A function used by gtk_assistant_set_forward_page_func() to know which
+is the next page given a current one. It's called both for computing the
+next page when the user presses the "forward" button and for handling
+the behavior of the "last" button.
 </para>
 
-@current_page: 
+@current_page: The page number used to calculate the next page.
-@data: 
+@data: user data.
-@Returns: 
+@Returns: The next page number.
 
 
 <!-- ##### FUNCTION gtk_assistant_set_forward_page_func ##### -->
@@ -186,14 +191,20 @@ guiding users through multi-step operations
 
 <!-- ##### ENUM GtkAssistantPageType ##### -->
 <para>
-
+An enum for determining the page role inside the #GtkAssistant. It's used to
+handle buttons sensitivity and visibility.
 </para>
 
-@GTK_ASSISTANT_PAGE_CONTENT: 
+<para>
-@GTK_ASSISTANT_PAGE_INTRO: 
+Note that an assistant needs to end its page flow with a page of type GTK_ASSISTANT_PAGE_CONFIRM
-@GTK_ASSISTANT_PAGE_CONFIRM: 
+or GTK_ASSISTANT_PAGE_SUMMARY to be correct.
-@GTK_ASSISTANT_PAGE_SUMMARY: 
+</para>
-@GTK_ASSISTANT_PAGE_PROGRESS: 
+
+@GTK_ASSISTANT_PAGE_CONTENT: The page has regular contents.
+@GTK_ASSISTANT_PAGE_INTRO: The page contains an introduction to the assistant task.
+@GTK_ASSISTANT_PAGE_CONFIRM: The page lets the user confirm or deny the changes.
+@GTK_ASSISTANT_PAGE_SUMMARY: The page informs the user of the changes done.
+@GTK_ASSISTANT_PAGE_PROGRESS: Used for tasks that take a long time to complete, blocks the assistant until the page is marked as complete.
 
 <!-- ##### FUNCTION gtk_assistant_set_page_type ##### -->
 <para>

docs/reference/gtk/visual_index.xml

@@ -86,6 +86,9 @@
   <link linkend="GtkMessageDialog">
     <inlinegraphic fileref="messagedialog.png" format="PNG"></inlinegraphic>
   </link>
+  <link linkend="GtkAssistant">
+    <inlinegraphic fileref="assistant.png" format="PNG"></inlinegraphic>
+  </link>
   <link linkend="GtkFontSelectionDialog">
     <inlinegraphic fileref="fontsel.png" format="PNG"></inlinegraphic>
   </link>

docs/tools/widgets.c

@@ -839,6 +839,34 @@ create_image (void)
   return new_widget_info ("image", vbox, SMALL);
 }
 
+static WidgetInfo *
+create_assistant (void)
+{
+  GtkWidget *widget;
+  GtkWidget *page1, *page2;
+  WidgetInfo *info;
+
+  widget = gtk_assistant_new ();
+  gtk_window_set_title (GTK_WINDOW (widget), "Assistant");
+
+  page1 = gtk_label_new ("Assistant");
+  gtk_widget_show (page1);
+  gtk_widget_set_size_request (page1, 300, 140);
+  gtk_assistant_prepend_page (GTK_ASSISTANT (widget), page1);
+  gtk_assistant_set_page_title (GTK_ASSISTANT (widget), page1, "Assistant page");
+  gtk_assistant_set_page_complete (GTK_ASSISTANT (widget), page1, TRUE);
+
+  page2 = gtk_label_new (NULL);
+  gtk_widget_show (page2);
+  gtk_assistant_append_page (GTK_ASSISTANT (widget), page2);
+  gtk_assistant_set_page_type (GTK_ASSISTANT (widget), page2, GTK_ASSISTANT_PAGE_CONFIRM);
+
+  info = new_widget_info ("assistant", widget, ASIS);
+  info->include_decorations = TRUE;
+
+  return info;
+}
+
 GList *
 get_all_widgets (void)
 {
@@ -876,6 +904,7 @@ get_all_widgets (void)
   retval = g_list_prepend (retval, create_colorsel ());
   retval = g_list_prepend (retval, create_filesel ());
   retval = g_list_prepend (retval, create_fontsel ());
+  retval = g_list_prepend (retval, create_assistant ());
 
   return retval;
 }

gtk/gtkassistant.c

@@ -537,12 +537,14 @@ _set_current_page (GtkAssistant     *assistant,
 
   if (GTK_WIDGET_VISIBLE (priv->current_page->page) && GTK_WIDGET_MAPPED (assistant))
     {
+      gtk_widget_set_child_visible (priv->current_page->page, TRUE);
       gtk_widget_map (priv->current_page->page);
       gtk_widget_map (priv->current_page->title);
     }
   
   if (old_page && GTK_WIDGET_MAPPED (old_page->page))
     {
+      gtk_widget_set_child_visible (old_page->page, FALSE);
       gtk_widget_unmap (old_page->page);
       gtk_widget_unmap (old_page->title);
     }
@@ -1161,6 +1163,7 @@ gtk_assistant_map (GtkWidget *widget)
       _set_assistant_sidebar_image ((GtkAssistant*) widget);
 
       g_signal_emit (widget, signals [PREPARE], 0, priv->current_page->page);
+      gtk_widget_set_child_visible (priv->current_page->page, TRUE);
       gtk_widget_map (priv->current_page->page);
       gtk_widget_map (priv->current_page->title);
     }
@@ -1214,13 +1217,14 @@ assistant_paint_colored_box (GtkWidget *widget)
 {
   GtkAssistant *assistant = GTK_ASSISTANT (widget);
   GtkAssistantPrivate *priv = assistant->priv;
-  gint header_padding, content_padding;
+  gint border_width, header_padding, content_padding;
   cairo_t *cr;
   gint content_x, content_width;
   gboolean rtl;
 
   cr   = gdk_cairo_create (widget->window);
   rtl  = (gtk_widget_get_direction (widget) == GTK_TEXT_DIR_RTL);
+  border_width = gtk_container_get_border_width (GTK_CONTAINER (widget));
 
   gtk_widget_style_get (widget,
 			"header-padding",  &header_padding,
@@ -1230,14 +1234,15 @@ assistant_paint_colored_box (GtkWidget *widget)
   /* colored box */
   gdk_cairo_set_source_color (cr, &widget->style->bg[GTK_STATE_SELECTED]);
   cairo_rectangle (cr,
-		   0, 0,
+		   border_width,
-		   widget->allocation.width,
+		   border_width,
-		   widget->allocation.height - priv->action_area->allocation.height);
+		   widget->allocation.width - 2 * border_width,
+		   widget->allocation.height - priv->action_area->allocation.height - 2 * border_width);
   cairo_fill (cr);
 
   /* content box */
-  content_x = content_padding;
+  content_x = content_padding + border_width;
-  content_width = widget->allocation.width - 2 * content_padding;
+  content_width = widget->allocation.width - 2 * content_padding - 2 * border_width;
 
   if (GTK_WIDGET_VISIBLE (priv->sidebar_image))
     {
@@ -1250,9 +1255,9 @@ assistant_paint_colored_box (GtkWidget *widget)
 
   cairo_rectangle (cr,
 		   content_x,
-		   priv->header_image->allocation.height + content_padding + 2 * header_padding,
+		   priv->header_image->allocation.height + content_padding + 2 * header_padding + border_width,
 		   content_width,
-		   widget->allocation.height - priv->action_area->allocation.height -
+		   widget->allocation.height - 2 * border_width - priv->action_area->allocation.height -
 		   priv->header_image->allocation.height - 2 * content_padding - 2 * header_padding);
   cairo_fill (cr);
 
@@ -1616,6 +1621,7 @@ gtk_assistant_insert_page (GtkAssistant *assistant,
 
   priv->pages = g_list_insert (priv->pages, page_info, position);
 
+  gtk_widget_set_child_visible (page_info->page, FALSE);
   gtk_widget_set_parent (page_info->page,  GTK_WIDGET (assistant));
   gtk_widget_set_parent (page_info->title, GTK_WIDGET (assistant));
 

tests/testassistant.c

@@ -31,6 +31,59 @@ get_test_page (const gchar *text)
   return gtk_label_new (text);
 }
 
+typedef struct {
+  GtkAssistant *assistant;
+  GtkWidget    *page;
+} PageData;
+
+static void
+complete_cb (GtkWidget *check, 
+	     gpointer   data)
+{
+  PageData *pdata = data;
+  gboolean complete;
+
+  complete = gtk_toggle_button_get_active (GTK_TOGGLE_BUTTON (check));
+
+  gtk_assistant_set_page_complete (pdata->assistant,
+				   pdata->page,
+				   complete);
+}
+
+	     
+static void
+add_completion_test_page (GtkWidget   *assistant,
+			  const gchar *text, 
+			  gboolean     visible,
+			  gboolean     complete)
+{
+  GtkWidget *page;
+  GtkWidget *check;
+  PageData *pdata;
+
+  page = gtk_vbox_new (0, FALSE);
+  check = gtk_check_button_new_with_label ("Complete");
+
+  gtk_container_add (GTK_CONTAINER (page), gtk_label_new (text));
+  gtk_container_add (GTK_CONTAINER (page), check);
+  
+  gtk_toggle_button_set_active (GTK_TOGGLE_BUTTON (check), complete);
+
+  pdata = g_new (PageData, 1);
+  pdata->assistant = GTK_ASSISTANT (assistant);
+  pdata->page = page;
+  g_signal_connect (G_OBJECT (check), "toggled", 
+		    G_CALLBACK (complete_cb), pdata);
+
+
+  if (visible)
+    gtk_widget_show_all (page);
+
+  gtk_assistant_append_page (GTK_ASSISTANT (assistant), page);
+  gtk_assistant_set_page_title (GTK_ASSISTANT (assistant), page, text);
+  gtk_assistant_set_page_complete (GTK_ASSISTANT (assistant), page, complete);
+}
+
 static void
 cancel_callback (GtkWidget *widget)
 {
@@ -167,17 +220,9 @@ create_generous_assistant (GtkWidget *widget)
       gtk_assistant_set_page_type  (GTK_ASSISTANT (assistant), page, GTK_ASSISTANT_PAGE_INTRO);
       gtk_assistant_set_page_complete (GTK_ASSISTANT (assistant), page, TRUE);
 
-      page = get_test_page ("Content");
+      add_completion_test_page (assistant, "Content", TRUE, FALSE);
-      gtk_widget_show (page);
+      add_completion_test_page (assistant, "More Content", TRUE, TRUE);
-      gtk_assistant_append_page (GTK_ASSISTANT (assistant), page);
+      add_completion_test_page (assistant, "Even More Content", TRUE, TRUE);
-      gtk_assistant_set_page_title (GTK_ASSISTANT (assistant), page, "Content");
-      gtk_assistant_set_page_complete (GTK_ASSISTANT (assistant), page, TRUE);
-
-      page = get_test_page ("More content");
-      gtk_widget_show (page);
-      gtk_assistant_append_page (GTK_ASSISTANT (assistant), page);
-      gtk_assistant_set_page_title (GTK_ASSISTANT (assistant), page, "More content");
-      gtk_assistant_set_page_complete (GTK_ASSISTANT (assistant), page, TRUE);
 
       page = get_test_page ("Confirmation");
       gtk_widget_show (page);
@@ -404,6 +449,70 @@ create_looping_assistant (GtkWidget *widget)
     }
 }
 
+static void
+create_full_featured_assistant (GtkWidget *widget)
+{
+  static GtkWidget *assistant = NULL;
+
+  if (!assistant)
+    {
+      GtkWidget *page, *button;
+	 GdkPixbuf *pixbuf;
+
+      assistant = gtk_assistant_new ();
+      gtk_window_set_default_size (GTK_WINDOW (assistant), 400, 300);
+
+	 button = gtk_button_new_from_stock (GTK_STOCK_STOP);
+	 gtk_widget_show (button);
+	 gtk_assistant_add_action_widget (GTK_ASSISTANT (assistant), button);
+
+      g_signal_connect (G_OBJECT (assistant), "cancel",
+			G_CALLBACK (cancel_callback), NULL);
+      g_signal_connect (G_OBJECT (assistant), "close",
+			G_CALLBACK (close_callback), NULL);
+      g_signal_connect (G_OBJECT (assistant), "apply",
+			G_CALLBACK (apply_callback), NULL);
+      g_signal_connect (G_OBJECT (assistant), "prepare",
+			G_CALLBACK (prepare_callback), NULL);
+
+      page = get_test_page ("Page 1");
+      gtk_widget_show (page);
+      gtk_assistant_append_page (GTK_ASSISTANT (assistant), page);
+      gtk_assistant_set_page_title (GTK_ASSISTANT (assistant), page, "Page 1");
+      gtk_assistant_set_page_complete (GTK_ASSISTANT (assistant), page, TRUE);
+
+	 /* set a side image */
+	 pixbuf = gtk_widget_render_icon (page, GTK_STOCK_DIALOG_WARNING, GTK_ICON_SIZE_DIALOG, NULL);
+	 gtk_assistant_set_page_side_image (GTK_ASSISTANT (assistant), page, pixbuf);
+
+	 /* set a header image */
+	 pixbuf = gtk_widget_render_icon (page, GTK_STOCK_DIALOG_INFO, GTK_ICON_SIZE_DIALOG, NULL);
+	 gtk_assistant_set_page_header_image (GTK_ASSISTANT (assistant), page, pixbuf);
+
+      page = get_test_page ("Invisible page");
+      gtk_assistant_append_page (GTK_ASSISTANT (assistant), page);
+
+      page = get_test_page ("Page 3");
+      gtk_widget_show (page);
+      gtk_assistant_append_page (GTK_ASSISTANT (assistant), page);
+      gtk_assistant_set_page_title (GTK_ASSISTANT (assistant), page, "Page 3");
+      gtk_assistant_set_page_type  (GTK_ASSISTANT (assistant), page, GTK_ASSISTANT_PAGE_CONFIRM);
+      gtk_assistant_set_page_complete (GTK_ASSISTANT (assistant), page, TRUE);
+
+	 /* set a header image */
+	 pixbuf = gtk_widget_render_icon (page, GTK_STOCK_DIALOG_INFO, GTK_ICON_SIZE_DIALOG, NULL);
+	 gtk_assistant_set_page_header_image (GTK_ASSISTANT (assistant), page, pixbuf);
+    }
+
+  if (!GTK_WIDGET_VISIBLE (assistant))
+    gtk_widget_show (assistant);
+  else
+    {
+      gtk_widget_destroy (assistant);
+      assistant = NULL;
+    }
+}
+
 struct {
   gchar *text;
   void  (*func) (GtkWidget *widget);
@@ -413,6 +522,7 @@ struct {
     { "generous assistant",      create_generous_assistant },
     { "nonlinear assistant",     create_nonlinear_assistant },
     { "looping assistant",       create_looping_assistant },
+    { "full featured assistant", create_full_featured_assistant },
   };
 
 int