git.maemo.org Git - hildon/blob - doc/migration.sgml

   1 <refentry id="hildon-migration-control-bar" revision="13 Feb 2001">
   2 <refmeta>
   3 <refentrytitle>Control Bar</refentrytitle>
   4 <manvolnum>3</manvolnum>
   5 <refmiscinfo>Hildon Library</refmiscinfo>
   6 </refmeta>
   7
   8 <refnamediv>
   9     <refname>Control Bar</refname>
  10     <refpurpose>How to migrate Control Bars</refpurpose>
  11 </refnamediv>
  12
  13 <refsect1 id="hildon-migrating-control-bar">
  14     <title>Migrating Control Bars</title>
  15
  16     <para>ControlBar widgets are deprecated since Hildon 2.2 and a GtkScale
  17     should be used to accomplish the same functionality.</para>
  18
  19     <para>To make a GtkScale have the same functionality as a control
  20     bar you'll need to change some properties of the widget's Adjustment
  21     so it has a range equal to the control bar's as well as the step
  22     increment.</para>
  23
  24     <para>The following example shows a control bar with the range of
  25     0 to 4.</para>
  26
  27     <example>
  28         <title>A Typical Control Bar</title>
  29         <programlisting>
  30 <![CDATA[
  31 HildonControlbar *bar = HILDON_CONTROLBAR (hildon_controlbar_new ());
  32 hildon_controlbar_set_range (bar, 1, 4);
  33 hildon_controlbar_set_value (bar, 2);
  34 ]]>
  35         </programlisting>
  36     </example>
  37
  38     <para>To accomplish the same functionality as the previous control
  39     bar example, one could use something like in the following example.</para>
  40
  41     <example>
  42         <title>A Replacement for the Control Bar</title>
  43         <programlisting>
  44 <![CDATA[
  45 GtkHScale *scale = GTK_HSCALE (hildon_gtk_hscale_new ());
  46 GtkAdjustment *adjustment = GTK_ADJUSTMENT (
  47                         gtk_range_get_adjustment (GTK_RANGE (scale)));
  48 g_object_set (adjustment, "step-increment", 1, "lower", 0, NULL);
  49 g_object_set (adjustment, "upper", 4, NULL);
  50 g_object_set (adjustment, "value", 2, NULL);
  51 ]]>
  52         </programlisting>
  53     </example>
  54 </refsect1>
  55 </refentry>
  56
  57 <refentry id="hildon-migration-volume-bar" revision="13 Feb 2001">
  58 <refmeta>
  59 <refentrytitle>Volume Bar</refentrytitle>
  60 <manvolnum>3</manvolnum>
  61 <refmiscinfo>Hildon Library</refmiscinfo>
  62 </refmeta>
  63
  64 <refnamediv>
  65     <refname>Volume Bar</refname>
  66     <refpurpose>How to migrate Volume Bars</refpurpose>
  67 </refnamediv>
  68
  69 <refsect1 id="hildon-migrating-volume-bar">
  70     <title>Migrating Volume Bars</title>
  71
  72     <para>VolumeBar widgets are deprecated since Hildon 2.2 and the way
  73     to exactly reproduce their functionality is to use a GtkScale together
  74     with a toggle button. Instead of the toggle button, a Hildon picker
  75     button could be used or two radio buttons or any other widgets that
  76     allow the user to choose from two options. The toggle button is used
  77     in this example since it is the very similar with the deprecated
  78     volume bar's button.</para>
  79
  80     <para>The deprecated volume bar is shown on the example bellow.</para>
  81
  82     <example>
  83         <title>A Typical Volume Bar</title>
  84         <programlisting>
  85 <![CDATA[
  86 HildonVVolumebar *bar = HILDON_VVOLUMEBAR (hildon_vvolumebar_new ());
  87 gtk_widget_set_size_request (GTK_WIDGET (bar), -1, 300);
  88 ]]>
  89         </programlisting>
  90     </example>
  91
  92     <para>A very similar widget can be done like the following example
  93     shows.</para>
  94
  95     <example>
  96         <title>A Replacement for the Volume Bar</title>
  97         <programlisting>
  98 <![CDATA[
  99 void
 100 toggle_volume_state_cb (GtkToggleButton *toggle, gpointer data)
 101 {
 102     GtkVScale *bar = GTK_VSCALE (data);
 103     gboolean mute = gtk_toggle_button_get_active (toggle);
 104     gtk_widget_set_sensitive (GTK_WIDGET (bar), !mute);
 105 }
 106
 107 GtkVScale *bar = GTK_VSCALE (hildon_gtk_vscale_new ());
 108 gtk_widget_set_size_request (GTK_WIDGET (bar), -1, 300);
 109 gtk_range_set_restrict_to_fill_level (GTK_RANGE (bar), TRUE);
 110 GtkToggleButton *toggle_volume = GTK_TOGGLE_BUTTON (hildon_gtk_toggle_button_new (
 111                                         HILDON_SIZE_FINGER_HEIGHT));
 112 gtk_button_set_label (GTK_BUTTON (toggle_volume), "Mute");
 113 g_signal_connect (toggle_volume, "toggled",
 114                     G_CALLBACK (toggle_volume_state_cb), bar);
 115 GtkVBox *volume = GTK_VBOX (gtk_vbox_new (0, FALSE));
 116 gtk_container_add (GTK_CONTAINER (volume), GTK_WIDGET (bar));
 117 gtk_box_pack_end (GTK_BOX (volume), GTK_WIDGET (toggle_volume), FALSE, FALSE, 0);
 118 ]]>
 119         </programlisting>
 120     </example>
 121 </refsect1>
 122 </refentry>
 123
 124 <refentry id="hildon-migration-date-widgets" revision="13 Feb 2001">
 125 <refmeta>
 126 <refentrytitle>Date Widgets</refentrytitle>
 127 <manvolnum>3</manvolnum>
 128 <refmiscinfo>Hildon Library</refmiscinfo>
 129 </refmeta>
 130
 131 <refnamediv>
 132     <refname>Date Bar</refname>
 133     <refpurpose>How to migrate Date widgets</refpurpose>
 134 </refnamediv>
 135
 136 <refsect1 id="hildon-migrating-date-widgets">
 137     <title>Migrating Date Widgets</title>
 138
 139     <para>Being deprecated since Hildon 2.2, the calendar popup and
 140     date editor can be substituded by a HildonDateButton.</para>
 141
 142     <para>Examples of a typical calendar popup and a date editor are
 143     presented bellow.</para>
 144
 145     <example>
 146         <title>A Typical Calendar Popup</title>
 147         <programlisting>
 148 <![CDATA[
 149 guint y = 2009, m = 4, d = 25;
 150 GtkWidget *parent, *popup;
 151 popup = hildon_calendar_popup_new (GTK_WINDOW (parent), y, m, d);
 152 gtk_dialog_run (GTK_DIALOG (popup));
 153 hildon_calendar_popup_get_date (HILDON_CALENDAR_POPUP (popup),
 154                                         &y, &m, &d);
 155 ]]>
 156         </programlisting>
 157     </example>
 158
 159     <example>
 160         <title>A Typical Date Editor</title>
 161         <programlisting>
 162 <![CDATA[
 163 gboolean
 164 on_error (GtkWidget *widget, HildonDateTimeError error_type);
 165
 166 gboolean
 167 on_error (GtkWidget *widget, HildonDateTimeError error_type)
 168 {
 169     g_debug ("Error: %d", error_type);
 170     return FALSE;
 171 }
 172
 173 GtkDialog *dialog = GTK_DIALOG (gtk_dialog_new ());
 174 HildonDateEditor *date_editor = HILDON_DATE_EDITOR (hildon_date_editor_new ());
 175
 176 gtk_box_pack_start (GTK_BOX (dialog->vbox), gtk_label_new ("Choose a date"), FALSE, FALSE, 10);
 177 gtk_box_pack_start (GTK_BOX (dialog->vbox), GTK_WIDGET (date_editor), FALSE, FALSE, 10);
 178 gtk_dialog_add_button (dialog, "Close", GTK_RESPONSE_CANCEL);
 179
 180 g_signal_connect (G_OBJECT (date_editor), "date_error", G_CALLBACK (on_error), NULL);
 181
 182 gtk_widget_show_all (GTK_WIDGET (dialog));
 183 gtk_dialog_run (dialog);
 184
 185 hildon_date_editor_get_date (date_editor, &y, &m, &d);
 186 ]]>
 187         </programlisting>
 188     </example>
 189
 190     <para>The following example accomplishes equivalent functionality
 191     using a HildonDateButton.</para>
 192
 193     <example>
 194         <title>A Replacement for the Calendar Popup</title>
 195         <programlisting>
 196 <![CDATA[
 197 GtkDialog *dialog = GTK_DIALOG (gtk_dialog_new ());
 198 guint y = 2009, m = 3, d = 25;
 199 HildonDateButton *date_button = HILDON_DATE_BUTTON (hildon_date_button_new (
 200             HILDON_SIZE_THUMB_HEIGHT, HILDON_BUTTON_ARRANGEMENT_VERTICAL));
 201 hildon_date_button_set_date (date_button, y, m, d);
 202 gtk_box_pack_end (GTK_BOX (dialog->vbox), GTK_WIDGET (date_button), FALSE, FALSE, 0);
 203 gtk_widget_show_all (GTK_WIDGET (dialog));
 204 gtk_dialog_run (dialog);
 205 hildon_date_button_get_date (date_button, &y, &m, &d);
 206 ]]>
 207         </programlisting>
 208     </example>
 209 </refsect1>
 210
 211 <refsect1>
 212     <title>Weekday Picker</title>
 213
 214     <para>A weekday picker (deprecated since Hildon 2.2) can be easily
 215     replaced by a HildonPickerButton.</para>
 216
 217     <para>The following example presents the deprecated weekday picker
 218     in a dialog.</para>
 219
 220     <example>
 221         <title>A Typical Weekday Picker</title>
 222         <programlisting>
 223 <![CDATA[
 224 GtkDialog *dialog = GTK_DIALOG (gtk_dialog_new ());
 225 GtkWidget *picker = hildon_weekday_picker_new ();
 226 gtk_box_pack_start (GTK_BOX (dialog->vbox), picker, TRUE, TRUE, 0);
 227 gtk_dialog_add_button (dialog, "Close", GTK_RESPONSE_CLOSE);
 228 gtk_widget_show_all (GTK_WIDGET (dialog));
 229 gtk_dialog_run (dialog);
 230 ]]>
 231         </programlisting>
 232     </example>
 233
 234     <para>With a HildonPickerButton it is easy to add the weekdays to its
 235     TouchSelector and thus having the same functionality.</para>
 236
 237     <example>
 238         <title>A Replacement for the Weekday Picker</title>
 239         <programlisting>
 240 <![CDATA[
 241 GtkDialog *dialog = GTK_DIALOG (gtk_dialog_new ());
 242 GtkWidget *picker = hildon_picker_button_new (HILDON_SIZE_THUMB_HEIGHT,
 243                                 HILDON_BUTTON_ARRANGEMENT_VERTICAL);
 244 hildon_button_set_title (HILDON_BUTTON (picker), "Weekday:");
 245 HildonTouchSelector *selector = HILDON_TOUCH_SELECTOR (
 246                                 hildon_touch_selector_new_text ());
 247 hildon_touch_selector_append_text (selector, "Sunday");
 248 hildon_touch_selector_append_text (selector, "Monday");
 249 hildon_touch_selector_append_text (selector, "Tuesday");
 250 hildon_touch_selector_append_text (selector, "Thursday");
 251 hildon_touch_selector_append_text (selector, "Friday");
 252 hildon_touch_selector_append_text (selector, "Saturday");
 253 hildon_touch_selector_set_column_selection_mode (selector,
 254                     HILDON_TOUCH_SELECTOR_SELECTION_MODE_MULTIPLE);
 255
 256 hildon_picker_button_set_selector (HILDON_PICKER_BUTTON (picker), selector);
 257 hildon_picker_button_set_active (HILDON_PICKER_BUTTON (picker), 0);
 258 gtk_box_pack_start (GTK_BOX (dialog->vbox), picker, TRUE, TRUE, 0);
 259 gtk_widget_show_all (GTK_WIDGET (dialog));
 260 gtk_dialog_run (dialog);
 261 ]]>
 262         </programlisting>
 263     </example>
 264 </refsect1>
 265 </refentry>
 266
 267 <refentry id="hildon-migration-time-widgets" revision="13 Feb 2001">
 268 <refmeta>
 269 <refentrytitle>Time Widgets</refentrytitle>
 270 <manvolnum>3</manvolnum>
 271 <refmiscinfo>Hildon Library</refmiscinfo>
 272 </refmeta>
 273
 274 <refnamediv>
 275     <refname>Time Widgets</refname>
 276     <refpurpose>How to migrate Time Widgets</refpurpose>
 277 </refnamediv>
 278
 279 <refsect1 id="hildon-migrating-time-widgets">
 280     <title>Migrating Time Widgets</title>
 281
 282     <para>A HildonTimeButton is the way to replace the time picker and
 283     time editor widgets (deprecated
 284     since Hildon version 2.2).</para>
 285
 286     <para>A time picker and time editor are shown in the examples bellow.</para>
 287
 288     <example>
 289         <title>A Typical Time Picker</title>
 290         <programlisting>
 291 <![CDATA[
 292 GtkDialog *dialog = GTK_DIALOG (hildon_time_picker_new (NULL));
 293
 294 gtk_widget_show_all (GTK_WIDGET (dialog));
 295 gtk_dialog_run (dialog);
 296 ]]>
 297         </programlisting>
 298     </example>
 299
 300     <example>
 301         <title>A Typical Time Editor</title>
 302         <programlisting>
 303 <![CDATA[
 304 GtkDialog *dialog = GTK_DIALOG (gtk_dialog_new ());
 305 HildonTimeEditor *time_editor = HILDON_TIME_EDITOR (hildon_time_editor_new ());
 306
 307 gtk_box_pack_start (GTK_BOX (dialog->vbox), GTK_WIDGET (time_editor), FALSE, FALSE, 0);
 308 gtk_dialog_add_button (dialog, "Close", GTK_RESPONSE_CANCEL);
 309
 310 gtk_widget_show_all (GTK_WIDGET (dialog));
 311 gtk_dialog_run (dialog);
 312 ]]>
 313         </programlisting>
 314     </example>
 315
 316     <para>The same functionality can be achieved as the following example
 317     shows.</para>
 318
 319     <example>
 320         <title>A Replacement for the Time Picker</title>
 321         <programlisting>
 322 <![CDATA[
 323 GtkDialog *dialog = GTK_DIALOG (gtk_dialog_new ());
 324 HildonTimeButton *time_button = HILDON_TIME_BUTTON (hildon_time_button_new (
 325             HILDON_SIZE_THUMB_HEIGHT, HILDON_BUTTON_ARRANGEMENT_VERTICAL));
 326 gtk_box_pack_end (GTK_BOX (dialog->vbox), GTK_WIDGET (time_button), FALSE, FALSE, 0);
 327 gtk_widget_show_all (GTK_WIDGET (dialog));
 328 gtk_dialog_run (dialog);
 329 ]]>
 330         </programlisting>
 331     </example>
 332 </refsect1>
 333 </refentry>
 334
 335 <refentry id="hildon-migration-number-widgets" revision="13 Feb 2001">
 336 <refmeta>
 337 <refentrytitle>Number Widgets</refentrytitle>
 338 <manvolnum>3</manvolnum>
 339 <refmiscinfo>Hildon Library</refmiscinfo>
 340 </refmeta>
 341
 342 <refnamediv>
 343     <refname>Number Widgets</refname>
 344     <refpurpose>How to migrate Number Widgets</refpurpose>
 345 </refnamediv>
 346
 347 <refsect1 id="hildon-migrating-number-widgets">
 348     <title>Migrating Number Widgets</title>
 349
 350     <para>To achieve the same functionlity of HildonNumberEditor you
 351     can use a HildonPickerButton with a HildonTouchSelectorEntry assigned
 352     to it. With these widgets you can also easily have the functionality
 353     of a HildonRangeEditor (not covered in this example). Both the
 354     HildonNumberEditor and the HildonRangeEditor are deprecated since
 355     Hildon 2.2.</para>
 356
 357     <para>The following example shows a typical NumberEditor.</para>
 358
 359     <example>
 360         <title>A Typical Number Editor</title>
 361         <programlisting>
 362 <![CDATA[
 363 GtkDialog *dialog = GTK_DIALOG (gtk_dialog_new ());
 364 GtkWidget *editor = hildon_number_editor_new (0, 30);
 365 GtkWidget *label = gtk_label_new ("Number:");
 366 GtkWidget *hbox = gtk_hbox_new (FALSE, 12);
 367
 368 gtk_box_pack_start (GTK_BOX (hbox), label, TRUE, TRUE, 0);
 369 gtk_box_pack_start (GTK_BOX (hbox), editor, FALSE, FALSE, 0);
 370 gtk_box_pack_start (GTK_BOX (dialog->vbox), hbox, TRUE, TRUE, 0);
 371
 372 gtk_widget_show_all (GTK_WIDGET (dialog));
 373 gtk_dialog_run (dialog);
 374 ]]>
 375         </programlisting>
 376     </example>
 377
 378     <para>The functionality of the example above is shown on the example
 379     bellow using by validating the HildonPickerButton's value every time
 380     it's changed. The choices given in the HildonTouchSelectorShould be
 381     the most common choices.</para>
 382
 383     <example>
 384         <title>A Replacement for the Number Editor</title>
 385         <programlisting>
 386 <![CDATA[
 387 void
 388 changed_value_cb (HildonPickerButton *picker, gpointer data)
 389 {
 390     gdouble number = 0;
 391     const gchar *choice = hildon_button_get_value(HILDON_BUTTON (picker));
 392     number = CLAMP(g_ascii_strtod (choice, NULL), 0, 30);
 393     hildon_button_set_value(HILDON_BUTTON (picker), g_strdup_printf ("%d", (int) number));
 394 }
 395
 396 GtkDialog *dialog = GTK_DIALOG (gtk_dialog_new ());
 397 GtkWidget *picker = hildon_picker_button_new (HILDON_SIZE_THUMB_HEIGHT,
 398                                 HILDON_BUTTON_ARRANGEMENT_VERTICAL);
 399 hildon_button_set_title (HILDON_BUTTON (picker), "Number:");
 400 HildonTouchSelector *selector = HILDON_TOUCH_SELECTOR (
 401                                 hildon_touch_selector_entry_new_text ());
 402 hildon_touch_selector_append_text (selector, "0");
 403 hildon_touch_selector_append_text (selector, "5");
 404 hildon_touch_selector_append_text (selector, "10");
 405 hildon_touch_selector_append_text (selector, "15");
 406 hildon_touch_selector_append_text (selector, "20");
 407 hildon_touch_selector_append_text (selector, "25");
 408 hildon_touch_selector_append_text (selector, "30");
 409 hildon_picker_button_set_selector (HILDON_PICKER_BUTTON (picker), selector);
 410 hildon_picker_button_set_active (HILDON_PICKER_BUTTON (picker), 0);
 411 g_signal_connect (G_OBJECT (picker), "value-changed",
 412                                 G_CALLBACK (changed_value_cb), NULL);
 413 gtk_box_pack_start (GTK_BOX (dialog->vbox), picker, TRUE, TRUE, 0);
 414 gtk_widget_show_all (GTK_WIDGET (dialog));
 415 gtk_dialog_run (dialog);
 416 ]]>
 417         </programlisting>
 418     </example>
 419 </refsect1>
 420 </refentry>
 421
 422 <refentry id="hildon-migration-hildon-dialogs" revision="13 Feb 2001">
 423 <refmeta>
 424 <refentrytitle>Hildon Dialogs</refentrytitle>
 425 <manvolnum>3</manvolnum>
 426 <refmiscinfo>Hildon Library</refmiscinfo>
 427 </refmeta>
 428
 429 <refnamediv>
 430     <refname>Hildon Dialogs</refname>
 431     <refpurpose>How to migrate Hildon Dialogs</refpurpose>
 432 </refnamediv>
 433
 434 <refsect1 id="hildon-migrating-hildon-dialogs">
 435     <title>Migrating Hildon Dialogs</title>
 436
 437     <para>The substitution of a HildonDialog should be easy. Since version
 438     2.2, dialogs in Hildon should be used as normal GtkDialog objects.</para>
 439 </refsect1>
 440 </refentry>
 441
 442 <refentry id="hildon-migration-sort-dialogs" revision="13 Feb 2001">
 443 <refmeta>
 444 <refentrytitle>Sort Dialogs</refentrytitle>
 445 <manvolnum>3</manvolnum>
 446 <refmiscinfo>Hildon Library</refmiscinfo>
 447 </refmeta>
 448
 449 <refnamediv>
 450     <refname>Sort Dialogs</refname>
 451     <refpurpose>How to migrate Sort Dialogs</refpurpose>
 452 </refnamediv>
 453
 454 <refsect1 id="hildon-migrating-sort-dialogs">
 455     <title>Migrating Sort Dialogs</title>
 456
 457     <para>HildonSortDialog is deprecated since Hildon 2.2. The correct way
 458     to let the user sort contents is with menu filters.</para>
 459
 460     <para>The following example shows a typical NumberEditor.</para>
 461
 462     <example>
 463         <title>A Typical Number Editor</title>
 464         <programlisting>
 465 <![CDATA[
 466 GtkDialog *dialog = GTK_DIALOG (hildon_sort_dialog_new (NULL));
 467
 468 hildon_sort_dialog_add_sort_key (HILDON_SORT_DIALOG (dialog), "First key");
 469 hildon_sort_dialog_add_sort_key_reversed (HILDON_SORT_DIALOG (dialog), "Second, key");
 470 ]]>
 471         </programlisting>
 472     </example>
 473
 474     <para>The functionality of the example above is shown on the example
 475     bellow using by validating the HildonPickerButton's value every time
 476     it's changed. The choices given in the HildonTouchSelectorShould be
 477     the most common choices.</para>
 478
 479     <example>
 480         <title>A Replacement for the Number Editor</title>
 481         <programlisting>
 482 <![CDATA[
 483 GtkRadioButton *filter;
 484 GtkWidget *window = hildon_stackable_window_new ();
 485 gtk_window_set_title (GTK_WINDOW (window), "Sort Example");
 486
 487 HildonAppMenu *menu = HILDON_APP_MENU (hildon_app_menu_new ());
 488
 489 filter = GTK_RADIO_BUTTON (hildon_gtk_radio_button_new (
 490                                 HILDON_SIZE_THUMB_HEIGHT, NULL));
 491 gtk_button_set_label (GTK_BUTTON (filter), "1st Key");
 492 hildon_app_menu_add_filter (menu, GTK_BUTTON (filter));
 493 gtk_toggle_button_set_mode (GTK_TOGGLE_BUTTON (filter), FALSE);
 494 gtk_toggle_button_set_active (GTK_TOGGLE_BUTTON (filter), TRUE);
 495
 496 filter = GTK_RADIO_BUTTON (hildon_gtk_radio_button_new_from_widget (
 497                             HILDON_SIZE_FINGER_HEIGHT, filter));
 498 gtk_button_set_label (GTK_BUTTON (filter), "2nd Key");
 499 hildon_app_menu_add_filter (menu, GTK_BUTTON (filter));
 500 gtk_toggle_button_set_mode (GTK_TOGGLE_BUTTON (filter), FALSE);
 501
 502 filter = GTK_RADIO_BUTTON (hildon_gtk_radio_button_new (
 503                                 HILDON_SIZE_THUMB_HEIGHT, NULL));
 504 gtk_button_set_label (GTK_BUTTON (filter), "A-Z");
 505 hildon_app_menu_add_filter (menu, GTK_BUTTON (filter));
 506 gtk_toggle_button_set_mode (GTK_TOGGLE_BUTTON (filter), FALSE);
 507
 508 filter = GTK_RADIO_BUTTON (hildon_gtk_radio_button_new_from_widget (
 509                             HILDON_SIZE_FINGER_HEIGHT, filter));
 510 gtk_button_set_label (GTK_BUTTON (filter), "Z-A");
 511 hildon_app_menu_add_filter (menu, GTK_BUTTON (filter));
 512 gtk_toggle_button_set_mode (GTK_TOGGLE_BUTTON (filter), FALSE);
 513
 514 hildon_stackable_window_set_main_menu (HILDON_STACKABLE_WINDOW (window), menu);
 515 ]]>
 516         </programlisting>
 517     </example>
 518 </refsect1>
 519 </refentry>