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