vcs.maemo.org Git - hildon/blob - src/hildon-bread-crumb-trail.c

   1 /*
   2  * This file is a part of hildon
   3  *
   4  * Copyright (C) 2007 Nokia Corporation, all rights reserved.
   5  *
   6  * Contact: Michael Dominic Kostrzewa <michael.kostrzewa@nokia.com>
   7  * Author: Xan Lopez <xan.lopez@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 /**
  28  * SECTION:hildon-bread-crumb-trail
  29  * @short_description: Widget used to represent a specific path in a hierarchical tree.
  30  * Stability: Unstable
  31  *
  32  * HildonBreadCrumbTrail is a GTK widget used to represent the currently active path in
  33  * some kind of hierarchical structure (file system, media library, structured document, etc).
  34  *
  35  * It has built-in support for text and icon bread crumbs, but the trail only requires a very
  36  * simple interface to be implemented for its children and thus new types of items can be
  37  * implemented if needed. See #HildonBreadCrumb for more details.
  38  */
  39
  40 #include <gdk/gdkkeysyms.h>
  41
  42 #include "hildon-marshalers.h"
  43 #include "hildon-bread-crumb-trail.h"
  44 #include "hildon-bread-crumb-widget.h"
  45
  46 #define HILDON_BREAD_CRUMB_TRAIL_GET_PRIVATE(obj) (G_TYPE_INSTANCE_GET_PRIVATE ((obj), HILDON_TYPE_BREAD_CRUMB_TRAIL, HildonBreadCrumbTrailPrivate))
  47
  48 struct _HildonBreadCrumbTrailPrivate
  49 {
  50   GtkWidget *back_button;
  51   GList *item_list;
  52   GtkWidget *arrow;
  53 };
  54
  55 /* Signals */
  56
  57 enum {
  58   CRUMB_CLICKED,
  59   MOVE_PARENT,
  60   LAST_SIGNAL
  61 };
  62
  63 /* Properties */
  64
  65 enum {
  66   PROP_0
  67 };
  68
  69 static void hildon_bread_crumb_trail_size_request (GtkWidget *widget,
  70                                                    GtkRequisition *requisition);
  71 static void hildon_bread_crumb_trail_size_allocate (GtkWidget *widget,
  72                                                     GtkAllocation *allocation);
  73 static void hildon_bread_crumb_trail_add (GtkContainer *container,
  74                                           GtkWidget *widget);
  75 static void hildon_bread_crumb_trail_forall (GtkContainer *container,
  76                                              gboolean include_internals,
  77                                              GtkCallback callback,
  78                                              gpointer callback_data);
  79 static void hildon_bread_crumb_trail_remove (GtkContainer *container,
  80                                              GtkWidget *widget);
  81 static void hildon_bread_crumb_trail_finalize (GObject *object);
  82 static void hildon_bread_crumb_trail_scroll_back (GtkWidget *button,
  83                                                   HildonBreadCrumbTrail *bct);
  84 static void hildon_bread_crumb_trail_update_back_button_sensitivity (HildonBreadCrumbTrail *bct);
  85 static void hildon_bread_crumb_trail_move_parent (HildonBreadCrumbTrail *bct);
  86
  87 static gpointer get_bread_crumb_id (HildonBreadCrumb *item);
  88
  89 static guint bread_crumb_trail_signals[LAST_SIGNAL] = { 0 };
  90
  91 /* GType methods */
  92
  93 G_DEFINE_TYPE (HildonBreadCrumbTrail, hildon_bread_crumb_trail, GTK_TYPE_CONTAINER)
  94
  95 static void
  96 hildon_bread_crumb_trail_class_init (HildonBreadCrumbTrailClass *klass)
  97 {
  98   GObjectClass *gobject_class = (GObjectClass*)klass;
  99   GtkObjectClass *object_class = (GtkObjectClass*)klass;
 100   GtkWidgetClass *widget_class = (GtkWidgetClass*)klass;
 101   GtkContainerClass *container_class = (GtkContainerClass*)klass;
 102   GtkBindingSet *binding_set;
 103
 104   /* GObject signals */
 105   gobject_class->finalize = hildon_bread_crumb_trail_finalize;
 106
 107   /* GtkWidget signals */
 108   widget_class->size_request = hildon_bread_crumb_trail_size_request;
 109   widget_class->size_allocate = hildon_bread_crumb_trail_size_allocate;
 110
 111   /* GtkContainer signals */
 112   container_class->add = hildon_bread_crumb_trail_add;
 113   container_class->forall = hildon_bread_crumb_trail_forall;
 114   container_class->remove = hildon_bread_crumb_trail_remove;
 115
 116   /* HildonBreadCrumbTrail signals */
 117   klass->move_parent = hildon_bread_crumb_trail_move_parent;
 118
 119   /* Style properties */
 120
 121 #define _BREAD_CRUMB_TRAIL_MINIMUM_WIDTH 10
 122
 123   /* FIXME: is this the best way to do it? */
 124   gtk_widget_class_install_style_property (widget_class,
 125                                            g_param_spec_int ("minimum-width",
 126                                                              "Minimum width",
 127                                                              "The minimum width in characters the children widgets will request",
 128                                                              0,
 129                                                              G_MAXINT,
 130                                                              _BREAD_CRUMB_TRAIL_MINIMUM_WIDTH,
 131                                                              G_PARAM_READABLE));
 132
 133 #define _BREAD_CRUMB_TRAIL_ARROW_SIZE 34
 134
 135   gtk_widget_class_install_style_property (widget_class,
 136                                            g_param_spec_int ("arrow-size",
 137                                                              "Arrow size",
 138                                                              "Size of the back button arrow",
 139                                                              0,
 140                                                              G_MAXINT,
 141                                                              _BREAD_CRUMB_TRAIL_ARROW_SIZE,
 142                                                              G_PARAM_READABLE));
 143   /* Signals */
 144   bread_crumb_trail_signals[CRUMB_CLICKED] =
 145     g_signal_new ("crumb-clicked",
 146                   G_OBJECT_CLASS_TYPE (object_class),
 147                   G_SIGNAL_RUN_LAST,
 148                   G_STRUCT_OFFSET (HildonBreadCrumbTrailClass, crumb_clicked),
 149                   g_signal_accumulator_true_handled, NULL,
 150                   _hildon_marshal_BOOLEAN__POINTER,
 151                   G_TYPE_BOOLEAN, 1,
 152                   G_TYPE_POINTER);
 153
 154   bread_crumb_trail_signals[MOVE_PARENT] =
 155     g_signal_new ("move-parent",
 156                   G_OBJECT_CLASS_TYPE (object_class),
 157                   G_SIGNAL_RUN_LAST | G_SIGNAL_ACTION,
 158                   G_STRUCT_OFFSET (HildonBreadCrumbTrailClass, move_parent),
 159                   NULL, NULL,
 160                   g_cclosure_marshal_VOID__VOID,
 161                   G_TYPE_NONE,
 162                   0);
 163
 164
 165   /* Binding set */
 166   binding_set = gtk_binding_set_by_class (widget_class);
 167
 168   gtk_binding_entry_add_signal (binding_set, GDK_Escape, 0,
 169                                 "move-parent", 0);
 170   gtk_binding_entry_add_signal (binding_set, GDK_BackSpace, 0,
 171                                 "move-parent", 0);
 172
 173   /* Private data */
 174   g_type_class_add_private (gobject_class, sizeof (HildonBreadCrumbTrailPrivate));
 175 }
 176
 177 static void
 178 hildon_bread_crumb_trail_finalize (GObject *object)
 179 {
 180   HildonBreadCrumbTrailPrivate *priv = HILDON_BREAD_CRUMB_TRAIL (object)->priv;
 181
 182   g_list_free (priv->item_list);
 183
 184   G_OBJECT_CLASS (hildon_bread_crumb_trail_parent_class)->finalize (object);
 185 }
 186
 187 static void
 188 hildon_bread_crumb_trail_move_parent (HildonBreadCrumbTrail *bct)
 189 {
 190   if (g_list_length (bct->priv->item_list) > 1)
 191     {
 192       g_signal_emit_by_name (HILDON_BREAD_CRUMB (bct->priv->item_list->next->data),
 193                              "crumb-activated");
 194     }
 195 }
 196
 197 static void
 198 hildon_bread_crumb_trail_size_request (GtkWidget *widget,
 199                                        GtkRequisition *requisition)
 200 {
 201   GList *p;
 202   GtkRequisition child_requisition;
 203   HildonBreadCrumbTrail *bct;
 204   HildonBreadCrumbTrailPrivate *priv;
 205   gint minimum_width, width = 0;
 206   PangoLayout *layout;
 207   gchar *tmp = NULL;
 208
 209   bct= HILDON_BREAD_CRUMB_TRAIL (widget);
 210   priv = bct->priv;
 211
 212   requisition->height = 0;
 213   requisition->width = 0;
 214
 215   gtk_widget_size_request (priv->back_button, &child_requisition);
 216   requisition->width = child_requisition.width;
 217   requisition->height = child_requisition.height;
 218
 219   if (priv->item_list)
 220     {
 221       /* Add minimum width for one item */
 222       /* TODO: this can be probably cached */
 223       gtk_widget_style_get (widget,
 224                             "minimum-width", &minimum_width,
 225                             NULL);
 226
 227       tmp = g_strnfill ((gsize)minimum_width, 'm');
 228       layout = gtk_widget_create_pango_layout (widget, tmp);
 229       g_free (tmp);
 230       pango_layout_get_size (layout, &width, NULL);
 231       requisition->width += PANGO_PIXELS (width);
 232       g_object_unref (layout);
 233     }
 234
 235   /* Button requisitions */
 236   for (p = priv->item_list; p; p = p->next)
 237     {
 238       GtkWidget *child = GTK_WIDGET (p->data);
 239
 240       if (GTK_WIDGET_VISIBLE (child))
 241         gtk_widget_size_request (child, &child_requisition);
 242     }
 243
 244   /* Border width */
 245   requisition->width += GTK_CONTAINER (widget)->border_width * 2;
 246   requisition->height += GTK_CONTAINER (widget)->border_width * 2;
 247
 248   widget->requisition = *requisition;
 249 }
 250
 251 /* Document me please */
 252
 253 static void
 254 hildon_bread_crumb_trail_size_allocate (GtkWidget *widget,
 255                                         GtkAllocation *allocation)
 256 {
 257   GtkRequisition req;
 258   gint natural_width, natural_height;
 259   HildonBreadCrumb *item;
 260   GtkAllocation child_allocation;
 261   GtkRequisition child_requisition;
 262   GtkWidget *child;
 263   gint allocation_width;
 264   gint border_width, width;
 265   gint extra_space;
 266   GList *p, *first_show, *first_hide;
 267   gint back_button_size;
 268   HildonBreadCrumbTrailPrivate *priv = HILDON_BREAD_CRUMB_TRAIL (widget)->priv;
 269   gboolean rtl;
 270
 271   /* Get the rtl status */
 272   rtl = (gtk_widget_get_direction (widget) == GTK_TEXT_DIR_RTL);
 273
 274   widget->allocation = *allocation;
 275
 276   border_width = (gint) GTK_CONTAINER (widget)->border_width;
 277   allocation_width = allocation->width - 2 * border_width;
 278
 279   /* Allocate the back button */
 280   if (rtl)
 281     child_allocation.x = allocation->width - border_width;
 282   else
 283     child_allocation.x = allocation->x + border_width;
 284
 285   child_allocation.y = allocation->y + border_width;
 286   gtk_widget_get_child_requisition (priv->back_button, &child_requisition);
 287   /* We want the back button to be a square */
 288   back_button_size = MAX (child_requisition.width, child_requisition.height);
 289   child_allocation.width = child_allocation.height = back_button_size;
 290
 291   if (rtl)
 292     child_allocation.x -= back_button_size;
 293
 294   gtk_widget_size_allocate (priv->back_button, &child_allocation);
 295
 296   if (!rtl)
 297     child_allocation.x += back_button_size;
 298
 299   /* If there are no buttons there's nothing else to do */
 300   if (priv->item_list == NULL)
 301     return;
 302
 303   /* We find out how many buttons can we show, starting from the
 304      the last one in the logical path (the first item in the list) */
 305
 306   width = back_button_size;
 307   p = priv->item_list;
 308   first_show = NULL;
 309   first_hide = NULL;
 310   extra_space = 0;
 311
 312   for (p = priv->item_list; p; p = p->next)
 313     {
 314       item = HILDON_BREAD_CRUMB (p->data);
 315       child = GTK_WIDGET (item);
 316
 317       /* Does the widget fit with its natural size? */
 318       hildon_bread_crumb_get_natural_size (item,
 319                                            &natural_width,
 320                                            &natural_height);
 321
 322       if (width + natural_width <= allocation_width)
 323         {
 324           /* Yes, it does */
 325           first_show = p;
 326           first_hide = p->next;
 327           width += natural_width;
 328         }
 329       else
 330         {
 331           /* No, it doesn't. Allocate as much as possible
 332              and stop */
 333           child_allocation.width = allocation_width - width;
 334
 335           gtk_widget_size_request (child, &req);
 336
 337           if (child_allocation.width > req.width)
 338             {
 339               first_hide = p->next;
 340               gtk_widget_set_child_visible (child, TRUE);
 341
 342               if (rtl)
 343                 child_allocation.x -= child_allocation.width;
 344
 345               gtk_widget_size_allocate (child, &child_allocation);
 346
 347               if (!rtl)
 348                 child_allocation.x += child_allocation.width;
 349             }
 350           else
 351             {
 352               extra_space = child_allocation.width;
 353             }
 354
 355           break;
 356         }
 357     }
 358
 359   /* Not enough items to fill the breadcrumb? */
 360   if (p == NULL && width < allocation_width)
 361     {
 362       extra_space = allocation_width - width;
 363     }
 364
 365   /* Allocate the other buttons */
 366   for (p = first_show; p; p = p->prev)
 367     {
 368       item = HILDON_BREAD_CRUMB (p->data);
 369       child = GTK_WIDGET (item);
 370
 371       /* Does the widget fit with its natural size? */
 372       hildon_bread_crumb_get_natural_size (item,
 373                                            &natural_width,
 374                                            &natural_height);
 375
 376       /* If I'm the last and there's extra space, use it */
 377       if (p->prev == NULL && extra_space != 0)
 378         {
 379           natural_width += extra_space;
 380         }
 381
 382       child_allocation.width = natural_width;
 383       gtk_widget_set_child_visible (child, TRUE);
 384
 385       if (rtl)
 386         child_allocation.x -= child_allocation.width;
 387
 388       gtk_widget_size_allocate (child, &child_allocation);
 389
 390       if (!rtl)
 391         child_allocation.x += child_allocation.width;
 392     }
 393
 394   for (p = first_hide; p; p = p->next)
 395     {
 396       item = HILDON_BREAD_CRUMB (p->data);
 397       child = GTK_WIDGET (item);
 398
 399       gtk_widget_set_child_visible (GTK_WIDGET (item), FALSE);
 400     }
 401 }
 402
 403 static gpointer
 404 get_bread_crumb_id (HildonBreadCrumb *item)
 405 {
 406   return g_object_get_data (G_OBJECT (item), "bread-crumb-id");
 407 }
 408
 409 static void
 410 crumb_activated_cb (GtkWidget *button,
 411                     HildonBreadCrumbTrail *bct)
 412 {
 413   gboolean signal_handled = FALSE;
 414
 415   g_signal_emit (bct, bread_crumb_trail_signals[CRUMB_CLICKED], 0,
 416                  get_bread_crumb_id (HILDON_BREAD_CRUMB (button)),
 417                  &signal_handled);
 418
 419   if (signal_handled == FALSE)
 420     {
 421       GtkWidget *child;
 422       gboolean focus_last_item = FALSE;
 423       HildonBreadCrumbTrailPrivate *priv;
 424
 425       priv = bct->priv;
 426
 427       child = GTK_WIDGET (priv->item_list->data);
 428
 429       /* We remove the tip of the list until we hit the clicked button */
 430       while (child && child != button)
 431         {
 432           if (GTK_WIDGET_HAS_FOCUS (child))
 433             focus_last_item = TRUE;
 434
 435           gtk_container_remove (GTK_CONTAINER (bct), child);
 436
 437           if (priv->item_list == NULL)
 438               return;
 439
 440           child = GTK_WIDGET (priv->item_list->data);
 441         }
 442
 443       if (focus_last_item)
 444         gtk_widget_grab_focus (GTK_WIDGET (bct->priv->item_list->data));
 445     }
 446 }
 447
 448 static void
 449 hildon_bread_crumb_trail_add (GtkContainer *container,
 450                               GtkWidget *widget)
 451 {
 452   gtk_widget_set_parent (widget, GTK_WIDGET (container));
 453
 454   if (HILDON_IS_BREAD_CRUMB (widget))
 455     {
 456       HildonBreadCrumbTrail *bct = HILDON_BREAD_CRUMB_TRAIL (container);
 457
 458       g_signal_connect (G_OBJECT (widget), "crumb-activated",
 459                         G_CALLBACK (crumb_activated_cb), container);
 460
 461       bct->priv->item_list = g_list_prepend (bct->priv->item_list, widget);
 462
 463       hildon_bread_crumb_trail_update_back_button_sensitivity (bct);
 464     }
 465 }
 466
 467 static void
 468 hildon_bread_crumb_trail_forall (GtkContainer *container,
 469                                  gboolean include_internals,
 470                                  GtkCallback callback,
 471                                  gpointer callback_data)
 472 {
 473   g_return_if_fail (callback != NULL);
 474   g_return_if_fail (HILDON_IS_BREAD_CRUMB_TRAIL (container));
 475
 476   GList *children;
 477   HildonBreadCrumbTrailPrivate *priv = HILDON_BREAD_CRUMB_TRAIL (container)->priv;
 478
 479   children = priv->item_list;
 480
 481   while (children)
 482     {
 483       GtkWidget *child;
 484       child = GTK_WIDGET (children->data);
 485       children = children->next;
 486
 487       (*callback) (child, callback_data);
 488     }
 489
 490   if (include_internals && priv->back_button)
 491     {
 492       (*callback) (priv->back_button, callback_data);
 493     }
 494 }
 495
 496 static void
 497 hildon_bread_crumb_trail_remove (GtkContainer *container,
 498                                  GtkWidget *widget)
 499 {
 500   GList *p, *next;
 501   HildonBreadCrumbTrailPrivate *priv;
 502   gboolean was_visible = GTK_WIDGET_VISIBLE (widget);
 503
 504   priv = HILDON_BREAD_CRUMB_TRAIL (container)->priv;
 505
 506   p = priv->item_list;
 507
 508   while (p)
 509     {
 510       next = p->next;
 511
 512       if (widget == GTK_WIDGET (p->data))
 513         {
 514           g_signal_handlers_disconnect_by_func (widget, G_CALLBACK (crumb_activated_cb),
 515                                                 HILDON_BREAD_CRUMB_TRAIL (container));
 516           gtk_widget_unparent (widget);
 517
 518           priv->item_list = g_list_delete_link (priv->item_list, p);
 519
 520           hildon_bread_crumb_trail_update_back_button_sensitivity (HILDON_BREAD_CRUMB_TRAIL (container));
 521
 522           if (was_visible)
 523             {
 524               gtk_widget_queue_resize (GTK_WIDGET (container));
 525             }
 526         }
 527
 528       p = next;
 529     }
 530 }
 531
 532 static void
 533 hildon_bread_crumb_trail_update_back_button_sensitivity (HildonBreadCrumbTrail *bct)
 534 {
 535   guint list_length;
 536   HildonBreadCrumbTrailPrivate *priv = bct->priv;
 537
 538   list_length = g_list_length (priv->item_list);
 539
 540   if (list_length <= 1)
 541     {
 542       gtk_widget_set_sensitive (priv->back_button, FALSE);
 543     }
 544   else
 545     {
 546       gtk_widget_set_sensitive (priv->back_button, TRUE);
 547     }
 548 }
 549
 550 static GtkWidget*
 551 create_back_button (HildonBreadCrumbTrail *bct)
 552 {
 553   GtkWidget *button;
 554   GtkWidget *arrow;
 555   gint arrow_size;
 556
 557   gtk_widget_push_composite_child ();
 558
 559   button = gtk_button_new ();
 560   gtk_widget_set_name (button, "hildon-bread-crumb-back-button");
 561   gtk_widget_set_sensitive (button, FALSE);
 562
 563   arrow = gtk_arrow_new (GTK_ARROW_LEFT, GTK_SHADOW_NONE);
 564   bct->priv->arrow = arrow;
 565   gtk_widget_style_get (GTK_WIDGET (bct),
 566                         "arrow-size", &arrow_size,
 567                         NULL);
 568   gtk_widget_set_size_request (arrow, arrow_size, arrow_size);
 569
 570   gtk_container_add (GTK_CONTAINER (button), arrow);
 571   gtk_container_add (GTK_CONTAINER (bct), button);
 572   gtk_widget_show_all (button);
 573
 574   gtk_widget_pop_composite_child ();
 575
 576   return button;
 577 }
 578
 579 static void
 580 hildon_bread_crumb_trail_init (HildonBreadCrumbTrail *bct)
 581 {
 582   HildonBreadCrumbTrailPrivate *priv = HILDON_BREAD_CRUMB_TRAIL_GET_PRIVATE (bct);
 583
 584   GTK_WIDGET_SET_FLAGS (bct, GTK_NO_WINDOW);
 585   gtk_widget_set_redraw_on_allocate (GTK_WIDGET (bct), FALSE);
 586
 587   bct->priv = priv;
 588   priv->item_list = NULL;
 589
 590   priv->back_button = create_back_button (bct);
 591   g_signal_connect (priv->back_button, "clicked",
 592                     G_CALLBACK (hildon_bread_crumb_trail_scroll_back),
 593                     bct);
 594 }
 595
 596 static void
 597 hildon_bread_crumb_trail_scroll_back (GtkWidget *button,
 598                                       HildonBreadCrumbTrail *bct)
 599 {
 600   hildon_bread_crumb_trail_move_parent (bct);
 601 }
 602
 603 static void
 604 attach_bread_crumb (HildonBreadCrumbTrail *bct,
 605                     GtkWidget *bread_crumb,
 606                     gpointer id,
 607                     GDestroyNotify destroy)
 608 {
 609   g_object_set_data_full (G_OBJECT (bread_crumb), "bread-crumb-id", id, destroy);
 610
 611   gtk_container_add (GTK_CONTAINER (bct), bread_crumb);
 612
 613   gtk_widget_show (bread_crumb);
 614 }
 615
 616 /* PUBLIC API */
 617
 618 /**
 619  * hildon_bread_crumb_trail_new:
 620  *
 621  * Creates a new #HildonBreadCrumbTrail widget.
 622  *
 623  * Returns: a #GtkWidget pointer of newly created bread crumb trail
 624  * widget
 625  *
 626  * Stability: Unstable
 627  */
 628
 629 GtkWidget*
 630 hildon_bread_crumb_trail_new (void)
 631 {
 632   return GTK_WIDGET (g_object_new (HILDON_TYPE_BREAD_CRUMB_TRAIL, NULL));
 633 }
 634
 635 /**
 636  * hildon_bread_crumb_trail_push:
 637  * @bct: pointer to #HildonBreadCrumbTrail
 638  * @item: the #HildonBreadCrumb to be added to the trail
 639  * @id: optional id for the bread crumb
 640  * @destroy: GDestroyNotify callback to be called when the bread crumb is destroyed
 641  *
 642  * Adds a new bread crumb to the end of the trail.
 643  *
 644  * Stability: Unstable
 645  */
 646
 647 void
 648 hildon_bread_crumb_trail_push (HildonBreadCrumbTrail *bct,
 649                                HildonBreadCrumb *item,
 650                                gpointer id,
 651                                GDestroyNotify destroy)
 652 {
 653   GtkWidget *widget;
 654
 655   g_return_if_fail (HILDON_IS_BREAD_CRUMB_TRAIL (bct));
 656   g_return_if_fail (HILDON_IS_BREAD_CRUMB (item));
 657
 658   widget = GTK_WIDGET (item);
 659
 660   attach_bread_crumb (bct, widget, id, destroy);
 661 }
 662
 663 /**
 664  * hildon_bread_crumb_trail_push_text:
 665  * @bct: pointer to #HildonBreadCrumbTrail
 666  * @text: content of the new bread crumb
 667  * @id: optional id for the bread crumb
 668  * @destroy: GDestroyNotify callback to be called when the bread crumb is destroyed
 669  *
 670  * Adds a new bread crumb to the end of the trail containing the specified text.
 671  *
 672  * Stability: Unstable
 673  */
 674
 675 void
 676 hildon_bread_crumb_trail_push_text (HildonBreadCrumbTrail *bct,
 677                                     const gchar *text,
 678                                     gpointer id,
 679                                     GDestroyNotify destroy)
 680 {
 681   GtkWidget *widget;
 682
 683   g_return_if_fail (HILDON_IS_BREAD_CRUMB_TRAIL (bct));
 684   g_return_if_fail (text != NULL);
 685
 686   widget = _hildon_bread_crumb_widget_new_with_text (text);
 687   if (bct->priv->item_list == NULL)
 688     {
 689       g_object_set (G_OBJECT (widget), "show-separator", FALSE, NULL);
 690     }
 691   attach_bread_crumb (bct, widget, id, destroy);
 692 }
 693
 694 /**
 695  * hildon_bread_crumb_trail_push_icon:
 696  * @bct: pointer to #HildonBreadCrumbTrail
 697  * @text: content of the new bread crumb
 698  * @icon: a widget to set as the icon in the bread crumb
 699  * @id: optional id for the bread crumb
 700  * @destroy: GDestroyNotify callback to be called when the bread crumb is destroyed
 701  *
 702  * Adds a new bread crumb to the end of the trail containing the specified text and
 703  * icon.
 704  *
 705  * Stability: Unstable
 706  */
 707
 708 void
 709 hildon_bread_crumb_trail_push_icon (HildonBreadCrumbTrail *bct,
 710                                     const gchar *text,
 711                                     GtkWidget *icon,
 712                                     gpointer id,
 713                                     GDestroyNotify destroy)
 714 {
 715   GtkWidget *widget;
 716
 717   g_return_if_fail (HILDON_IS_BREAD_CRUMB_TRAIL (bct));
 718   g_return_if_fail (text != NULL);
 719   g_return_if_fail (GTK_IS_WIDGET (icon));
 720
 721   widget = _hildon_bread_crumb_widget_new_with_icon (icon, text);
 722   if (bct->priv->item_list == NULL)
 723     {
 724       g_object_set (G_OBJECT (widget), "show-separator", FALSE, NULL);
 725     }
 726   attach_bread_crumb (bct, widget, id, destroy);
 727 }
 728
 729 /**
 730  * hildon_bread_crumb_trail_pop:
 731  * @bct: pointer to #HildonBreadCrumbTrail
 732  *
 733  * Removes the last bread crumb from the trail.
 734  *
 735  * Stability: Unstable
 736  */
 737
 738 void
 739 hildon_bread_crumb_trail_pop (HildonBreadCrumbTrail *bct)
 740 {
 741   GtkWidget *child;
 742   HildonBreadCrumbTrailPrivate *priv;
 743
 744   g_return_if_fail (HILDON_IS_BREAD_CRUMB_TRAIL (bct));
 745
 746   priv = bct->priv;
 747
 748   if (priv->item_list == NULL)
 749     return;
 750
 751   if (priv->item_list)
 752     {
 753       child = GTK_WIDGET (priv->item_list->data);
 754       gtk_container_remove (GTK_CONTAINER (bct), child);
 755     }
 756
 757   hildon_bread_crumb_trail_update_back_button_sensitivity (bct);
 758 }
 759
 760 /**
 761  * hildon_bread_crumb_trail_clear:
 762  * @bct: pointer to #HildonBreadCrumbTrail
 763  *
 764  * Removes all the bread crumbs from the bread crumb trail.
 765  *
 766  * Stability: Unstable
 767  */
 768
 769 void
 770 hildon_bread_crumb_trail_clear (HildonBreadCrumbTrail *bct)
 771 {
 772   HildonBreadCrumbTrailPrivate *priv;
 773
 774   g_return_if_fail (HILDON_IS_BREAD_CRUMB_TRAIL (bct));
 775
 776   priv = bct->priv;
 777
 778   while (priv->item_list)
 779     {
 780       hildon_bread_crumb_trail_pop (bct);
 781     }
 782
 783   /*
 784     Sensitivity hack from hell. We need to do this while
 785      http://bugzilla.gnome.org/show_bug.cgi?id=56070 is not
 786      fixed to allow repeated clicking on the back button if
 787      someone clears and rebuilds the trail when it's clicked
 788   */
 789   gtk_widget_hide (priv->back_button);
 790   gtk_widget_show (priv->back_button);
 791 }