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