vcs.maemo.org Git - hildon/blob - src/hildon-wizard-dialog.c

   1 /*
   2  * This file is a part of hildon
   3  *
   4  * Copyright (C) 2005, 2006 Nokia Corporation, all rights reserved.
   5  *
   6  * Contact: Rodrigo Novo <rodrigo.novo@nokia.com>
   7  *   Fixes: Michael Dominic Kostrzewa <michael.kostrzewa@nokia.com>
   8  *
   9  * This library is free software; you can redistribute it and/or
  10  * modify it under the terms of the GNU Lesser General Public License
  11  * as published by the Free Software Foundation; version 2.1 of
  12  * the License, or (at your option) any later version.
  13  *
  14  * This library is distributed in the hope that it will be useful, but
  15  * WITHOUT ANY WARRANTY; without even the implied warranty of
  16  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  17  * Lesser General Public License for more details.
  18  *
  19  * You should have received a copy of the GNU Lesser General Public
  20  * License along with this library; if not, write to the Free Software
  21  * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
  22  * 02110-1301 USA
  23  *
  24  */
  25
  26 /**
  27  * SECTION:hildon-wizard-dialog
  28  * @short_description: A widget to create a guided installation
  29  * process wizard.
  30  *
  31  * #HildonWizardDialog is a widget to create a guided installation
  32  * process. The dialog has three standard buttons, previous, next,
  33  * finish, and contains several pages.
  34  *
  35  * Response buttons are dimmed/undimmed automatically. The notebook
  36  * widget provided by users contains the actual wizard pages.
  37  *
  38  * Usage of the API is very simple, it has only one function to create it
  39  * and the rest of it is handled by developers notebook.
  40  * Also, the response is returned, either cancel or finish.
  41  * Next and previous buttons are handled by the wizard dialog it self, by
  42  * switching the page either forward or backward in the notebook.
  43  */
  44
  45 #ifdef                                          HAVE_CONFIG_H
  46 #include                                        <config.h>
  47 #endif
  48
  49 #include                                        <libintl.h>
  50
  51 #include                                        "hildon-wizard-dialog.h"
  52 #include                                        "hildon-defines.h"
  53 #include                                        "hildon-wizard-dialog-private.h"
  54
  55 #define                                         _(String) dgettext("hildon-libs", String)
  56
  57 static GtkDialogClass*                          parent_class;
  58
  59 static void
  60 hildon_wizard_dialog_class_init                 (HildonWizardDialogClass *wizard_dialog_class);
  61
  62 static void
  63 hildon_wizard_dialog_init                       (HildonWizardDialog *wizard_dialog);
  64
  65 static void
  66 create_title                                    (HildonWizardDialog *wizard_dialog);
  67
  68 static void
  69 hildon_wizard_dialog_set_property               (GObject *object,
  70                                                  guint property_id,
  71                                                  const GValue *value,
  72                                                  GParamSpec *pspec);
  73
  74 static void
  75 hildon_wizard_dialog_get_property               (GObject *object,
  76                                                  guint property_id,
  77                                                  GValue *value,
  78                                                  GParamSpec *pspec);
  79
  80 static void
  81 finalize                                        (GObject *object);
  82
  83 static void
  84 destroy                                         (GtkObject *object);
  85
  86 static void
  87 response                                        (HildonWizardDialog *wizard,
  88                                                  gint response_id,
  89                                                  gpointer unused);
  90
  91 static void
  92 make_buttons_sensitive                          (HildonWizardDialog *wizard_dialog,
  93                                                  gboolean previous,
  94                                                  gboolean finish,
  95                                                  gboolean next);
  96
  97 enum
  98 {
  99     PROP_0,
 100     PROP_NAME,
 101     PROP_NOTEBOOK,
 102     PROP_AUTOTITLE
 103 };
 104
 105 /**
 106  * hildon_wizard_dialog_get_type:
 107  *
 108  * Initializes and returns the type of a hildon wizard dialog.
 109  *
 110  * @Returns: GType of #HildonWzardDialog
 111  */
 112 GType G_GNUC_CONST
 113 hildon_wizard_dialog_get_type                   (void)
 114 {
 115     static GType wizard_dialog_type = 0;
 116
 117     if (! wizard_dialog_type) {
 118
 119         static const GTypeInfo wizard_dialog_info = {
 120             sizeof (HildonWizardDialogClass),
 121             NULL,       /* base_init      */
 122             NULL,       /* base_finalize  */
 123             (GClassInitFunc) hildon_wizard_dialog_class_init,
 124             NULL,       /* class_finalize */
 125             NULL,       /* class_data     */
 126             sizeof (HildonWizardDialog),
 127             0,          /* n_preallocs    */
 128             (GInstanceInitFunc) hildon_wizard_dialog_init,
 129         };
 130
 131         wizard_dialog_type = g_type_register_static (GTK_TYPE_DIALOG,
 132                 "HildonWizardDialog",
 133                 &wizard_dialog_info,
 134                 0);
 135     }
 136
 137     return wizard_dialog_type;
 138 }
 139
 140 static void
 141 hildon_wizard_dialog_class_init                 (HildonWizardDialogClass *wizard_dialog_class)
 142 {
 143     GObjectClass *object_class = G_OBJECT_CLASS (wizard_dialog_class);
 144     GtkObjectClass *gtk_object_class = GTK_OBJECT_CLASS (wizard_dialog_class);
 145     parent_class = g_type_class_peek_parent (wizard_dialog_class);
 146
 147     g_type_class_add_private (wizard_dialog_class, sizeof (HildonWizardDialogPrivate));
 148
 149     /* Override virtual methods */
 150     object_class->set_property = hildon_wizard_dialog_set_property;
 151     object_class->get_property = hildon_wizard_dialog_get_property;
 152     object_class->finalize     = finalize;
 153     gtk_object_class->destroy  = destroy;
 154
 155     /**
 156      * HildonWizardDialog:wizard-name:
 157      *
 158      * The name of the wizard.
 159      */
 160     g_object_class_install_property (object_class, PROP_NAME,
 161             g_param_spec_string
 162             ("wizard-name",
 163              "Wizard Name",
 164              "The name of the HildonWizardDialog",
 165              NULL,
 166              G_PARAM_READWRITE));
 167
 168     /**
 169      * HildonWizardDialog:wizard-notebook:
 170      *
 171      * The notebook object, which is used by the HildonWizardDialog.
 172      */
 173     g_object_class_install_property (object_class, PROP_NOTEBOOK,
 174             g_param_spec_object
 175             ("wizard-notebook",
 176              "Wizard Notebook",
 177              "GtkNotebook object to be used in the "
 178              "HildonWizardDialog",
 179              GTK_TYPE_NOTEBOOK, G_PARAM_READWRITE));
 180
 181     /**
 182      * HildonWizardDialog:autotitle
 183      *
 184      * If the wizard should automatically try to change the window title when changing steps.
 185      * Set to FALSE if you'd like to override the default behaviour.
 186      *
 187      * Since: 0.14.5
 188      */
 189     g_object_class_install_property (object_class, PROP_AUTOTITLE,
 190             g_param_spec_boolean
 191             ("autotitle",
 192              "AutoTitle",
 193              "If the wizard should autotitle itself",
 194              TRUE,
 195              G_PARAM_READWRITE));
 196 }
 197
 198 static void
 199 finalize                                        (GObject *object)
 200 {
 201     HildonWizardDialogPrivate *priv = HILDON_WIZARD_DIALOG_GET_PRIVATE (object);
 202
 203     g_assert (priv);
 204
 205     if (priv->wizard_name != NULL)
 206         g_free (priv->wizard_name);
 207
 208     if (G_OBJECT_CLASS (parent_class)->finalize)
 209         G_OBJECT_CLASS (parent_class)->finalize (object);
 210 }
 211
 212 static void
 213 destroy                                         (GtkObject *object)
 214 {
 215     HildonWizardDialogPrivate *priv = HILDON_WIZARD_DIALOG_GET_PRIVATE (object);
 216
 217     g_assert (priv);
 218
 219     if (priv->forward_function)
 220     {
 221       if (priv->forward_function_data &&
 222           priv->forward_data_destroy)
 223         priv->forward_data_destroy (priv->forward_function_data);
 224
 225       priv->forward_function = NULL;
 226       priv->forward_function_data = NULL;
 227       priv->forward_data_destroy = NULL;
 228     }
 229 }
 230
 231 /* Disable or enable the Previous, Next and Finish buttons */
 232 static void
 233 make_buttons_sensitive                          (HildonWizardDialog *wizard_dialog,
 234                                                  gboolean previous,
 235                                                  gboolean finish,
 236                                                  gboolean next)
 237 {
 238     gtk_dialog_set_response_sensitive (GTK_DIALOG (wizard_dialog),
 239             HILDON_WIZARD_DIALOG_PREVIOUS,
 240             previous);
 241
 242     gtk_dialog_set_response_sensitive (GTK_DIALOG (wizard_dialog),
 243             HILDON_WIZARD_DIALOG_FINISH,
 244             finish);
 245
 246     gtk_dialog_set_response_sensitive (GTK_DIALOG (wizard_dialog),
 247             HILDON_WIZARD_DIALOG_NEXT,
 248             next);
 249 }
 250
 251 static void
 252 hildon_wizard_dialog_init                       (HildonWizardDialog *wizard_dialog)
 253 {
 254     /* Initialize private structure for faster member access */
 255     HildonWizardDialogPrivate *priv = HILDON_WIZARD_DIALOG_GET_PRIVATE (wizard_dialog);
 256     g_assert (priv);
 257
 258     GtkDialog *dialog = GTK_DIALOG (wizard_dialog);
 259
 260     /* Init internal widgets */
 261     gtk_dialog_set_has_separator (dialog, FALSE);
 262
 263     /* Default values for user provided properties */
 264     priv->notebook = NULL;
 265     priv->wizard_name = NULL;
 266     priv->autotitle = TRUE;
 267
 268     priv->forward_function = NULL;
 269     priv->forward_function_data = NULL;
 270     priv->forward_data_destroy = NULL;
 271
 272     /* Add response buttons: finish, previous, next */
 273     gtk_dialog_add_button (dialog, _("wdgt_bd_finish"), HILDON_WIZARD_DIALOG_FINISH);
 274     gtk_dialog_add_button (dialog, _("wdgt_bd_previous"), HILDON_WIZARD_DIALOG_PREVIOUS);
 275     gtk_dialog_add_button (dialog, _("wdgt_bd_next"), HILDON_WIZARD_DIALOG_NEXT);
 276
 277     /* Set initial button states: previous and finish buttons are disabled */
 278     make_buttons_sensitive (wizard_dialog, FALSE, FALSE, TRUE);
 279
 280     /* Show all the internal widgets */
 281     gtk_widget_show_all (GTK_WIDGET (dialog->vbox));
 282
 283     /* connect to dialog's response signal */
 284     g_signal_connect (G_OBJECT (dialog), "response",
 285             G_CALLBACK (response), NULL);
 286 }
 287
 288 static void
 289 hildon_wizard_dialog_set_property               (GObject *object,
 290                                                  guint property_id,
 291                                                  const GValue *value,
 292                                                  GParamSpec *pspec)
 293 {
 294     HildonWizardDialogPrivate *priv = HILDON_WIZARD_DIALOG_GET_PRIVATE (object);
 295     GtkDialog *dialog = GTK_DIALOG (object);
 296
 297     g_assert (priv);
 298
 299     switch (property_id) {
 300
 301         case PROP_AUTOTITLE:
 302
 303             priv->autotitle = g_value_get_boolean (value);
 304
 305             if (priv->autotitle &&
 306                     priv->wizard_name &&
 307                     priv->notebook)
 308                 create_title (HILDON_WIZARD_DIALOG (object));
 309             else if (priv->wizard_name)
 310                 gtk_window_set_title (GTK_WINDOW (object), priv->wizard_name);
 311             break;
 312
 313         case PROP_NAME:
 314
 315             /* Set new wizard name. This name will appear in titlebar */
 316             if (priv->wizard_name)
 317                 g_free (priv->wizard_name);
 318
 319             gchar *str = (gchar *) g_value_get_string (value);
 320             g_return_if_fail (str != NULL);
 321
 322             priv->wizard_name = g_strdup (str);
 323
 324             /* We need notebook in order to create title, since page information
 325                is used in title generation */
 326
 327             if (priv->notebook && priv->autotitle)
 328                 create_title (HILDON_WIZARD_DIALOG (object));
 329             break;
 330
 331         case PROP_NOTEBOOK: {
 332
 333             GtkNotebook *book = GTK_NOTEBOOK (g_value_get_object (value));
 334             g_return_if_fail (book != NULL);
 335
 336             priv->notebook = book;
 337
 338             /* Set the default properties for the notebook (disable tabs,
 339              * and remove borders) to make it look like a nice wizard widget */
 340             gtk_notebook_set_show_tabs (priv->notebook, FALSE);
 341             gtk_notebook_set_show_border (priv->notebook, FALSE);
 342             gtk_box_pack_start_defaults (GTK_BOX (dialog->vbox), GTK_WIDGET (priv->notebook));
 343
 344             /* Show the notebook so that a gtk_widget_show on the dialog is
 345              * all that is required to display the dialog correctly */
 346             gtk_widget_show (GTK_WIDGET (priv->notebook));
 347
 348             /* Update dialog title to reflect current page stats etc */
 349             if (priv->wizard_name && priv->autotitle)
 350                 create_title (HILDON_WIZARD_DIALOG (object));
 351
 352         } break;
 353
 354         default:
 355             G_OBJECT_WARN_INVALID_PROPERTY_ID (object, property_id, pspec);
 356             break;
 357     }
 358 }
 359
 360 static void
 361 hildon_wizard_dialog_get_property               (GObject *object,
 362                                                  guint property_id,
 363                                                  GValue *value,
 364                                                  GParamSpec *pspec)
 365 {
 366     HildonWizardDialogPrivate *priv = HILDON_WIZARD_DIALOG_GET_PRIVATE (object);
 367     g_assert (priv);
 368
 369     switch (property_id) {
 370
 371         case PROP_NAME:
 372             g_value_set_string (value, priv->wizard_name);
 373             break;
 374
 375         case PROP_NOTEBOOK:
 376             g_value_set_object (value, priv->notebook);
 377             break;
 378
 379         default:
 380             G_OBJECT_WARN_INVALID_PROPERTY_ID (object, property_id, pspec);
 381             break;
 382     }
 383 }
 384
 385 /* Creates the title of the dialog taking into account the current
 386  * page of the notebook. */
 387 static void
 388 create_title                                    (HildonWizardDialog *wizard_dialog)
 389 {
 390     gint pages, current;
 391     gchar *str = NULL;
 392     HildonWizardDialogPrivate *priv = HILDON_WIZARD_DIALOG_GET_PRIVATE (wizard_dialog);
 393     GtkNotebook *notebook;
 394
 395     g_assert (priv);
 396     notebook = priv->notebook;
 397
 398     if (! notebook)
 399         return;
 400
 401     /* Get page information, we'll need that when creating title */
 402     pages = gtk_notebook_get_n_pages (notebook);
 403     current = gtk_notebook_get_current_page (priv->notebook);
 404     if (current < 0)
 405         current = 0;
 406
 407     /* the welcome title on the initial page */
 408     if (current == 0) {
 409         str = g_strdup_printf (_("ecdg_ti_wizard_welcome"),
 410                 priv->wizard_name);
 411     } else {
 412         const gchar *steps = gtk_notebook_get_tab_label_text (notebook,
 413                 gtk_notebook_get_nth_page (notebook, current));
 414
 415         str = g_strdup_printf (_("%s: %s"), priv->wizard_name, steps);
 416     }
 417
 418     /* Update the dialog to display the generated title */
 419     gtk_window_set_title (GTK_WINDOW (wizard_dialog), str);
 420     g_free (str);
 421 }
 422
 423 /* Response signal handler. This function is needed because GtkDialog's
 424  * handler for this signal closes the dialog and we don't want that, we
 425  * want to change pages and, dimm certain response buttons. Overriding the
 426  * virtual function would not work because that would be called after the
 427  * signal handler implemented by GtkDialog.
 428  * FIXME: There is a much saner way to do that [MDK] */
 429 static void
 430 response                                        (HildonWizardDialog *wizard_dialog,
 431                                                  gint response_id,
 432                                                  gpointer unused)
 433 {
 434     HildonWizardDialogPrivate *priv = HILDON_WIZARD_DIALOG_GET_PRIVATE (wizard_dialog);
 435     GtkNotebook *notebook = priv->notebook;
 436     gint current = 0;
 437     gint last = gtk_notebook_get_n_pages (notebook) - 1;
 438     gboolean is_first, is_last;
 439
 440     g_assert (priv);
 441
 442     current = gtk_notebook_current_page (notebook);
 443
 444     switch (response_id) {
 445
 446         case HILDON_WIZARD_DIALOG_PREVIOUS:
 447             --current;
 448             is_last = (current == last);
 449             is_first = (current == 0);
 450             make_buttons_sensitive (wizard_dialog,
 451                                     !is_first, !is_first, !is_last);
 452             gtk_notebook_prev_page (notebook); /* go to previous page */
 453             break;
 454
 455         case HILDON_WIZARD_DIALOG_NEXT:
 456
 457           if (!priv->forward_function ||
 458                 (*priv->forward_function) (priv->notebook, current, priv->forward_function_data)) {
 459               ++current;
 460               is_last = (current == last);
 461               is_first = (current == 0);
 462               make_buttons_sensitive (wizard_dialog,
 463                                       !is_first, !is_first, !is_last);
 464               gtk_notebook_next_page (notebook); /* go to next page */
 465             }
 466             break;
 467
 468         case HILDON_WIZARD_DIALOG_FINISH:
 469             return;
 470
 471     }
 472
 473     current = gtk_notebook_get_current_page (notebook);
 474     is_last = current == last;
 475     is_first = current == 0;
 476
 477     /* Don't let the dialog close */
 478     g_signal_stop_emission_by_name (wizard_dialog, "response");
 479
 480     /* New page number may appear in the title, update it */
 481     if (priv->autotitle)
 482         create_title (wizard_dialog);
 483 }
 484
 485 /**
 486  * hildon_wizard_dialog_new:
 487  * @parent: a #GtkWindow
 488  * @wizard_name: the name of dialog
 489  * @notebook: the notebook to be shown on the dialog
 490  *
 491  * Creates a new #HildonWizardDialog.
 492  *
 493  * Returns: a new #HildonWizardDialog
 494  */
 495 GtkWidget*
 496 hildon_wizard_dialog_new                        (GtkWindow *parent,
 497                                                  const char *wizard_name,
 498                                                  GtkNotebook *notebook)
 499 {
 500     GtkWidget *widget;
 501
 502     g_return_val_if_fail (GTK_IS_NOTEBOOK (notebook), NULL);
 503
 504     widget = GTK_WIDGET (g_object_new
 505             (HILDON_TYPE_WIZARD_DIALOG,
 506              "wizard-name", wizard_name,
 507              "wizard-notebook", notebook, NULL));
 508
 509     if (parent)
 510         gtk_window_set_transient_for (GTK_WINDOW (widget), parent);
 511
 512     return widget;
 513 }
 514
 515 /**
 516  * hildon_wizard_dialog_set_forward_page_func:
 517  * @dialog: a #HildonWizardDialog
 518  * @page_func: the #HildonWizardDialogPageFunc
 519  * @data: user data for @page_func
 520  * @destroy: destroy notifier for @data
 521  *
 522  * Sets the page forwarding function to be @page_func. This function
 523  * will be used to determine whether it is possible to go to the next page
 524  * when the user presses the forward button. Setting @page_func to %NULL
 525  * wil make the wizard to simply go always to the next page.
 526  *
 527  * Since: 2.2
 528  **/
 529 void
 530 hildon_wizard_dialog_set_forward_page_func      (HildonWizardDialog *wizard_dialog,
 531                                                  HildonWizardDialogPageFunc page_func,
 532                                                  gpointer data,
 533                                                  GDestroyNotify destroy)
 534 {
 535   g_return_if_fail (HILDON_IS_WIZARD_DIALOG (wizard_dialog));
 536
 537   HildonWizardDialogPrivate *priv = HILDON_WIZARD_DIALOG_GET_PRIVATE (wizard_dialog);
 538
 539   if (priv->forward_data_destroy &&
 540       priv->forward_function_data) {
 541     (*priv->forward_data_destroy) (priv->forward_function_data);
 542   }
 543
 544   priv->forward_function = page_func;
 545   priv->forward_function_data = data;
 546   priv->forward_data_destroy = destroy;
 547 }