git.maemo.org Git - hildon/blob - doc/tmpl/hildon-grid.sgml

   1 <!-- ##### SECTION Title ##### -->
   2 HildonGrid
   3
   4 <!-- ##### SECTION Short_Description ##### -->
   5 #HildonGrid is intended to be used where ever a number of single tap
   6 activatable items need to be presented (e.g. Control Panel applets).
   7
   8 <!-- ##### SECTION Long_Description ##### -->
   9 <para>
  10 HildonGrid is a set of application-defineable items that are presented in a
  11 table. The form of this table is selected from two modes; large icon mode and
  12 small icon mode.
  13
  14 In large icon mode, the Grid View items are presented with a large icon and a
  15 label underneath it. In small icon mode, the items are presented with a small
  16 icon and a label on the right side of the icon.
  17
  18 The label of an item is displayed within a band of colour displayed as a
  19 background colour as wide as the maximum text width. This allows the text to
  20 have focus as well as be legible when displayed upon a black or dark background
  21 image. Long names are truncated with an ellipsis ("...") appended.
  22 </para>
  23
  24 <para>
  25 <informalexample>
  26 Example:
  27 <programlisting>
  28 <!-- hildon-tests/wt/hildon-widgets-combo/testgrid.c -->
  29 ##include &lt;hildon-widgets/hildon-app.h&gt;
  30 ##include &lt;hildon-widgets/hildon-appview.h&gt;
  31 ##include &lt;hildon-widgets/hildon-grid.h&gt;
  32 ##include &lt;hildon-widgets/hildon-grid-item.h&gt;
  33 ##include &lt;gtk/gtk.h&gt;
  34 ##include &lt;pango/pango.h&gt;
  35 ##include &lt;libintl.h&gt;
  36 ##include &lt;locale.h&gt;
  37 ##include &lt;string.h&gt;
  38 ##include &lt;gtk/gtktoolbar.h&gt;
  39 ##include &lt;gtk/gtkwidget.h&gt;
  40
  41 ##ifdef HAVE_CONFIG_H
  42 ##include &lt;config.h&gt;
  43 ##endif
  44
  45 ##include &lt;stdio.h&gt;
  46 ##include &lt;stdlib.h&gt;
  47
  48 ##define _(String) gettext (String)
  49
  50 ##define ICONFILE    "Help"
  51
  52 enum {
  53         ACTIVATE,
  54         DISABLE_NEXT,
  55         EMBLEM_NEXT
  56 };
  57
  58 static int action = ACTIVATE;
  59
  60
  61 static GtkWidget    *w_add_one = NULL;
  62 static GtkWidget    *w_add_eight = NULL;
  63 static GtkWidget    *w_disable_next = NULL;
  64 static GtkWidget    *w_emblem_next = NULL;
  65
  66 static GtkWidget    *menu_small_icons;
  67 static GtkWidget    *menu_big_icons;
  68
  69 static GtkWidget    *standard_icons;
  70 static GtkWidget    *alt_empty_label;
  71 static GtkWidget    *dim_selected;
  72 static GtkWidget    *undim_all;
  73
  74
  75 GtkWidget *create_layout(void);
  76 static void activate (HildonGrid *grid, HildonGridItem *item, gpointer data);
  77 static void generate_name (char *target, size_t len);
  78 static void update_dim (HildonGrid *grid);
  79
  80 static void add_one (HildonGrid *grid);
  81 static void add_eight (HildonGrid *grid);
  82 static void disable_this (GtkWidget *widget);
  83 static void emblem_this (GtkWidget *widget);
  84
  85 static void create_basic_icons (HildonGrid *grid);
  86 static void remove_all_icons (HildonGrid *grid);
  87 static void show_standard_icons_signal (GtkMenuItem *widget, gpointer data);
  88 static void set_empty_label_signal (GtkMenuItem *widget, gpointer data);
  89 static void dim_selected_signal (GtkMenuItem *widget, gpointer data);
  90 static void undim_all_signal (GtkMenuItem *widget, gpointer data);
  91 static void set_icon_size (GtkMenuItem *item, gpointer data);
  92
  93 void _testGrid(GtkWidget *parent, gchar **help);
  94
  95 void
  96 _testGrid(GtkWidget *parent, gchar **help)
  97 {
  98
  99         GtkIconTheme *icon_theme;
 100         GtkWidget *grid;
 101         GtkWidget *popup;
 102         GtkMenu *menu;
 103         GSList *group = NULL;
 104
 105         icon_theme = gtk_icon_theme_get_default ();
 106
 107         grid = create_layout ();
 108         gtk_container_add (GTK_CONTAINER (parent), grid);
 109
 110         g_signal_connect (grid, "activate-child", G_CALLBACK (activate), NULL);
 111
 112         /* Create context menu. */
 113         popup = gtk_menu_new ();
 114         menu_small_icons = gtk_radio_menu_item_new_with_label (group,
 115                         _("Small icons"));
 116         menu_big_icons = gtk_radio_menu_item_new_with_label (
 117                         gtk_radio_menu_item_get_group (
 118                                 GTK_RADIO_MENU_ITEM (menu_small_icons)),
 119                         _("Big icons"));
 120         gtk_check_menu_item_set_active (GTK_CHECK_MENU_ITEM (menu_big_icons),
 121                         TRUE);
 122
 123         gtk_widget_show (menu_small_icons);
 124         gtk_widget_show (menu_big_icons);
 125         gtk_menu_shell_append (GTK_MENU_SHELL (popup), menu_small_icons);
 126         gtk_menu_shell_append (GTK_MENU_SHELL (popup), menu_big_icons);
 127         gtk_widget_tap_and_hold_setup (grid, popup, NULL, TRUE);
 128
 129         g_signal_connect (G_OBJECT (menu_small_icons), "activate",
 130                         G_CALLBACK (set_icon_size), HILDON_GRID (grid));
 131         g_signal_connect (G_OBJECT (menu_big_icons), "activate",
 132                         G_CALLBACK (set_icon_size), HILDON_GRID (grid));
 133
 134         /* Add menuitem for showing/hiding standard icons. */
 135         menu = hildon_appview_get_menu (HILDON_APPVIEW (
 136                                 gtk_widget_get_ancestor (parent, HILDON_TYPE_APPVIEW)));
 137         standard_icons = gtk_check_menu_item_new_with_label (
 138                         _("Show standard icons"));
 139         gtk_check_menu_item_set_active (GTK_CHECK_MENU_ITEM (standard_icons), TRUE);
 140         alt_empty_label = gtk_check_menu_item_new_with_label (
 141                         _("Alternative empty label"));
 142         gtk_check_menu_item_set_active (GTK_CHECK_MENU_ITEM (alt_empty_label),
 143                         FALSE);
 144
 145         dim_selected = gtk_menu_item_new_with_label (_("Dim current"));
 146         undim_all = gtk_menu_item_new_with_label (_("Undim all"));
 147
 148
 149         gtk_menu_shell_append (GTK_MENU_SHELL (menu), standard_icons);
 150         gtk_widget_show (standard_icons);
 151         gtk_menu_shell_append (GTK_MENU_SHELL (menu), alt_empty_label);
 152         gtk_widget_show (alt_empty_label);
 153         gtk_menu_shell_append (GTK_MENU_SHELL (menu), dim_selected);
 154         gtk_widget_show (dim_selected);
 155         gtk_menu_shell_append (GTK_MENU_SHELL (menu), undim_all);
 156         gtk_widget_show (undim_all);
 157
 158         g_signal_connect (G_OBJECT (standard_icons), "toggled",
 159                         G_CALLBACK (show_standard_icons_signal),
 160                         (gpointer) grid);
 161         g_signal_connect (G_OBJECT (alt_empty_label), "toggled",
 162                         G_CALLBACK (set_empty_label_signal),
 163                         (gpointer) grid);
 164         g_signal_connect (G_OBJECT (dim_selected), "activate",
 165                         G_CALLBACK (dim_selected_signal),
 166                         (gpointer) grid);
 167         g_signal_connect (G_OBJECT (undim_all), "activate",
 168                         G_CALLBACK (undim_all_signal),
 169                         (gpointer) grid);
 170
 171         create_basic_icons (HILDON_GRID (grid));
 172         update_dim (HILDON_GRID (grid));
 173
 174         hildon_grid_set_style (HILDON_GRID (grid), "bigicons");
 175         gtk_widget_show (GTK_WIDGET (grid));
 176
 177 }
 178
 179 static void
 180 show_standard_icons_signal (GtkMenuItem *widget,
 181                             gpointer    data)
 182 {
 183         HildonGrid *grid;
 184         grid = HILDON_GRID (data);
 185
 186         if (gtk_check_menu_item_get_active (GTK_CHECK_MENU_ITEM (widget)))
 187                 create_basic_icons (grid);
 188         else
 189                 remove_all_icons (grid);
 190
 191         update_dim (grid);
 192 }
 193
 194 static void
 195 set_empty_label_signal (GtkMenuItem *widget,
 196                         gpointer    data)
 197 {
 198         GValue val = {0, };
 199         HildonGrid *grid;
 200         grid = HILDON_GRID (data);
 201
 202         g_value_init (&amp;val, G_TYPE_STRING);
 203
 204         if (gtk_check_menu_item_get_active (GTK_CHECK_MENU_ITEM (widget)))
 205                 g_value_set_string (&amp;val, _("Alternative empty label here"));
 206         else
 207                 g_value_set_string (&amp;val, _("No icons"));
 208
 209         g_object_set_property (G_OBJECT (grid), "empty_label", &amp;val);
 210 }
 211
 212 static void
 213 create_basic_icons (HildonGrid *grid)
 214 {
 215         w_add_one = hildon_grid_item_new_with_label (
 216                         "Calendar", _("Add one"));
 217         w_add_eight = hildon_grid_item_new_with_label (
 218                         "Clock", _("Add eight"));
 219         w_disable_next = hildon_grid_item_new_with_label (
 220                         "Calculator", _("Disable next"));
 221         w_emblem_next = hildon_grid_item_new_with_label (
 222                         "Paint", _("Set emblem"));
 223         emblem_this (w_emblem_next);
 224
 225         gtk_container_add (GTK_CONTAINER (grid), w_add_one);
 226         gtk_container_add (GTK_CONTAINER (grid), w_add_eight);
 227         gtk_container_add (GTK_CONTAINER (grid), w_disable_next);
 228         gtk_container_add (GTK_CONTAINER (grid), w_emblem_next);
 229 }
 230
 231 static void
 232 remove_all_icons (HildonGrid *grid)
 233 {
 234         gtk_container_remove (GTK_CONTAINER (grid), w_add_one);
 235         gtk_container_remove (GTK_CONTAINER (grid), w_add_eight);
 236         gtk_container_remove (GTK_CONTAINER (grid), w_disable_next);
 237         gtk_container_remove (GTK_CONTAINER (grid), w_emblem_next);
 238 }
 239
 240 static void
 241 generate_name (gchar *target, size_t len)
 242 {
 243         int i;
 244         target[len] = '\0';
 245         for (i = 0; i &lt; len; i++)
 246                 target[i] = (rand() &amp; 0x0f) + 'a';
 247 }
 248
 249
 250 GtkWidget *
 251 create_layout (void)
 252 {
 253         GtkWidget *grid;
 254         grid = hildon_grid_new ();
 255         return GTK_WIDGET (grid);
 256 }
 257
 258 static void
 259 activate (HildonGrid *grid, HildonGridItem *item, gpointer data)
 260 {
 261         GtkWidget *widget;
 262         widget = GTK_WIDGET (item);
 263
 264         switch (action)
 265         {
 266                 case ACTIVATE:
 267                         if (widget == w_add_one)
 268                                 add_one (grid);
 269                         else if (widget == w_add_eight)
 270                                 add_eight (grid);
 271                         else if (widget == w_disable_next)
 272                                 action = DISABLE_NEXT;
 273                         else if (widget == w_emblem_next)
 274                                 action = EMBLEM_NEXT;
 275                         else
 276                         {
 277                                 gtk_container_remove (GTK_CONTAINER (grid), widget);
 278                                 update_dim (grid);
 279                         }
 280                         break;
 281
 282                 case DISABLE_NEXT:
 283                         disable_this (widget);
 284                         action = ACTIVATE;
 285                         break;
 286
 287                 case EMBLEM_NEXT:
 288                         emblem_this (widget);
 289                         action = ACTIVATE;
 290                         break;
 291         }
 292 }
 293
 294 static void
 295 add_one (HildonGrid *grid)
 296 {
 297 #define LABEL_WIDTH 64
 298         static gchar foo[LABEL_WIDTH];
 299         GtkWidget *t;
 300         generate_name (foo, rand () % (LABEL_WIDTH - 1) + 1);
 301         t = hildon_grid_item_new_with_label (ICONFILE, foo);
 302         gtk_container_add (GTK_CONTAINER (grid), t);
 303         gtk_widget_show (t);
 304
 305         update_dim (grid);
 306 }
 307
 308 static void
 309 add_eight (HildonGrid *grid)
 310 {
 311         int i;
 312         for (i = 0; i &lt; 8; i++)
 313                 add_one (grid);
 314 }
 315
 316 static void
 317 emblem_this (GtkWidget *widget)
 318 {
 319         const char *emblem;
 320         emblem = hildon_grid_item_get_emblem_type (HILDON_GRID_ITEM (widget));
 321
 322         hildon_grid_item_set_emblem_type (HILDON_GRID_ITEM (widget),
 323                         emblem == NULL ? "gnome-mime-image-png" : NULL);
 324 }
 325
 326 static void
 327 disable_this (GtkWidget *widget)
 328 {
 329         gtk_widget_set_sensitive (widget, FALSE);
 330 }
 331
 332 static void
 333 dim_selected_signal (GtkMenuItem    *widget,
 334                      gpointer       data)
 335 {
 336         GtkWidget *selected;
 337
 338         selected = GTK_CONTAINER (data)-&gt;focus_child;
 339         gtk_widget_set_sensitive (selected, FALSE);
 340 }
 341
 342 static void
 343 undim_all_signal (GtkMenuItem   *widget,
 344                   gpointer      data)
 345 {
 346         gtk_container_foreach (GTK_CONTAINER (data),
 347                         (GtkCallback) gtk_widget_set_sensitive,
 348                         (gpointer) TRUE);
 349 }
 350
 351 static void
 352 update_dim (HildonGrid *grid)
 353 {
 354         GtkWidget *selected;
 355         selected = GTK_CONTAINER (grid)-&gt;focus_child;
 356         gtk_widget_set_sensitive (dim_selected, selected != NULL);
 357 }
 358
 359 static void
 360 set_icon_size (GtkMenuItem *item, gpointer data)
 361 {
 362         HildonGrid *grid;
 363         grid = HILDON_GRID (data);
 364
 365         if (GTK_WIDGET (item) == menu_small_icons)
 366                 hildon_grid_set_style (grid, "smallicons");
 367         else if (GTK_WIDGET (item) == menu_big_icons)
 368                 hildon_grid_set_style (grid, "bigicons");
 369 }
 370 </programlisting>
 371 </informalexample>
 372 </para>
 373
 374 <!-- ##### SECTION See_Also ##### -->
 375 <para>
 376 #HildonGridItem
 377 </para>
 378
 379 <!-- ##### STRUCT HildonGrid ##### -->
 380 <para>
 381
 382 </para>
 383
 384
 385 <!-- ##### FUNCTION hildon_grid_new ##### -->
 386 <para>
 387
 388 </para>
 389
 390 @Returns:
 391
 392
 393 <!-- ##### FUNCTION hildon_grid_set_style ##### -->
 394 <para>
 395
 396 </para>
 397
 398 @grid:
 399 @style_name:
 400
 401
 402 <!-- ##### FUNCTION hildon_grid_get_style ##### -->
 403 <para>
 404
 405 </para>
 406
 407 @grid:
 408 @Returns:
 409
 410
 411 <!-- ##### FUNCTION hildon_grid_set_scrollbar_pos ##### -->
 412 <para>
 413
 414 </para>
 415
 416 @grid:
 417 @scrollbar_pos:
 418
 419
 420 <!-- ##### FUNCTION hildon_grid_get_scrollbar_pos ##### -->
 421 <para>
 422
 423 </para>
 424
 425 @grid:
 426 @Returns:
 427
 428
 429 <!-- ##### FUNCTION hildon_grid_activate_child ##### -->
 430 <para>
 431
 432 </para>
 433
 434 @grid:
 435 @item:
 436
 437
 438 <!-- ##### SIGNAL HildonGrid::activate-child ##### -->
 439 <para>
 440
 441 </para>
 442
 443 @hildongrid: the object which received the signal.
 444 @arg1:
 445
 446 <!-- ##### SIGNAL HildonGrid::popup-context-menu ##### -->
 447 <para>
 448
 449 </para>
 450
 451 @hildongrid: the object which received the signal.
 452 @arg1:
 453 @arg2:
 454 @arg3:
 455 @Returns:
 456
 457 <!-- ##### ARG HildonGrid:empty-label ##### -->
 458 <para>
 459
 460 </para>
 461
 462 <!-- ##### ARG HildonGrid:emblem-size ##### -->
 463 <para>
 464
 465 </para>
 466
 467 <!-- ##### ARG HildonGrid:icon-size ##### -->
 468 <para>
 469
 470 </para>
 471
 472 <!-- ##### ARG HildonGrid:item-height ##### -->
 473 <para>
 474
 475 </para>
 476
 477 <!-- ##### ARG HildonGrid:item-hspacing ##### -->
 478 <para>
 479
 480 </para>
 481
 482 <!-- ##### ARG HildonGrid:item-vspacing ##### -->
 483 <para>
 484
 485 </para>
 486
 487 <!-- ##### ARG HildonGrid:item-width ##### -->
 488 <para>
 489
 490 </para>
 491
 492 <!-- ##### ARG HildonGrid:label-height ##### -->
 493 <para>
 494
 495 </para>
 496
 497 <!-- ##### ARG HildonGrid:label-hspacing ##### -->
 498 <para>
 499
 500 </para>
 501
 502 <!-- ##### ARG HildonGrid:label-pos ##### -->
 503 <para>
 504
 505 </para>
 506
 507 <!-- ##### ARG HildonGrid:label-vspacing ##### -->
 508 <para>
 509
 510 </para>
 511
 512 <!-- ##### ARG HildonGrid:n-columns ##### -->
 513 <para>
 514
 515 </para>
 516