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_expose (GtkWidget *widget,
103 GdkEventExpose *event);
106 hildon_caption_destroy (GtkObject *self);
109 hildon_caption_button_press (GtkWidget *widget,
110 GdkEventButton *event);
113 hildon_caption_set_label_text (HildonCaptionPrivate *priv,
117 hildon_caption_set_child_property (GtkContainer *container,
124 hildon_caption_get_child_property (GtkContainer *container,
149 * hildon_caption_get_type:
151 * Initializes and returns the type of a hildon caption.
153 * Returns: GType of #HildonCaption
156 hildon_caption_get_type (void)
158 static GType caption_type = 0;
162 static const GTypeInfo caption_info = {
163 sizeof (HildonCaptionClass),
164 NULL, /* base_init */
165 NULL, /* base_finalize */
166 (GClassInitFunc) hildon_caption_class_init,
167 NULL, /* class_finalize */
168 NULL, /* class_data */
169 sizeof (HildonCaption),
171 (GInstanceInitFunc) hildon_caption_init,
173 caption_type = g_type_register_static (GTK_TYPE_EVENT_BOX,
174 "HildonCaption", &caption_info, 0 );
180 * Initialises the caption class.
183 hildon_caption_class_init (HildonCaptionClass *caption_class)
185 GtkWidgetClass *widget_class = GTK_WIDGET_CLASS (caption_class);
186 GObjectClass *gobject_class = G_OBJECT_CLASS (caption_class);
187 GtkContainerClass *container_class = GTK_CONTAINER_CLASS (caption_class);
189 parent_class = g_type_class_peek_parent (caption_class);
191 g_type_class_add_private (caption_class, sizeof (HildonCaptionPrivate));
193 /* Override virtual functions */
194 gobject_class->get_property = hildon_caption_get_property;
195 gobject_class->set_property = hildon_caption_set_property;
196 caption_class->activate = (gpointer) hildon_caption_activate;
197 GTK_OBJECT_CLASS(caption_class)->destroy = hildon_caption_destroy;
199 container_class->forall = hildon_caption_forall;
200 container_class->set_child_property = hildon_caption_set_child_property;
201 container_class->get_child_property = hildon_caption_get_child_property;
203 widget_class->expose_event = hildon_caption_expose;
204 widget_class->hierarchy_changed = hildon_caption_hierarchy_changed;
205 widget_class->size_request = hildon_caption_size_request;
206 widget_class->size_allocate = hildon_caption_size_allocate;
207 widget_class->button_press_event = hildon_caption_button_press;
208 widget_class->grab_focus = hildon_caption_grab_focus;
210 /* Create new signals and properties */
211 widget_class->activate_signal = g_signal_new ("activate",
212 G_OBJECT_CLASS_TYPE (
216 G_STRUCT_OFFSET (HildonCaptionClass,
217 activate), NULL, NULL,
218 g_cclosure_marshal_VOID__VOID,
222 * HildonCaption:label:
226 g_object_class_install_property (gobject_class, PROP_LABEL,
227 g_param_spec_string ("label",
228 "Current label", "Caption label",
229 NULL, G_PARAM_READABLE | G_PARAM_WRITABLE) );
232 * HildonCaption:markup:
234 * Caption markup. Mutually exclusive with label.
236 g_object_class_install_property (gobject_class, PROP_MARKUP,
237 g_param_spec_string ("markup",
238 "Current markup", "Caption markup",
239 NULL, G_PARAM_WRITABLE) );
242 * HildonCaption:icon:
244 * The icon shown on the caption area.
246 g_object_class_install_property (gobject_class, PROP_ICON,
247 g_param_spec_object ("icon",
249 "The icon shown on the caption area",
250 GTK_TYPE_WIDGET, G_PARAM_READABLE |
253 * HildonCaption:status:
255 * Mandatory or optional status.
257 g_object_class_install_property (gobject_class, PROP_STATUS,
258 g_param_spec_enum ("status",
260 "Mandatory or optional status",
261 HILDON_TYPE_CAPTION_STATUS,
262 HILDON_CAPTION_OPTIONAL,
263 G_PARAM_READABLE | G_PARAM_WRITABLE) );
265 * HildonCaption:icon-position:
267 * If the icon is positioned on the left or right side.
269 g_object_class_install_property (gobject_class, PROP_ICON_POSITION,
270 g_param_spec_enum ("icon-position",
272 "If the icon is on the left or right side",
273 HILDON_TYPE_CAPTION_ICON_POSITION,
274 HILDON_CAPTION_POSITION_RIGHT,
275 G_PARAM_READABLE | G_PARAM_WRITABLE) );
278 * HildonCaption:size_group:
280 * Current size group the caption is in.
282 g_object_class_install_property (gobject_class, PROP_SIZE_GROUP,
283 g_param_spec_object ("size_group",
284 "Current size group",
285 "Current size group the caption is in",
286 GTK_TYPE_SIZE_GROUP, G_PARAM_READABLE |
290 * HildonCaption:separator:
292 * The current separator.
294 g_object_class_install_property (gobject_class, PROP_SEPARATOR,
295 g_param_spec_string ("separator",
296 "Current separator", "Current separator",
297 _("ecdg_ti_caption_separator"),
298 G_PARAM_READABLE | G_PARAM_WRITABLE) );
300 /* Create child properties. These are related to
301 child <-> parent relationship, not to either of objects itself */
302 gtk_container_class_install_child_property (container_class,
304 g_param_spec_boolean ("expand",
305 "Same as GtkBox expand.",
306 "Same as GtkBox expand. Wheter the child should be expanded or not.",
311 /* Destroy can be called multiple times, remember to set pointers to NULL */
313 hildon_caption_destroy (GtkObject *self)
315 HildonCaptionPrivate *priv = HILDON_CAPTION_GET_PRIVATE (self);
317 /* Free our internal child */
318 if (priv && priv->caption_area)
320 gtk_widget_unparent (priv->caption_area);
321 priv->caption_area = NULL;
324 /* Free user provided strings */
325 if (priv && priv->text)
331 if (priv && priv->separator)
333 g_free (priv->separator);
334 priv->separator = NULL;
337 /* Parent classes destroy takes care of user packed contents */
338 if (GTK_OBJECT_CLASS (parent_class)->destroy)
339 GTK_OBJECT_CLASS (parent_class)->destroy (self);
342 /* Parent, eventbox will run allocate also for the child which may be
343 * owning a window too. This window is then moved and resized
344 * and we do not want to do that (it causes flickering).
347 hildon_caption_expose (GtkWidget *widget,
348 GdkEventExpose *event)
350 HildonCaptionPrivate *priv = NULL;
355 g_assert (HILDON_IS_CAPTION (widget));
356 priv = HILDON_CAPTION_GET_PRIVATE (widget);
359 if (! GTK_WIDGET_DRAWABLE (widget))
362 GTK_WIDGET_CLASS (parent_class)->expose_event (widget, event);
364 /* If our child control is focused, we draw nice looking focus
365 graphics for the caption */
366 if (priv->is_focused && priv->text)
368 /* Determine focus box dimensions */
369 gtk_widget_get_child_requisition (priv->caption_area, &req);
370 align = hildon_caption_get_label_alignment (HILDON_CAPTION(widget));
372 alloc.width = priv->caption_area->allocation.width + HILDON_CAPTION_SPACING;
373 alloc.height = MIN (req.height + (2 * widget->style->ythickness), priv->caption_area->allocation.height);
375 alloc.x = priv->caption_area->allocation.x - HILDON_CAPTION_SPACING; /* - left margin */
376 alloc.y = priv->caption_area->allocation.y +
377 MAX (((priv->caption_area->allocation.height - alloc.height) * align), 0);
379 /* Paint the focus box */
380 gtk_paint_box (widget->style, widget->window, GTK_STATE_ACTIVE,
381 GTK_SHADOW_OUT, NULL, widget, "selection",
382 alloc.x, alloc.y, alloc.width, alloc.height);
384 /* Paint caption contents on top of the focus box */
385 GTK_WIDGET_GET_CLASS (priv->caption_area)->expose_event (priv->caption_area, event);
392 hildon_caption_set_property (GObject *object,
397 HildonCaptionPrivate *priv = HILDON_CAPTION_GET_PRIVATE (object);
402 case PROP_ICON_POSITION:
403 hildon_caption_set_icon_position (HILDON_CAPTION (object), g_value_get_enum (value));
407 /* Free old label string */
415 priv->text = g_value_dup_string (value);
416 hildon_caption_set_label_text (priv, FALSE);
420 /* Free old label string */
428 priv->text = g_value_dup_string (value);
429 hildon_caption_set_label_text (priv, TRUE);
433 /* Remove old icon */
435 gtk_container_remove (GTK_CONTAINER (priv->icon_align), priv->icon);
437 /* Pack and display new icon */
438 priv->icon = g_value_get_object (value);
441 gtk_container_add (GTK_CONTAINER (priv->icon_align), priv->icon);
442 gtk_widget_show_all (priv->caption_area);
447 priv->status = g_value_get_enum (value);
450 case PROP_SIZE_GROUP:
451 /* Detach from previous size group */
453 gtk_size_group_remove_widget (priv->group, priv->caption_area);
455 priv->group = g_value_get_object (value);
457 /* Attach to new size group */
459 gtk_size_group_add_widget (priv->group, priv->caption_area);
461 gtk_widget_queue_draw (GTK_WIDGET(object));
466 /* Free old separator */
469 g_free (priv->separator);
470 priv->separator = NULL;
473 priv->separator = g_value_dup_string (value);
474 hildon_caption_set_label_text (priv, FALSE);
478 G_OBJECT_WARN_INVALID_PROPERTY_ID (object, param_id, pspec);
484 hildon_caption_get_property (GObject *object,
489 HildonCaptionPrivate *priv = HILDON_CAPTION_GET_PRIVATE (object);
494 g_value_set_string (value, priv->text);
498 g_value_set_object (value, priv->icon);
502 g_value_set_enum (value, priv->status);
505 case PROP_ICON_POSITION:
506 g_value_set_enum (value, priv->icon_position);
509 case PROP_SIZE_GROUP:
510 g_value_set_object (value, priv->group);
514 g_value_set_string (value, priv->separator);
518 G_OBJECT_WARN_INVALID_PROPERTY_ID(object, param_id, pspec);
524 hildon_caption_set_child_property (GtkContainer *container,
532 case CHILD_PROP_EXPAND:
533 hildon_caption_set_child_expand (HILDON_CAPTION (container),
534 g_value_get_boolean (value));
538 G_OBJECT_WARN_INVALID_PROPERTY_ID (container, property_id, pspec);
544 hildon_caption_get_child_property (GtkContainer *container,
552 case CHILD_PROP_EXPAND:
553 g_value_set_boolean (value, hildon_caption_get_child_expand(
554 HILDON_CAPTION (container)));
558 G_OBJECT_WARN_INVALID_PROPERTY_ID(container, property_id, pspec);
563 /* We want to activate out child control on button press */
565 hildon_caption_button_press (GtkWidget *widget,
566 GdkEventButton *event)
568 gtk_widget_grab_focus (GTK_BIN (widget)->child);
570 /* we'll update our focused state in set-focus when/if the child receives
577 hildon_caption_init (HildonCaption *caption)
579 HildonCaptionPrivate *priv = NULL;
581 /* Initialize startup state */
582 priv = HILDON_CAPTION_GET_PRIVATE (caption);
585 priv->status = HILDON_CAPTION_OPTIONAL;
588 priv->is_focused = FALSE;
591 priv->separator = g_strdup(_("ecdg_ti_caption_separator"));
593 gtk_widget_push_composite_child();
595 /* Create caption text */
596 priv->caption_area = gtk_hbox_new (FALSE, HILDON_CAPTION_SPACING);
597 priv->label = gtk_label_new (NULL);
598 priv->icon_align = gtk_alignment_new (0.5f, 0.5f, 0.0f, 0.0f);
599 priv->icon_position = HILDON_CAPTION_POSITION_RIGHT;
601 /* We want to receive button presses for child widget activation */
602 gtk_event_box_set_above_child (GTK_EVENT_BOX (caption), FALSE);
603 gtk_widget_add_events (GTK_WIDGET (caption), GDK_BUTTON_PRESS_MASK);
605 /* Pack text label caption layout */
606 gtk_box_pack_end (GTK_BOX (priv->caption_area), priv->icon_align, FALSE, FALSE, 0);
607 gtk_box_pack_end (GTK_BOX (priv->caption_area), priv->label, FALSE, FALSE, 0);
608 gtk_widget_set_parent (priv->caption_area, GTK_WIDGET (caption));
610 gtk_widget_pop_composite_child ();
612 hildon_caption_set_child_expand (caption, TRUE);
614 gtk_widget_show_all (priv->caption_area);
618 hildon_caption_set_focus (GtkWindow *window,
622 HildonCaptionPrivate *priv = HILDON_CAPTION_GET_PRIVATE (caption);
625 /* check if ancestor gone */
631 /* Try to find caption among the ancestors of widget */
632 if (gtk_widget_is_ancestor (widget, caption))
634 priv->is_focused = TRUE;
635 gtk_widget_queue_draw (caption);
639 if (priv->is_focused == TRUE)
641 /* Caption wasn't found, so cannot focus */
642 priv->is_focused = FALSE;
643 gtk_widget_queue_draw (caption);
647 /* We need to connect/disconnect signal handlers to toplevel window
648 in which we reside. Ww want to update connected signals if our
651 hildon_caption_hierarchy_changed (GtkWidget *widget,
652 GtkWidget *previous_toplevel)
654 GtkWidget *current_ancestor;
655 HildonCaptionPrivate *priv;
657 priv = HILDON_CAPTION_GET_PRIVATE (widget);
660 if (GTK_WIDGET_CLASS (parent_class)->hierarchy_changed)
661 GTK_WIDGET_CLASS (parent_class)->hierarchy_changed (widget, previous_toplevel);
663 /* If we already were inside a window, remove old handler */
664 if (previous_toplevel) {
665 /* This is a compilation workaround for gcc > 3.3 since glib is buggy */
666 /* see http://bugzilla.gnome.org/show_bug.cgi?id=310175 */
670 g_signal_handlers_disconnect_by_func
671 (previous_toplevel, (gpointer) hildon_caption_set_focus, widget);
674 current_ancestor = gtk_widget_get_ancestor (widget, GTK_TYPE_WINDOW);
676 /* Install new handler for focus movement */
677 if (current_ancestor)
678 g_signal_connect( current_ancestor, "set-focus",
679 G_CALLBACK (hildon_caption_set_focus), widget );
683 hildon_caption_size_request (GtkWidget *widget,
684 GtkRequisition *requisition)
687 HildonCaptionPrivate *priv = NULL;
688 g_return_if_fail (HILDON_IS_CAPTION(widget));
690 priv = HILDON_CAPTION_GET_PRIVATE (widget);
693 /* Use the same size requisition for the main box of the caption */
694 gtk_widget_size_request (priv->caption_area, &req);
696 if (GTK_WIDGET_CLASS (parent_class)->size_request)
697 GTK_WIDGET_CLASS (parent_class)->size_request (widget, requisition);
699 requisition->width += req.width + HILDON_CAPTION_SPACING * 3;
701 if ((req.height + (2 * widget->style->ythickness)) > requisition->height)
702 requisition->height = req.height + (2 * widget->style->ythickness);
705 /* We use HILDON_CAPTION_SPACING to make it look a bit nicer */
707 hildon_caption_size_allocate (GtkWidget *widget,
708 GtkAllocation *allocation)
710 GtkAllocation child_alloc;
711 GtkAllocation caption_alloc;
712 GtkRequisition req, child_req;
713 GtkWidget *child = NULL;
714 HildonCaptionPrivate *priv = NULL;
717 g_assert (HILDON_IS_CAPTION (widget));
718 priv = HILDON_CAPTION_GET_PRIVATE (widget);
721 /* Get the rtl status */
722 rtl = (gtk_widget_get_direction (widget) == GTK_TEXT_DIR_RTL);
724 /* Position the caption to its allocated location */
725 if (GTK_WIDGET_REALIZED (widget))
726 gdk_window_move_resize (widget->window,
727 allocation->x + GTK_CONTAINER (widget)->border_width,
728 allocation->y + GTK_CONTAINER (widget)->border_width,
729 MAX (allocation->width - GTK_CONTAINER (widget)->border_width * 2, 0),
730 MAX (allocation->height - GTK_CONTAINER (widget)->border_width * 2, 0));
732 child = GTK_BIN (widget)->child;
734 gtk_widget_get_child_requisition (child, &child_req);
736 widget->allocation = *allocation;
737 gtk_widget_get_child_requisition (priv->caption_area, &req);
739 child_alloc.height = caption_alloc.height = allocation->height;
740 child_alloc.width = caption_alloc.width = allocation->width;
741 child_alloc.x = caption_alloc.x = caption_alloc.y = child_alloc.y = 0;
743 /* Center the captioned widget */
746 if (caption_alloc.width > child_req.width + HILDON_CAPTION_SPACING)
748 caption_alloc.x = caption_alloc.width - req.width;
749 child_alloc.width = child_req.width;
751 caption_alloc.width -= child_req.width + HILDON_CAPTION_SPACING * 2;
755 if (child_alloc.width > req.width + HILDON_CAPTION_SPACING)
757 child_alloc.x += req.width + HILDON_CAPTION_SPACING * 2;
758 caption_alloc.width = req.width;
760 /* Leave at least the space of the HILDON_CAPTION_SPACING in the left */
761 caption_alloc.x = HILDON_CAPTION_SPACING;
763 /* Leave room for the other drawable parts of the caption control */
764 child_alloc.width -= req.width + HILDON_CAPTION_SPACING * 2;
767 /* Give the child at least its minimum requisition, unless it is expandable */
768 if (! priv->expand && child && GTK_WIDGET_VISIBLE(child))
770 child_alloc.width = MIN (child_alloc.width, child_req.width);
771 child_alloc.height = MIN (child_alloc.height, child_req.height);
772 /* Center the child */
773 child_alloc.y = (allocation->height - child_alloc.height -
774 2 * GTK_CONTAINER (widget)->border_width)/2;
777 /* Ensure there are no negative dimensions */
778 if (child_alloc.width < 0)
780 caption_alloc.width = req.width + child_alloc.width;
781 child_alloc.width = 0;
782 caption_alloc.width = MAX (caption_alloc.width, 0);
786 child_alloc.x = caption_alloc.x - child_req.width - HILDON_CAPTION_SPACING * 2;
788 child_alloc.height = MAX (child_alloc.height, 0);
789 caption_alloc.height = MAX (caption_alloc.height, 0);
791 if (child && GTK_WIDGET_VISIBLE(child) )
792 gtk_widget_size_allocate (child, &child_alloc );
794 gtk_widget_size_allocate (priv->caption_area, &caption_alloc);
798 hildon_caption_forall (GtkContainer *container,
799 gboolean include_internals,
800 GtkCallback callback,
803 HildonCaptionPrivate *priv = NULL;
805 g_assert (HILDON_IS_CAPTION (container));
806 g_assert (callback != NULL);
808 priv = HILDON_CAPTION_GET_PRIVATE (container);
811 /* Execute callback for the child widgets */
812 if (GTK_CONTAINER_CLASS (parent_class)->forall)
813 GTK_CONTAINER_CLASS (parent_class)->forall (container, include_internals, callback, data);
815 if (include_internals)
816 /* Execute callback for the parent box as well */
817 (*callback) (priv->caption_area, data);
821 * hildon_caption_set_size_group:
822 * @caption : a #HildonCaption
823 * @new_group : a #GtkSizeGroup
825 * Sets a #GtkSizeGroup of a given captioned control.
829 hildon_caption_set_size_group (const HildonCaption *self,
832 g_object_set (G_OBJECT(self), "size_group", group, NULL);
836 * hildon_caption_get_size_group:
837 * @caption : a #HildonCaption
839 * Query given captioned control for the #GtkSizeGroup assigned to it.
841 * Returns: a #GtkSizeGroup
845 hildon_caption_get_size_group (const HildonCaption *self)
847 HildonCaptionPrivate *priv;
848 g_return_val_if_fail (HILDON_IS_CAPTION (self), NULL);
850 priv = HILDON_CAPTION_GET_PRIVATE(self);
857 * hildon_caption_new:
858 * @group : a #GtkSizeGroup for controlling the size of related captions,
860 * @value : the caption text to accompany the text entry. The widget makes
861 * a copy of this text.
862 * @control : the control that is to be captioned
863 * @icon : an icon to accompany the label - can be NULL in which case no
865 * @flag : indicates whether this captioned control is mandatory or
868 * Creates a new instance of hildon_caption widget, with a specific
870 * Note: Clicking on a focused caption will trigger the activate signal.
871 * The default behaviour for the caption's activate signal is to call
872 * gtk_widget_activate on it's control.
874 * Returns: a #GtkWidget pointer of Caption
877 hildon_caption_new (GtkSizeGroup *group,
881 HildonCaptionStatus flag)
884 g_return_val_if_fail (GTK_IS_WIDGET (child), NULL);
886 widget = g_object_new (HILDON_TYPE_CAPTION,
894 /* Do not expand GtkCheckButton by default, we want to reduce its activation area */
895 if (GTK_IS_CHECK_BUTTON (child))
896 hildon_caption_set_child_expand (HILDON_CAPTION (widget), FALSE);
902 * hildon_caption_is_mandatory:
903 * @caption : a #HildonCaption
905 * Query #HildonCaption whether this captioned control is a mandatory one.
907 * Returns: is this captioned control a mandatory one?
910 hildon_caption_is_mandatory (const HildonCaption *caption)
912 HildonCaptionPrivate *priv;
914 g_return_val_if_fail (HILDON_IS_CAPTION (caption), FALSE);
916 priv = HILDON_CAPTION_GET_PRIVATE (caption);
919 return (priv->status == HILDON_CAPTION_MANDATORY);
923 * hildon_caption_set_icon_position:
924 * @caption : a #HildonCaption
925 * @pos : one of the values from #HildonCaptionIconPosition
927 * Sets #HildonCaption icon position.
931 hildon_caption_set_icon_position (HildonCaption *caption,
932 HildonCaptionIconPosition pos)
934 g_return_if_fail (HILDON_IS_CAPTION (caption));
935 HildonCaptionPrivate *priv = HILDON_CAPTION_GET_PRIVATE (caption);
938 g_return_if_fail (priv->caption_area != NULL);
940 int order = (pos == HILDON_CAPTION_POSITION_LEFT) ? -1 : 0;
941 gtk_box_reorder_child (GTK_BOX (priv->caption_area), priv->icon_align, order);
943 priv->icon_position = pos;
947 * hildon_caption_get_icon_position:
948 * @caption : a #HildonCaption
950 * Gets #HildonCaption icon position.
952 * Returns: one of the values from #HildonCaptionIconPosition.
956 HildonCaptionIconPosition
957 hildon_caption_get_icon_position (const HildonCaption *caption)
959 g_return_val_if_fail (HILDON_IS_CAPTION (caption), 0);
961 HildonCaptionPrivate *priv = HILDON_CAPTION_GET_PRIVATE (caption);
964 return priv->icon_position;
968 * hildon_caption_set_status:
969 * @caption : a #HildonCaption
970 * @flag : one of the values from #HildonCaptionStatus
972 * Sets #HildonCaption status.
975 hildon_caption_set_status (HildonCaption *caption,
976 HildonCaptionStatus flag)
978 g_return_if_fail (HILDON_IS_CAPTION(caption));
980 g_object_set (G_OBJECT(caption), "status", flag, NULL);
984 * hildon_caption_get_status:
985 * @caption: a #HildonCaption
987 * Gets #HildonCaption status.
989 * Returns: one of the values from #HildonCaptionStatus
992 hildon_caption_get_status (const HildonCaption *caption)
994 HildonCaptionPrivate *priv;
995 g_return_val_if_fail (HILDON_IS_CAPTION (caption), HILDON_CAPTION_OPTIONAL);
997 priv = HILDON_CAPTION_GET_PRIVATE(caption);
1000 return priv->status;
1004 * hildon_caption_set_icon_image:
1005 * @caption : a #HildonCaption
1006 * @icon : the #GtkImage to use as the icon.
1007 * calls gtk_widget_show on the icon if !GTK_WIDGET_VISIBLE(icon)
1009 * Sets the icon image widget to be used by this hildon_caption widget.
1012 hildon_caption_set_icon_image (HildonCaption *caption,
1015 g_return_if_fail (HILDON_IS_CAPTION(caption));
1017 g_object_set (G_OBJECT(caption), "icon", icon, NULL);
1021 * hildon_caption_get_icon_image:
1022 * @caption : a #HildonCaption
1024 * Gets icon of #HildonCaption
1026 * Returns: the #GtkImage widget that is being used as the icon by the
1027 * hildon_caption, or NULL if no icon image is in use.
1030 hildon_caption_get_icon_image (const HildonCaption *caption)
1032 HildonCaptionPrivate *priv;
1034 g_return_val_if_fail (HILDON_IS_CAPTION (caption), NULL);
1036 priv = HILDON_CAPTION_GET_PRIVATE (caption);
1043 * hildon_caption_set_label:
1044 * @caption : a #HildonCaption
1045 * @label : the text to use
1047 * Sets the label text that appears before the control.
1048 * Separator character is added to the end of the label string. By default
1049 * the separator is ":".
1052 hildon_caption_set_label (HildonCaption *caption,
1055 g_return_if_fail (HILDON_IS_CAPTION (caption));
1057 g_object_set (G_OBJECT(caption), "label", label, NULL);
1061 * hildon_caption_set_label_markup:
1062 * @caption : a #HildonCaption
1063 * @markup : the markup text to use
1065 * Sets the label markup text that appears before the control. It acts like
1066 * #hildon_caption_set_label but is using the markup text that allows to specify
1067 * text properties such as bold or italic.
1070 hildon_caption_set_label_markup (HildonCaption *caption,
1071 const gchar *markup)
1073 g_return_if_fail (HILDON_IS_CAPTION (caption));
1075 g_object_set (G_OBJECT(caption), "markup", markup, NULL);
1079 * hildon_caption_get_label:
1080 * @caption : a #HildonCaption
1082 * Gets label of #HildonCaption
1084 * Returns: the text currently being used as the label of the caption
1085 * control. The string is owned by the label and the caller should never
1086 * free or modify this value.
1089 hildon_caption_get_label (const HildonCaption *caption)
1091 HildonCaptionPrivate *priv;
1092 g_return_val_if_fail (HILDON_IS_CAPTION (caption), "");
1093 priv = HILDON_CAPTION_GET_PRIVATE (caption);
1096 return (gchar*) gtk_label_get_text (GTK_LABEL (priv->label));
1100 * hildon_caption_set_separator:
1101 * @caption : a #HildonCaption
1102 * @separator : the separator to use
1104 * Sets the separator character that appears after the label.
1105 * The default seaparator character is ":"
1109 hildon_caption_set_separator (HildonCaption *caption,
1110 const gchar *separator)
1112 g_return_if_fail (HILDON_IS_CAPTION (caption));
1114 g_object_set (G_OBJECT (caption), "separator", separator, NULL);
1118 * hildon_caption_get_separator:
1119 * @caption : a #HildonCaption
1121 * Gets separator string of #HildonCaption
1123 * Returns: the text currently being used as the separator of the caption
1124 * control. The string is owned by the caption control and the caller should
1125 * never free or modify this value.
1128 hildon_caption_get_separator (const HildonCaption *caption)
1130 HildonCaptionPrivate *priv;
1131 g_return_val_if_fail (HILDON_IS_CAPTION (caption), "");
1133 priv = HILDON_CAPTION_GET_PRIVATE (caption);
1136 return priv->separator;
1139 /* Activates the child control
1140 * We have this signal so that if needed an application can
1141 * know when we've been activated (useful for captions with
1143 * FIXME: There never are multiple children. Possibly activate
1144 * signal could be removed entirely? (does anyone use it?)
1147 hildon_caption_activate (GtkWidget *widget)
1149 GtkWidget *child = GTK_BIN (widget)->child;
1150 gtk_widget_grab_focus (child);
1154 hildon_caption_grab_focus (GtkWidget *widget)
1156 gtk_widget_grab_focus (GTK_BIN (widget)->child);
1160 * hildon_caption_set_child_expand:
1161 * @caption : a #HildonCaption
1162 * @expand : gboolean to determine if the child is expandable
1164 * Sets child expandability.
1167 hildon_caption_set_child_expand (HildonCaption *caption,
1170 HildonCaptionPrivate *priv = NULL;
1171 GtkWidget *child = NULL;
1172 g_return_if_fail (HILDON_IS_CAPTION (caption));
1174 priv = HILDON_CAPTION_GET_PRIVATE (caption);
1177 /* Did the setting really change? */
1178 if (priv->expand == expand)
1181 priv->expand = expand;
1182 child = GTK_BIN (caption)->child;
1184 /* We do not have a child, nothing to do */
1185 if (! GTK_IS_WIDGET (child))
1188 if (GTK_WIDGET_VISIBLE (child) && GTK_WIDGET_VISIBLE (caption))
1189 gtk_widget_queue_resize (child);
1191 gtk_widget_child_notify (child, "expand");
1195 * hildon_caption_get_child_expand:
1196 * @caption : a #HildonCaption
1198 * Gets childs expandability.
1200 * Returns: wheter the child is expandable or not.
1203 hildon_caption_get_child_expand (const HildonCaption *caption)
1205 HildonCaptionPrivate *priv = NULL;
1206 g_return_val_if_fail (HILDON_IS_CAPTION (caption), FALSE);
1208 priv = HILDON_CAPTION_GET_PRIVATE (caption);
1211 return priv->expand;
1215 hildon_caption_set_label_text (HildonCaptionPrivate *priv,
1219 g_assert (priv != NULL);
1223 if (priv->separator)
1225 /* Don't duplicate the separator, if the string already contains one */
1226 if (g_str_has_suffix (priv->text, priv->separator))
1229 gtk_label_set_markup (GTK_LABEL (priv->label), priv->text);
1231 gtk_label_set_text (GTK_LABEL (priv->label), priv->text);
1235 /* Append separator and set text */
1236 tmp = g_strconcat( priv->text, priv->separator, NULL );
1239 gtk_label_set_markup (GTK_LABEL (priv->label), tmp);
1241 gtk_label_set_text (GTK_LABEL (priv->label), tmp);
1249 gtk_label_set_markup (GTK_LABEL (priv->label), priv->text);
1251 gtk_label_set_text (GTK_LABEL (priv->label), priv->text);
1256 /* Clear the label */
1258 gtk_label_set_markup (GTK_LABEL (priv->label), "");
1260 gtk_label_set_text (GTK_LABEL (priv->label), "" );
1265 * hildon_caption_set_label_alignment:
1266 * @caption: a #HildonCaption widget
1267 * @alignment: new vertical alignment
1269 * Sets the vertical alignment to be used for the
1270 * text part of the caption. Applications need to
1271 * align the child control themselves.
1275 hildon_caption_set_label_alignment (HildonCaption *caption,
1278 HildonCaptionPrivate *priv;
1280 g_return_if_fail (HILDON_IS_CAPTION (caption));
1282 priv = HILDON_CAPTION_GET_PRIVATE (caption);
1285 g_object_set (priv->label, "yalign", alignment, NULL);
1286 g_object_set (priv->icon_align, "yalign", alignment, NULL);
1291 * hildon_caption_get_label_alignment:
1292 * @caption: a #HildonCaption widget
1294 * Gets current vertical alignment for the text part.
1296 * Returns: vertical alignment
1300 hildon_caption_get_label_alignment (HildonCaption *caption)
1302 HildonCaptionPrivate *priv;
1305 g_return_val_if_fail (HILDON_IS_CAPTION (caption), 0);
1306 priv = HILDON_CAPTION_GET_PRIVATE (caption);
1309 g_object_get (priv->label, "yalign", &result, NULL);