2 * This file is a part of hildon
4 * Copyright (C) 2005, 2006 Nokia Corporation, all rights reserved.
6 * Contact: Rodrigo Novo <rodrigo.novo@nokia.com>
8 * This library is free software; you can redistribute it and/or
9 * modify it under the terms of the GNU Lesser General Public License
10 * as published by the Free Software Foundation; version 2.1 of
11 * the License, or (at your option) any later version.
13 * This library is distributed in the hope that it will be useful, but
14 * WITHOUT ANY WARRANTY; without even the implied warranty of
15 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
16 * Lesser General Public License for more details.
18 * You should have received a copy of the GNU Lesser General Public
19 * License along with this library; if not, write to the Free Software
20 * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
26 * SECTION:hildon-caption
27 * @short_description: A single-child container widget that precedes the
28 * contained widget with a field label and an optional icon.
30 * #HildonCaption is a single-child container widget that precedes the
31 * contained widget with a field label and an optional icon. It allows
32 * grouping of several controls together. When a captioned widget has focus,
33 * both widget and caption label are displayed with active focus.
43 #include "hildon-defines.h"
44 #include "hildon-caption.h"
45 #include "hildon-caption-private.h"
48 dgettext("hildon-libs", String)
50 #define HILDON_CAPTION_SPACING 6
52 static GtkEventBox* parent_class = NULL;
55 hildon_caption_class_init (HildonCaptionClass *caption_class);
58 hildon_caption_init (HildonCaption *caption);
61 hildon_caption_size_request (GtkWidget *widget,
62 GtkRequisition *requisition);
65 hildon_caption_size_allocate (GtkWidget *widget,
66 GtkAllocation *allocation);
69 hildon_caption_forall (GtkContainer *container,
70 gboolean include_internals,
75 hildon_caption_hierarchy_changed (GtkWidget *widget,
76 GtkWidget *previous_toplevel);
79 hildon_caption_set_focus (GtkWindow *window,
84 hildon_caption_grab_focus (GtkWidget *widget);
87 hildon_caption_activate (GtkWidget *widget);
90 hildon_caption_set_property (GObject *object,
96 hildon_caption_get_property (GObject *object,
102 hildon_caption_destroy (GtkObject *self);
105 hildon_caption_button_press (GtkWidget *widget,
106 GdkEventButton *event);
109 hildon_caption_set_label_text (HildonCaptionPrivate *priv,
113 hildon_caption_set_child_property (GtkContainer *container,
120 hildon_caption_get_child_property (GtkContainer *container,
145 * hildon_caption_get_type:
147 * Initializes and returns the type of a hildon caption.
149 * Returns: GType of #HildonCaption
152 hildon_caption_get_type (void)
154 static GType caption_type = 0;
158 static const GTypeInfo caption_info = {
159 sizeof (HildonCaptionClass),
160 NULL, /* base_init */
161 NULL, /* base_finalize */
162 (GClassInitFunc) hildon_caption_class_init,
163 NULL, /* class_finalize */
164 NULL, /* class_data */
165 sizeof (HildonCaption),
167 (GInstanceInitFunc) hildon_caption_init,
169 caption_type = g_type_register_static (GTK_TYPE_EVENT_BOX,
170 "HildonCaption", &caption_info, 0 );
176 * Initialises the caption class.
179 hildon_caption_class_init (HildonCaptionClass *caption_class)
181 GtkWidgetClass *widget_class = GTK_WIDGET_CLASS (caption_class);
182 GObjectClass *gobject_class = G_OBJECT_CLASS (caption_class);
183 GtkContainerClass *container_class = GTK_CONTAINER_CLASS (caption_class);
185 parent_class = g_type_class_peek_parent (caption_class);
187 g_type_class_add_private (caption_class, sizeof (HildonCaptionPrivate));
189 /* Override virtual functions */
190 gobject_class->get_property = hildon_caption_get_property;
191 gobject_class->set_property = hildon_caption_set_property;
192 caption_class->activate = (gpointer) hildon_caption_activate;
193 GTK_OBJECT_CLASS(caption_class)->destroy = hildon_caption_destroy;
195 container_class->forall = hildon_caption_forall;
196 container_class->set_child_property = hildon_caption_set_child_property;
197 container_class->get_child_property = hildon_caption_get_child_property;
199 widget_class->hierarchy_changed = hildon_caption_hierarchy_changed;
200 widget_class->size_request = hildon_caption_size_request;
201 widget_class->size_allocate = hildon_caption_size_allocate;
202 widget_class->button_press_event = hildon_caption_button_press;
203 widget_class->grab_focus = hildon_caption_grab_focus;
205 /* Create new signals and properties */
206 widget_class->activate_signal = g_signal_new ("activate",
207 G_OBJECT_CLASS_TYPE (
211 G_STRUCT_OFFSET (HildonCaptionClass,
212 activate), NULL, NULL,
213 g_cclosure_marshal_VOID__VOID,
217 * HildonCaption:label:
221 g_object_class_install_property (gobject_class, PROP_LABEL,
222 g_param_spec_string ("label",
223 "Current label", "Caption label",
224 NULL, G_PARAM_READABLE | G_PARAM_WRITABLE) );
227 * HildonCaption:markup:
229 * Caption markup. Mutually exclusive with label.
231 g_object_class_install_property (gobject_class, PROP_MARKUP,
232 g_param_spec_string ("markup",
233 "Current markup", "Caption markup",
234 NULL, G_PARAM_WRITABLE) );
237 * HildonCaption:icon:
239 * The icon shown on the caption area.
241 g_object_class_install_property (gobject_class, PROP_ICON,
242 g_param_spec_object ("icon",
244 "The icon shown on the caption area",
245 GTK_TYPE_WIDGET, G_PARAM_READABLE |
248 * HildonCaption:status:
250 * Mandatory or optional status.
252 g_object_class_install_property (gobject_class, PROP_STATUS,
253 g_param_spec_enum ("status",
255 "Mandatory or optional status",
256 HILDON_TYPE_CAPTION_STATUS,
257 HILDON_CAPTION_OPTIONAL,
258 G_PARAM_READABLE | G_PARAM_WRITABLE) );
260 * HildonCaption:icon-position:
262 * If the icon is positioned on the left or right side.
264 g_object_class_install_property (gobject_class, PROP_ICON_POSITION,
265 g_param_spec_enum ("icon-position",
267 "Whether the icon is on the left or right side",
268 HILDON_TYPE_CAPTION_ICON_POSITION,
269 HILDON_CAPTION_POSITION_RIGHT,
270 G_PARAM_READABLE | G_PARAM_WRITABLE) );
273 * HildonCaption:size_group:
275 * Current size group the caption is in.
277 g_object_class_install_property (gobject_class, PROP_SIZE_GROUP,
278 g_param_spec_object ("size_group",
279 "Current size group",
280 "Current size group the caption is in",
281 GTK_TYPE_SIZE_GROUP, G_PARAM_READABLE |
285 * HildonCaption:separator:
287 * The current separator.
289 g_object_class_install_property (gobject_class, PROP_SEPARATOR,
290 g_param_spec_string ("separator",
291 "Current separator", "Current separator",
292 _("ecdg_ti_caption_separator"),
293 G_PARAM_READABLE | G_PARAM_WRITABLE) );
295 /* Create child properties. These are related to
296 child <-> parent relationship, not to either of objects itself */
297 gtk_container_class_install_child_property (container_class,
299 g_param_spec_boolean ("expand",
300 "Same as GtkBox expand.",
301 "Same as GtkBox expand. Wheter the child should be expanded or not.",
306 /* Destroy can be called multiple times, remember to set pointers to NULL */
308 hildon_caption_destroy (GtkObject *self)
310 HildonCaptionPrivate *priv = HILDON_CAPTION_GET_PRIVATE (self);
312 /* Free our internal child */
313 if (priv && priv->caption_area)
315 gtk_widget_unparent (priv->caption_area);
316 priv->caption_area = NULL;
319 /* Free user provided strings */
320 if (priv && priv->text)
326 if (priv && priv->separator)
328 g_free (priv->separator);
329 priv->separator = NULL;
332 /* Parent classes destroy takes care of user packed contents */
333 if (GTK_OBJECT_CLASS (parent_class)->destroy)
334 GTK_OBJECT_CLASS (parent_class)->destroy (self);
338 hildon_caption_set_property (GObject *object,
343 HildonCaptionPrivate *priv = HILDON_CAPTION_GET_PRIVATE (object);
347 case PROP_ICON_POSITION:
348 hildon_caption_set_icon_position (HILDON_CAPTION (object), g_value_get_enum (value));
352 /* Free old label string */
360 priv->text = g_value_dup_string (value);
361 hildon_caption_set_label_text (priv, FALSE);
365 /* Free old label string */
373 priv->text = g_value_dup_string (value);
374 hildon_caption_set_label_text (priv, TRUE);
378 /* Remove old icon */
380 gtk_container_remove (GTK_CONTAINER (priv->icon_align), priv->icon);
382 /* Pack and display new icon */
383 priv->icon = g_value_get_object (value);
386 gtk_container_add (GTK_CONTAINER (priv->icon_align), priv->icon);
387 gtk_widget_show_all (priv->caption_area);
392 priv->status = g_value_get_enum (value);
395 case PROP_SIZE_GROUP:
396 /* Detach from previous size group */
398 gtk_size_group_remove_widget (priv->group, priv->caption_area);
400 priv->group = g_value_get_object (value);
402 /* Attach to new size group */
404 gtk_size_group_add_widget (priv->group, priv->caption_area);
406 gtk_widget_queue_draw (GTK_WIDGET(object));
411 /* Free old separator */
414 g_free (priv->separator);
415 priv->separator = NULL;
418 priv->separator = g_value_dup_string (value);
419 hildon_caption_set_label_text (priv, FALSE);
423 G_OBJECT_WARN_INVALID_PROPERTY_ID (object, param_id, pspec);
429 hildon_caption_get_property (GObject *object,
434 HildonCaptionPrivate *priv = HILDON_CAPTION_GET_PRIVATE (object);
439 g_value_set_string (value, priv->text);
443 g_value_set_object (value, priv->icon);
447 g_value_set_enum (value, priv->status);
450 case PROP_ICON_POSITION:
451 g_value_set_enum (value, priv->icon_position);
454 case PROP_SIZE_GROUP:
455 g_value_set_object (value, priv->group);
459 g_value_set_string (value, priv->separator);
463 G_OBJECT_WARN_INVALID_PROPERTY_ID(object, param_id, pspec);
469 hildon_caption_set_child_property (GtkContainer *container,
477 case CHILD_PROP_EXPAND:
478 hildon_caption_set_child_expand (HILDON_CAPTION (container),
479 g_value_get_boolean (value));
483 G_OBJECT_WARN_INVALID_PROPERTY_ID (container, property_id, pspec);
489 hildon_caption_get_child_property (GtkContainer *container,
497 case CHILD_PROP_EXPAND:
498 g_value_set_boolean (value, hildon_caption_get_child_expand(
499 HILDON_CAPTION (container)));
503 G_OBJECT_WARN_INVALID_PROPERTY_ID(container, property_id, pspec);
508 /* We want to activate out child control on button press */
510 hildon_caption_button_press (GtkWidget *widget,
511 GdkEventButton *event)
513 gtk_widget_grab_focus (GTK_BIN (widget)->child);
515 /* we'll update our focused state in set-focus when/if the child receives
522 hildon_caption_init (HildonCaption *caption)
524 HildonCaptionPrivate *priv = NULL;
526 /* Initialize startup state */
527 priv = HILDON_CAPTION_GET_PRIVATE (caption);
529 priv->status = HILDON_CAPTION_OPTIONAL;
532 priv->is_focused = FALSE;
535 priv->separator = g_strdup(_("ecdg_ti_caption_separator"));
537 gtk_widget_push_composite_child();
539 /* Create caption text */
540 priv->caption_area = gtk_hbox_new (FALSE, HILDON_CAPTION_SPACING);
541 priv->label = gtk_label_new (NULL);
542 priv->icon_align = gtk_alignment_new (0.5f, 0.5f, 0.0f, 0.0f);
543 priv->icon_position = HILDON_CAPTION_POSITION_RIGHT;
545 /* We want to receive button presses for child widget activation */
546 gtk_event_box_set_above_child (GTK_EVENT_BOX (caption), FALSE);
547 gtk_widget_add_events (GTK_WIDGET (caption), GDK_BUTTON_PRESS_MASK);
549 /* Pack text label caption layout */
550 gtk_box_pack_end (GTK_BOX (priv->caption_area), priv->icon_align, FALSE, FALSE, 0);
551 gtk_box_pack_end (GTK_BOX (priv->caption_area), priv->label, FALSE, FALSE, 0);
552 gtk_widget_set_parent (priv->caption_area, GTK_WIDGET (caption));
554 gtk_widget_pop_composite_child ();
556 hildon_caption_set_child_expand (caption, TRUE);
558 gtk_widget_show_all (priv->caption_area);
562 hildon_caption_set_focus (GtkWindow *window,
566 HildonCaptionPrivate *priv = HILDON_CAPTION_GET_PRIVATE (caption);
568 /* check if ancestor gone */
574 /* Try to find caption among the ancestors of widget */
575 if (gtk_widget_is_ancestor (widget, caption))
577 priv->is_focused = TRUE;
578 gtk_widget_queue_draw (caption);
582 if (priv->is_focused == TRUE)
584 /* Caption wasn't found, so cannot focus */
585 priv->is_focused = FALSE;
586 gtk_widget_queue_draw (caption);
590 /* We need to connect/disconnect signal handlers to toplevel window
591 in which we reside. Ww want to update connected signals if our
594 hildon_caption_hierarchy_changed (GtkWidget *widget,
595 GtkWidget *previous_toplevel)
597 GtkWidget *current_ancestor;
599 if (GTK_WIDGET_CLASS (parent_class)->hierarchy_changed)
600 GTK_WIDGET_CLASS (parent_class)->hierarchy_changed (widget, previous_toplevel);
602 /* If we already were inside a window, remove old handler */
603 if (previous_toplevel) {
604 /* This is a compilation workaround for gcc > 3.3 since glib is buggy */
605 /* see http://bugzilla.gnome.org/show_bug.cgi?id=310175 */
609 g_signal_handlers_disconnect_by_func
610 (previous_toplevel, (gpointer) hildon_caption_set_focus, widget);
613 current_ancestor = gtk_widget_get_ancestor (widget, GTK_TYPE_WINDOW);
615 /* Install new handler for focus movement */
616 if (current_ancestor)
617 g_signal_connect( current_ancestor, "set-focus",
618 G_CALLBACK (hildon_caption_set_focus), widget );
622 hildon_caption_size_request (GtkWidget *widget,
623 GtkRequisition *requisition)
626 HildonCaptionPrivate *priv = NULL;
627 g_return_if_fail (HILDON_IS_CAPTION(widget));
629 priv = HILDON_CAPTION_GET_PRIVATE (widget);
631 /* Use the same size requisition for the main box of the caption */
632 gtk_widget_size_request (priv->caption_area, &req);
634 if (GTK_WIDGET_CLASS (parent_class)->size_request)
635 GTK_WIDGET_CLASS (parent_class)->size_request (widget, requisition);
637 requisition->width += req.width + HILDON_CAPTION_SPACING * 3;
639 if ((req.height + (2 * widget->style->ythickness)) > requisition->height)
640 requisition->height = req.height + (2 * widget->style->ythickness);
643 /* We use HILDON_CAPTION_SPACING to make it look a bit nicer */
645 hildon_caption_size_allocate (GtkWidget *widget,
646 GtkAllocation *allocation)
648 GtkAllocation child_alloc;
649 GtkAllocation caption_alloc;
650 GtkRequisition req, child_req = {0};
651 GtkWidget *child = NULL;
652 HildonCaptionPrivate *priv = NULL;
655 g_assert (HILDON_IS_CAPTION (widget));
656 priv = HILDON_CAPTION_GET_PRIVATE (widget);
658 /* Get the rtl status */
659 rtl = (gtk_widget_get_direction (widget) == GTK_TEXT_DIR_RTL);
661 /* Position the caption to its allocated location */
662 if (GTK_WIDGET_REALIZED (widget))
663 gdk_window_move_resize (widget->window,
664 allocation->x + GTK_CONTAINER (widget)->border_width,
665 allocation->y + GTK_CONTAINER (widget)->border_width,
666 MAX (allocation->width - GTK_CONTAINER (widget)->border_width * 2, 0),
667 MAX (allocation->height - GTK_CONTAINER (widget)->border_width * 2, 0));
669 child = GTK_BIN (widget)->child;
671 gtk_widget_get_child_requisition (child, &child_req);
673 widget->allocation = *allocation;
674 gtk_widget_get_child_requisition (priv->caption_area, &req);
676 child_alloc.height = caption_alloc.height = allocation->height;
677 child_alloc.width = caption_alloc.width = allocation->width;
678 child_alloc.x = caption_alloc.x = caption_alloc.y = child_alloc.y = 0;
680 /* Center the captioned widget */
683 if (caption_alloc.width > child_req.width + HILDON_CAPTION_SPACING)
685 caption_alloc.x = caption_alloc.width - req.width;
686 child_alloc.width = child_req.width;
688 caption_alloc.width -= child_req.width + HILDON_CAPTION_SPACING * 2;
692 if (child_alloc.width > req.width + HILDON_CAPTION_SPACING)
694 child_alloc.x += req.width + HILDON_CAPTION_SPACING * 2;
695 caption_alloc.width = req.width;
697 /* Leave at least the space of the HILDON_CAPTION_SPACING in the left */
698 caption_alloc.x = HILDON_CAPTION_SPACING;
700 /* Leave room for the other drawable parts of the caption control */
701 child_alloc.width -= req.width + HILDON_CAPTION_SPACING * 2;
704 /* Give the child at least its minimum requisition, unless it is expandable */
705 if (! priv->expand && child && GTK_WIDGET_VISIBLE(child))
707 child_alloc.width = MIN (child_alloc.width, child_req.width);
708 child_alloc.height = MIN (child_alloc.height, child_req.height);
709 /* Center the child */
710 child_alloc.y = (allocation->height - child_alloc.height -
711 2 * GTK_CONTAINER (widget)->border_width)/2;
714 /* Ensure there are no negative dimensions */
715 if (child_alloc.width < 0)
717 caption_alloc.width = req.width + child_alloc.width;
718 child_alloc.width = 0;
719 caption_alloc.width = MAX (caption_alloc.width, 0);
723 child_alloc.x = caption_alloc.x - child_req.width - HILDON_CAPTION_SPACING * 2;
725 child_alloc.height = MAX (child_alloc.height, 0);
726 caption_alloc.height = MAX (caption_alloc.height, 0);
728 if (child && GTK_WIDGET_VISIBLE(child) )
729 gtk_widget_size_allocate (child, &child_alloc );
731 gtk_widget_size_allocate (priv->caption_area, &caption_alloc);
735 hildon_caption_forall (GtkContainer *container,
736 gboolean include_internals,
737 GtkCallback callback,
740 HildonCaptionPrivate *priv = NULL;
742 g_assert (HILDON_IS_CAPTION (container));
743 g_assert (callback != NULL);
745 priv = HILDON_CAPTION_GET_PRIVATE (container);
747 /* Execute callback for the child widgets */
748 if (GTK_CONTAINER_CLASS (parent_class)->forall)
749 GTK_CONTAINER_CLASS (parent_class)->forall (container, include_internals, callback, data);
751 if (include_internals)
752 /* Execute callback for the parent box as well */
753 (*callback) (priv->caption_area, data);
757 * hildon_caption_set_size_group:
758 * @caption: a #HildonCaption
759 * @new_group: a #GtkSizeGroup
761 * Sets a #GtkSizeGroup of a given captioned control.
765 hildon_caption_set_size_group (const HildonCaption *self,
768 g_object_set (G_OBJECT(self), "size_group", group, NULL);
772 * hildon_caption_get_size_group:
773 * @caption: a #HildonCaption
775 * Queries given captioned control for the #GtkSizeGroup assigned to it.
777 * Returns: a #GtkSizeGroup
781 hildon_caption_get_size_group (const HildonCaption *self)
783 HildonCaptionPrivate *priv;
784 g_return_val_if_fail (HILDON_IS_CAPTION (self), NULL);
786 priv = HILDON_CAPTION_GET_PRIVATE(self);
792 * hildon_caption_new:
793 * @group: a #GtkSizeGroup for controlling the size of related captions or %NULL
794 * @value: the caption text to accompany the text entry. The widget makes
795 * a copy of this text.
796 * @control: the control that is to be captioned.
797 * @icon: an icon to accompany the label or %NULL in case no icon should be displayed.
798 * @flag: indicates whether this captioned control is mandatory or
801 * Creates a new instance of #HildonCaption widget, with a specific
803 * Note: Clicking on a focused caption will trigger the activate signal.
804 * The default behaviour for the caption's activate signal is to call
805 * gtk_widget_activate() on its control.
807 * Returns: a new #HildonCaption
810 hildon_caption_new (GtkSizeGroup *group,
814 HildonCaptionStatus flag)
817 g_return_val_if_fail (GTK_IS_WIDGET (child), NULL);
819 widget = g_object_new (HILDON_TYPE_CAPTION,
827 /* Do not expand GtkCheckButton by default, we want to reduce its activation area */
828 if (GTK_IS_CHECK_BUTTON (child))
829 hildon_caption_set_child_expand (HILDON_CAPTION (widget), FALSE);
835 * hildon_caption_is_mandatory:
836 * @caption: a #HildonCaption
838 * Queries whether @caption is mandatory.
840 * Returns: Whether this captioned control is mandatory.
843 hildon_caption_is_mandatory (const HildonCaption *caption)
845 HildonCaptionPrivate *priv;
847 g_return_val_if_fail (HILDON_IS_CAPTION (caption), FALSE);
849 priv = HILDON_CAPTION_GET_PRIVATE (caption);
851 return (priv->status == HILDON_CAPTION_MANDATORY);
855 * hildon_caption_set_icon_position:
856 * @caption: a #HildonCaption
857 * @pos: one of the values from #HildonCaptionIconPosition
859 * Sets @caption<!-- -->'s icon position.
863 hildon_caption_set_icon_position (HildonCaption *caption,
864 HildonCaptionIconPosition pos)
866 g_return_if_fail (HILDON_IS_CAPTION (caption));
867 HildonCaptionPrivate *priv = HILDON_CAPTION_GET_PRIVATE (caption);
869 g_return_if_fail (priv->caption_area != NULL);
871 int order = (pos == HILDON_CAPTION_POSITION_LEFT) ? -1 : 0;
872 gtk_box_reorder_child (GTK_BOX (priv->caption_area), priv->icon_align, order);
874 priv->icon_position = pos;
878 * hildon_caption_get_icon_position:
879 * @caption: a #HildonCaption
881 * Gets @caption<!-- -->'s icon position.
883 * Returns: one of the values from #HildonCaptionIconPosition.
887 HildonCaptionIconPosition
888 hildon_caption_get_icon_position (const HildonCaption *caption)
890 g_return_val_if_fail (HILDON_IS_CAPTION (caption), 0);
892 HildonCaptionPrivate *priv = HILDON_CAPTION_GET_PRIVATE (caption);
894 return priv->icon_position;
898 * hildon_caption_set_status:
899 * @caption: a #HildonCaption
900 * @flag: one of the values from #HildonCaptionStatus
902 * Sets @caption<!-- -->'s status.
905 hildon_caption_set_status (HildonCaption *caption,
906 HildonCaptionStatus flag)
908 g_return_if_fail (HILDON_IS_CAPTION(caption));
910 g_object_set (G_OBJECT(caption), "status", flag, NULL);
914 * hildon_caption_get_status:
915 * @caption: a #HildonCaption
917 * Gets @caption<!-- -->'s status.
919 * Returns: one of the values from #HildonCaptionStatus
922 hildon_caption_get_status (const HildonCaption *caption)
924 HildonCaptionPrivate *priv;
925 g_return_val_if_fail (HILDON_IS_CAPTION (caption), HILDON_CAPTION_OPTIONAL);
927 priv = HILDON_CAPTION_GET_PRIVATE(caption);
933 * hildon_caption_set_icon_image:
934 * @caption: a #HildonCaption
935 * @icon : the #GtkImage to use as the icon.
936 * Calls gtk_widget_show() on the icon if it is not visible.
938 * Sets the icon image widget to be used by @caption.
941 hildon_caption_set_icon_image (HildonCaption *caption,
944 g_return_if_fail (HILDON_IS_CAPTION(caption));
946 g_object_set (G_OBJECT(caption), "icon", icon, NULL);
950 * hildon_caption_get_icon_image:
951 * @caption: a #HildonCaption
953 * Gets the icon image widget used by @caption.
955 * Returns: the #GtkImage widget that is being used as the icon by
956 * @caption, or %NULL if no icon image is in use.
959 hildon_caption_get_icon_image (const HildonCaption *caption)
961 HildonCaptionPrivate *priv;
963 g_return_val_if_fail (HILDON_IS_CAPTION (caption), NULL);
965 priv = HILDON_CAPTION_GET_PRIVATE (caption);
971 * hildon_caption_set_label:
972 * @caption: a #HildonCaption
973 * @label: the text to use
975 * Sets the label text that appears before the control.
976 * Separator character is added to the end of the label string. By default
977 * the separator is ":". See also hildon_caption_set_separator().
981 hildon_caption_set_label (HildonCaption *caption,
984 g_return_if_fail (HILDON_IS_CAPTION (caption));
986 g_object_set (G_OBJECT(caption), "label", label, NULL);
990 * hildon_caption_set_label_markup:
991 * @caption : a #HildonCaption
992 * @markup : the markup text to use
994 * Sets the label markup text that appears before the control. It acts like
995 * hildon_caption_set_label() but is using the markup text that allows to
996 * specify text properties such as bold or italic.
999 hildon_caption_set_label_markup (HildonCaption *caption,
1000 const gchar *markup)
1002 g_return_if_fail (HILDON_IS_CAPTION (caption));
1004 g_object_set (G_OBJECT(caption), "markup", markup, NULL);
1008 * hildon_caption_get_label:
1009 * @caption : a #HildonCaption
1011 * Gets the label of @caption
1013 * Returns: the text currently being used as the label of @caption.
1014 * The string is owned by the label and the caller should never
1015 * free or modify this value.
1018 hildon_caption_get_label (const HildonCaption *caption)
1020 HildonCaptionPrivate *priv;
1021 g_return_val_if_fail (HILDON_IS_CAPTION (caption), "");
1022 priv = HILDON_CAPTION_GET_PRIVATE (caption);
1024 return (gchar*) gtk_label_get_text (GTK_LABEL (priv->label));
1028 * hildon_caption_set_separator:
1029 * @caption: a #HildonCaption
1030 * @separator: the separator to use
1032 * Sets the separator character that appears after the label.
1033 * The default seaparator character is ":".
1036 hildon_caption_set_separator (HildonCaption *caption,
1037 const gchar *separator)
1039 g_return_if_fail (HILDON_IS_CAPTION (caption));
1041 g_object_set (G_OBJECT (caption), "separator", separator, NULL);
1045 * hildon_caption_get_separator:
1046 * @caption: a #HildonCaption
1048 * Gets the separator string of @caption
1050 * Returns: the text currently being used as the separator of the caption
1051 * control. The string is owned by @caption and the caller should
1052 * never free or modify this value.
1055 hildon_caption_get_separator (const HildonCaption *caption)
1057 HildonCaptionPrivate *priv;
1058 g_return_val_if_fail (HILDON_IS_CAPTION (caption), "");
1060 priv = HILDON_CAPTION_GET_PRIVATE (caption);
1062 return priv->separator;
1065 /* Activates the child control
1066 * We have this signal so that if needed an application can
1067 * know when we've been activated (useful for captions with
1069 * FIXME: There never are multiple children. Possibly activate
1070 * signal could be removed entirely? (does anyone use it?)
1073 hildon_caption_activate (GtkWidget *widget)
1075 GtkWidget *child = GTK_BIN (widget)->child;
1076 gtk_widget_grab_focus (child);
1080 hildon_caption_grab_focus (GtkWidget *widget)
1082 gtk_widget_grab_focus (GTK_BIN (widget)->child);
1086 * hildon_caption_set_child_expand:
1087 * @caption: a #HildonCaption
1088 * @expand: whether the child is expandable.
1090 * Sets child expandability.
1093 hildon_caption_set_child_expand (HildonCaption *caption,
1096 HildonCaptionPrivate *priv = NULL;
1097 GtkWidget *child = NULL;
1098 g_return_if_fail (HILDON_IS_CAPTION (caption));
1100 priv = HILDON_CAPTION_GET_PRIVATE (caption);
1102 /* Did the setting really change? */
1103 if (priv->expand == expand)
1106 priv->expand = expand;
1107 child = GTK_BIN (caption)->child;
1109 /* We do not have a child, nothing to do */
1110 if (! GTK_IS_WIDGET (child))
1113 if (GTK_WIDGET_VISIBLE (child) && GTK_WIDGET_VISIBLE (caption))
1114 gtk_widget_queue_resize (child);
1116 gtk_widget_child_notify (child, "expand");
1120 * hildon_caption_get_child_expand:
1121 * @caption: a #HildonCaption
1123 * Gets childs expandability.
1125 * Returns: wheter the child is expandable or not.
1128 hildon_caption_get_child_expand (const HildonCaption *caption)
1130 HildonCaptionPrivate *priv = NULL;
1131 g_return_val_if_fail (HILDON_IS_CAPTION (caption), FALSE);
1133 priv = HILDON_CAPTION_GET_PRIVATE (caption);
1135 return priv->expand;
1139 hildon_caption_set_label_text (HildonCaptionPrivate *priv,
1143 g_assert (priv != NULL);
1147 if (priv->separator)
1149 /* Don't duplicate the separator, if the string already contains one */
1150 if (g_str_has_suffix (priv->text, priv->separator))
1153 gtk_label_set_markup (GTK_LABEL (priv->label), priv->text);
1155 gtk_label_set_text (GTK_LABEL (priv->label), priv->text);
1159 /* Append separator and set text */
1160 tmp = g_strconcat( priv->text, priv->separator, NULL );
1163 gtk_label_set_markup (GTK_LABEL (priv->label), tmp);
1165 gtk_label_set_text (GTK_LABEL (priv->label), tmp);
1173 gtk_label_set_markup (GTK_LABEL (priv->label), priv->text);
1175 gtk_label_set_text (GTK_LABEL (priv->label), priv->text);
1180 /* Clear the label */
1182 gtk_label_set_markup (GTK_LABEL (priv->label), "");
1184 gtk_label_set_text (GTK_LABEL (priv->label), "" );
1189 * hildon_caption_set_label_alignment:
1190 * @caption: a #HildonCaption widget
1191 * @alignment: new vertical alignment
1193 * Sets the vertical alignment to be used for the
1194 * text part of the caption. Applications need to
1195 * align the child control themselves.
1199 hildon_caption_set_label_alignment (HildonCaption *caption,
1202 HildonCaptionPrivate *priv;
1204 g_return_if_fail (HILDON_IS_CAPTION (caption));
1206 priv = HILDON_CAPTION_GET_PRIVATE (caption);
1208 g_object_set (priv->label, "yalign", alignment, NULL);
1209 g_object_set (priv->icon_align, "yalign", alignment, NULL);
1214 * hildon_caption_get_label_alignment:
1215 * @caption: a #HildonCaption widget
1217 * Gets current vertical alignment for the text part.
1219 * Returns: vertical alignment
1223 hildon_caption_get_label_alignment (HildonCaption *caption)
1225 HildonCaptionPrivate *priv;
1228 g_return_val_if_fail (HILDON_IS_CAPTION (caption), 0);
1229 priv = HILDON_CAPTION_GET_PRIVATE (caption);
1231 g_object_get (priv->label, "yalign", &result, NULL);