2 * This file is a part of hildon
4 * Copyright (C) 2007 Nokia Corporation, all rights reserved.
6 * Contact: Rodrigo Novo <rodrigo.novo@nokia.com>
7 * Author: Xan Lopez <xan.lopez@nokia.com>
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.
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.
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
28 * SECTION:hildon-bread-crumb-trail
29 * @short_description: Widget used to represent a specific path in a hierarchical tree.
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).
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.
39 * #HildonBreadCrumbTrail is deprecated since hildon 2.2. You should instead use
40 * #HildonStackableWindow to represent hierarchical structure in
44 #undef HILDON_DISABLE_DEPRECATED
46 #include <gdk/gdkkeysyms.h>
48 #include "hildon-marshalers.h"
49 #include "hildon-bread-crumb-trail.h"
50 #include "hildon-bread-crumb-widget.h"
52 #define HILDON_BREAD_CRUMB_TRAIL_GET_PRIVATE(obj) (G_TYPE_INSTANCE_GET_PRIVATE ((obj), HILDON_TYPE_BREAD_CRUMB_TRAIL, HildonBreadCrumbTrailPrivate))
54 struct _HildonBreadCrumbTrailPrivate
56 GtkWidget *back_button;
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,
81 static void hildon_bread_crumb_trail_forall (GtkContainer *container,
82 gboolean include_internals,
84 gpointer callback_data);
85 static void hildon_bread_crumb_trail_remove (GtkContainer *container,
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);
93 static gpointer get_bread_crumb_id (HildonBreadCrumb *item);
95 static guint bread_crumb_trail_signals[LAST_SIGNAL] = { 0 };
99 G_DEFINE_TYPE (HildonBreadCrumbTrail, hildon_bread_crumb_trail, GTK_TYPE_CONTAINER)
102 hildon_bread_crumb_trail_class_init (HildonBreadCrumbTrailClass *klass)
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;
110 /* GObject signals */
111 gobject_class->finalize = hildon_bread_crumb_trail_finalize;
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;
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;
122 /* HildonBreadCrumbTrail signals */
123 klass->move_parent = hildon_bread_crumb_trail_move_parent;
125 /* Style properties */
127 #define _BREAD_CRUMB_TRAIL_MINIMUM_WIDTH 10
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",
133 "The minimum width in characters the children widgets will request",
136 _BREAD_CRUMB_TRAIL_MINIMUM_WIDTH,
139 #define _BREAD_CRUMB_TRAIL_ARROW_SIZE 34
141 gtk_widget_class_install_style_property (widget_class,
142 g_param_spec_int ("arrow-size",
144 "Size of the back button arrow",
147 _BREAD_CRUMB_TRAIL_ARROW_SIZE,
150 bread_crumb_trail_signals[CRUMB_CLICKED] =
151 g_signal_new ("crumb-clicked",
152 G_OBJECT_CLASS_TYPE (object_class),
154 G_STRUCT_OFFSET (HildonBreadCrumbTrailClass, crumb_clicked),
155 g_signal_accumulator_true_handled, NULL,
156 _hildon_marshal_BOOLEAN__POINTER,
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),
166 g_cclosure_marshal_VOID__VOID,
172 binding_set = gtk_binding_set_by_class (widget_class);
174 gtk_binding_entry_add_signal (binding_set, GDK_Escape, 0,
176 gtk_binding_entry_add_signal (binding_set, GDK_BackSpace, 0,
180 g_type_class_add_private (gobject_class, sizeof (HildonBreadCrumbTrailPrivate));
184 hildon_bread_crumb_trail_finalize (GObject *object)
186 HildonBreadCrumbTrailPrivate *priv = HILDON_BREAD_CRUMB_TRAIL (object)->priv;
188 g_list_free (priv->item_list);
190 G_OBJECT_CLASS (hildon_bread_crumb_trail_parent_class)->finalize (object);
194 hildon_bread_crumb_trail_move_parent (HildonBreadCrumbTrail *bct)
196 if (g_list_length (bct->priv->item_list) > 1)
198 g_signal_emit_by_name (HILDON_BREAD_CRUMB (bct->priv->item_list->next->data),
204 hildon_bread_crumb_trail_size_request (GtkWidget *widget,
205 GtkRequisition *requisition)
208 GtkRequisition child_requisition;
209 HildonBreadCrumbTrail *bct;
210 HildonBreadCrumbTrailPrivate *priv;
211 gint minimum_width, width = 0;
215 bct= HILDON_BREAD_CRUMB_TRAIL (widget);
218 requisition->height = 0;
219 requisition->width = 0;
221 gtk_widget_size_request (priv->back_button, &child_requisition);
222 requisition->width = child_requisition.width;
223 requisition->height = child_requisition.height;
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,
233 tmp = g_strnfill ((gsize)minimum_width, 'm');
234 layout = gtk_widget_create_pango_layout (widget, tmp);
236 pango_layout_get_size (layout, &width, NULL);
237 requisition->width += PANGO_PIXELS (width);
238 g_object_unref (layout);
241 /* Button requisitions */
242 for (p = priv->item_list; p; p = p->next)
244 GtkWidget *child = GTK_WIDGET (p->data);
246 if (GTK_WIDGET_VISIBLE (child))
247 gtk_widget_size_request (child, &child_requisition);
251 requisition->width += GTK_CONTAINER (widget)->border_width * 2;
252 requisition->height += GTK_CONTAINER (widget)->border_width * 2;
254 widget->requisition = *requisition;
257 /* Document me please */
260 hildon_bread_crumb_trail_size_allocate (GtkWidget *widget,
261 GtkAllocation *allocation)
264 gint natural_width, natural_height;
265 HildonBreadCrumb *item;
266 GtkAllocation child_allocation;
267 GtkRequisition child_requisition;
269 gint allocation_width;
270 gint border_width, width;
272 GList *p, *first_show, *first_hide;
273 gint back_button_size;
274 HildonBreadCrumbTrailPrivate *priv = HILDON_BREAD_CRUMB_TRAIL (widget)->priv;
277 /* Get the rtl status */
278 rtl = (gtk_widget_get_direction (widget) == GTK_TEXT_DIR_RTL);
280 widget->allocation = *allocation;
282 border_width = (gint) GTK_CONTAINER (widget)->border_width;
283 allocation_width = allocation->width - 2 * border_width;
285 /* Allocate the back button */
287 child_allocation.x = allocation->width - border_width;
289 child_allocation.x = allocation->x + border_width;
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;
298 child_allocation.x -= back_button_size;
300 gtk_widget_size_allocate (priv->back_button, &child_allocation);
303 child_allocation.x += back_button_size;
305 /* If there are no buttons there's nothing else to do */
306 if (priv->item_list == NULL)
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) */
312 width = back_button_size;
318 for (p = priv->item_list; p; p = p->next)
320 item = HILDON_BREAD_CRUMB (p->data);
321 child = GTK_WIDGET (item);
323 /* Does the widget fit with its natural size? */
324 hildon_bread_crumb_get_natural_size (item,
328 if (width + natural_width <= allocation_width)
332 first_hide = p->next;
333 width += natural_width;
337 /* No, it doesn't. Allocate as much as possible
339 child_allocation.width = allocation_width - width;
341 gtk_widget_size_request (child, &req);
343 if (child_allocation.width > req.width)
345 first_hide = p->next;
346 gtk_widget_set_child_visible (child, TRUE);
349 child_allocation.x -= child_allocation.width;
351 gtk_widget_size_allocate (child, &child_allocation);
354 child_allocation.x += child_allocation.width;
358 extra_space = child_allocation.width;
365 /* Not enough items to fill the breadcrumb? */
366 if (p == NULL && width < allocation_width)
368 extra_space = allocation_width - width;
371 /* Allocate the other buttons */
372 for (p = first_show; p; p = p->prev)
374 item = HILDON_BREAD_CRUMB (p->data);
375 child = GTK_WIDGET (item);
377 /* Does the widget fit with its natural size? */
378 hildon_bread_crumb_get_natural_size (item,
382 /* If I'm the last and there's extra space, use it */
383 if (p->prev == NULL && extra_space != 0)
385 natural_width += extra_space;
388 child_allocation.width = natural_width;
389 gtk_widget_set_child_visible (child, TRUE);
392 child_allocation.x -= child_allocation.width;
394 gtk_widget_size_allocate (child, &child_allocation);
397 child_allocation.x += child_allocation.width;
400 for (p = first_hide; p; p = p->next)
402 item = HILDON_BREAD_CRUMB (p->data);
403 gtk_widget_set_child_visible (GTK_WIDGET (item), FALSE);
408 get_bread_crumb_id (HildonBreadCrumb *item)
410 return g_object_get_data (G_OBJECT (item), "bread-crumb-id");
414 crumb_activated_cb (GtkWidget *button,
415 HildonBreadCrumbTrail *bct)
417 gboolean signal_handled = FALSE;
419 g_signal_emit (bct, bread_crumb_trail_signals[CRUMB_CLICKED], 0,
420 get_bread_crumb_id (HILDON_BREAD_CRUMB (button)),
423 if (signal_handled == FALSE)
426 gboolean focus_last_item = FALSE;
427 HildonBreadCrumbTrailPrivate *priv;
431 child = GTK_WIDGET (priv->item_list->data);
433 /* We remove the tip of the list until we hit the clicked button */
434 while (child && child != button)
436 if (GTK_WIDGET_HAS_FOCUS (child))
437 focus_last_item = TRUE;
439 gtk_container_remove (GTK_CONTAINER (bct), child);
441 if (priv->item_list == NULL)
444 child = GTK_WIDGET (priv->item_list->data);
448 gtk_widget_grab_focus (GTK_WIDGET (bct->priv->item_list->data));
453 hildon_bread_crumb_trail_add (GtkContainer *container,
456 gtk_widget_set_parent (widget, GTK_WIDGET (container));
458 if (HILDON_IS_BREAD_CRUMB (widget))
460 HildonBreadCrumbTrail *bct = HILDON_BREAD_CRUMB_TRAIL (container);
462 g_signal_connect (G_OBJECT (widget), "crumb-activated",
463 G_CALLBACK (crumb_activated_cb), container);
465 bct->priv->item_list = g_list_prepend (bct->priv->item_list, widget);
467 hildon_bread_crumb_trail_update_back_button_sensitivity (bct);
472 hildon_bread_crumb_trail_forall (GtkContainer *container,
473 gboolean include_internals,
474 GtkCallback callback,
475 gpointer callback_data)
477 g_return_if_fail (callback != NULL);
478 g_return_if_fail (HILDON_IS_BREAD_CRUMB_TRAIL (container));
481 HildonBreadCrumbTrailPrivate *priv = HILDON_BREAD_CRUMB_TRAIL (container)->priv;
483 children = priv->item_list;
488 child = GTK_WIDGET (children->data);
489 children = children->next;
491 (*callback) (child, callback_data);
494 if (include_internals && priv->back_button)
496 (*callback) (priv->back_button, callback_data);
501 hildon_bread_crumb_trail_remove (GtkContainer *container,
505 HildonBreadCrumbTrailPrivate *priv;
506 gboolean was_visible = GTK_WIDGET_VISIBLE (widget);
508 priv = HILDON_BREAD_CRUMB_TRAIL (container)->priv;
516 if (widget == GTK_WIDGET (p->data))
518 g_signal_handlers_disconnect_by_func (widget, G_CALLBACK (crumb_activated_cb),
519 HILDON_BREAD_CRUMB_TRAIL (container));
520 gtk_widget_unparent (widget);
522 priv->item_list = g_list_delete_link (priv->item_list, p);
524 hildon_bread_crumb_trail_update_back_button_sensitivity (HILDON_BREAD_CRUMB_TRAIL (container));
528 gtk_widget_queue_resize (GTK_WIDGET (container));
537 hildon_bread_crumb_trail_update_back_button_sensitivity (HildonBreadCrumbTrail *bct)
540 HildonBreadCrumbTrailPrivate *priv = bct->priv;
542 list_length = g_list_length (priv->item_list);
544 if (list_length <= 1)
546 gtk_widget_set_sensitive (priv->back_button, FALSE);
550 gtk_widget_set_sensitive (priv->back_button, TRUE);
555 create_back_button (HildonBreadCrumbTrail *bct)
561 gtk_widget_push_composite_child ();
563 button = gtk_button_new ();
564 gtk_widget_set_name (button, "hildon-bread-crumb-back-button");
565 gtk_widget_set_sensitive (button, FALSE);
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,
572 gtk_widget_set_size_request (arrow, arrow_size, arrow_size);
574 gtk_container_add (GTK_CONTAINER (button), arrow);
575 gtk_container_add (GTK_CONTAINER (bct), button);
576 gtk_widget_show_all (button);
578 gtk_widget_pop_composite_child ();
584 hildon_bread_crumb_trail_init (HildonBreadCrumbTrail *bct)
586 HildonBreadCrumbTrailPrivate *priv = HILDON_BREAD_CRUMB_TRAIL_GET_PRIVATE (bct);
588 GTK_WIDGET_SET_FLAGS (bct, GTK_NO_WINDOW);
589 gtk_widget_set_redraw_on_allocate (GTK_WIDGET (bct), FALSE);
592 priv->item_list = NULL;
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),
601 hildon_bread_crumb_trail_scroll_back (GtkWidget *button,
602 HildonBreadCrumbTrail *bct)
604 hildon_bread_crumb_trail_move_parent (bct);
608 attach_bread_crumb (HildonBreadCrumbTrail *bct,
609 GtkWidget *bread_crumb,
611 GDestroyNotify destroy)
613 g_object_set_data_full (G_OBJECT (bread_crumb), "bread-crumb-id", id, destroy);
615 gtk_container_add (GTK_CONTAINER (bct), bread_crumb);
617 gtk_widget_show (bread_crumb);
623 * hildon_bread_crumb_trail_new:
625 * Creates a new #HildonBreadCrumbTrail widget.
627 * Returns: a #GtkWidget pointer of newly created bread crumb trail
630 * Stability: Unstable
634 hildon_bread_crumb_trail_new (void)
636 return GTK_WIDGET (g_object_new (HILDON_TYPE_BREAD_CRUMB_TRAIL, NULL));
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
646 * Adds a new bread crumb to the end of the trail.
648 * Stability: Unstable
652 hildon_bread_crumb_trail_push (HildonBreadCrumbTrail *bct,
653 HildonBreadCrumb *item,
655 GDestroyNotify destroy)
659 g_return_if_fail (HILDON_IS_BREAD_CRUMB_TRAIL (bct));
660 g_return_if_fail (HILDON_IS_BREAD_CRUMB (item));
662 widget = GTK_WIDGET (item);
664 attach_bread_crumb (bct, widget, id, destroy);
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
674 * Adds a new bread crumb to the end of the trail containing the specified text.
676 * Stability: Unstable
680 hildon_bread_crumb_trail_push_text (HildonBreadCrumbTrail *bct,
683 GDestroyNotify destroy)
687 g_return_if_fail (HILDON_IS_BREAD_CRUMB_TRAIL (bct));
688 g_return_if_fail (text != NULL);
690 widget = _hildon_bread_crumb_widget_new_with_text (text);
691 if (bct->priv->item_list == NULL)
693 g_object_set (G_OBJECT (widget), "show-separator", FALSE, NULL);
695 attach_bread_crumb (bct, widget, id, destroy);
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
706 * Adds a new bread crumb to the end of the trail containing the specified text and
709 * Stability: Unstable
713 hildon_bread_crumb_trail_push_icon (HildonBreadCrumbTrail *bct,
717 GDestroyNotify destroy)
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));
725 widget = _hildon_bread_crumb_widget_new_with_icon (icon, text);
726 if (bct->priv->item_list == NULL)
728 g_object_set (G_OBJECT (widget), "show-separator", FALSE, NULL);
730 attach_bread_crumb (bct, widget, id, destroy);
734 * hildon_bread_crumb_trail_pop:
735 * @bct: pointer to #HildonBreadCrumbTrail
737 * Removes the last bread crumb from the trail.
739 * Stability: Unstable
743 hildon_bread_crumb_trail_pop (HildonBreadCrumbTrail *bct)
746 HildonBreadCrumbTrailPrivate *priv;
748 g_return_if_fail (HILDON_IS_BREAD_CRUMB_TRAIL (bct));
752 if (priv->item_list == NULL)
757 child = GTK_WIDGET (priv->item_list->data);
758 gtk_container_remove (GTK_CONTAINER (bct), child);
761 hildon_bread_crumb_trail_update_back_button_sensitivity (bct);
765 * hildon_bread_crumb_trail_clear:
766 * @bct: pointer to #HildonBreadCrumbTrail
768 * Removes all the bread crumbs from the bread crumb trail.
770 * Stability: Unstable
774 hildon_bread_crumb_trail_clear (HildonBreadCrumbTrail *bct)
776 HildonBreadCrumbTrailPrivate *priv;
778 g_return_if_fail (HILDON_IS_BREAD_CRUMB_TRAIL (bct));
782 while (priv->item_list)
784 hildon_bread_crumb_trail_pop (bct);
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
793 gtk_widget_hide (priv->back_button);
794 gtk_widget_show (priv->back_button);