HildonCaption

HildonCaption — A single-child container widget that precedes the contained widget with a field label and an optional icon

Synopsis




enum        HildonCaptionStatus;
enum        HildonCaptionIconPosition;
#define     HILDON_TYPE_CAPTION_STATUS
#define     HILDON_TYPE_CAPTION_ICON_POSITION
GType       hildon_caption_icon_position_get_type
                                            (void);
GType       hildon_caption_get_type         (void);
GtkWidget*  hildon_caption_new              (GtkSizeGroup *group,
                                             const gchar *value,
                                             GtkWidget *control,
                                             GtkWidget *icon,
                                             HildonCaptionStatus flag);
GtkSizeGroup* hildon_caption_get_sizegroup  (const HildonCaption *caption);
void        hildon_caption_set_sizegroup    (const HildonCaption *caption,
                                             GtkSizeGroup *new_group);
gboolean    hildon_caption_is_mandatory     (const HildonCaption *caption);
void        hildon_caption_set_status       (HildonCaption *caption,
                                             HildonCaptionStatus flag);
HildonCaptionStatus hildon_caption_get_status
                                            (const HildonCaption *caption);
void        hildon_caption_set_icon_position
                                            (HildonCaption *caption,
                                             HildonCaptionIconPosition pos);
HildonCaptionIconPosition hildon_caption_get_icon_position
                                            (const HildonCaption *caption);
void        hildon_caption_set_icon_image   (HildonCaption *caption,
                                             GtkWidget *icon);
GtkWidget*  hildon_caption_get_icon_image   (const HildonCaption *caption);
void        hildon_caption_set_label        (HildonCaption *caption,
                                             const gchar *label);
gchar*      hildon_caption_get_label        (const HildonCaption *caption);
void        hildon_caption_set_separator    (HildonCaption *caption,
                                             const gchar *separator);
gchar*      hildon_caption_get_separator    (const HildonCaption *caption);
void        hildon_caption_set_label_alignment
                                            (HildonCaption *caption,
                                             gfloat alignment);
gfloat      hildon_caption_get_label_alignment
                                            (HildonCaption *caption);
GtkWidget*  hildon_caption_get_control      (const HildonCaption *caption);
void        hildon_caption_set_control      (HildonCaption *caption,
                                             GtkWidget *control);
void        hildon_caption_set_child_expand (HildonCaption *caption,
                                             gboolean expand);
gboolean    hildon_caption_get_child_expand (const HildonCaption *caption);

Description

HildonCaption is a single-child container widget that precedes the contained widget with a field label and an optional icon. It allows grouping of several controls together. When a captioned widget has focus, both widget and caption label are displayed with active focus.


#include <hildon-widgets/hildon-caption.h>

#include <gtk/gtkwidget.h>
#include <gtk/gtkvbox.h>
#include <gtk/gtkhbox.h>
#include <gtk/gtkcombobox.h>
#include <gtk/gtkcomboboxentry.h>
#include <gtk/gtkentry.h>
#include <gtk/gtkscrolledwindow.h>
#include <gtk/gtkimage.h>
#include <gtk/gtkcheckbutton.h>
#include <glib/glist.h>
#include <gtk/gtktogglebutton.h>
#include <gtk/gtklabel.h>

#include <libintl.h>
#define _(String) gettext(String)

static void destroy_callback( GtkWidget *widget );
void _testCaptionControl(GtkWidget *parent, gchar **help);

gchar *hildon_icons[] = { "hildon-file-open",
	"gtk-ok",
	"gtk-refresh",
	"gtk-remove"
};

const int num_icons = sizeof( hildon_icons ) / sizeof( gchar * );

static GList *caption_list = NULL;

static void text_changed_callback( HildonCaption *caption, gpointer user_data )
{
	hildon_caption_set_label( caption, gtk_entry_get_text( user_data ) );
}

static void icon_toggled_callback( HildonCaption *caption, gpointer user_data )
{
	GtkWidget *phone_image = NULL;
	GList *cur = caption_list;
	int i = 0;
	while ( cur )
	{
		if ( !hildon_caption_get_icon_image( HILDON_CAPTION(cur->data) ) )
		{
			phone_image = gtk_image_new_from_stock( hildon_icons[i], GTK_ICON_SIZE_SMALL_TOOLBAR );
		}

		hildon_caption_set_icon_image( HILDON_CAPTION( cur->data), phone_image );

		cur = cur->next;
		if ( ++i >= num_icons )
		{
			i = 0;
		}

	}
}
static void mandatory_toggled_callback( HildonCaption *caption, gpointer user_data )
{
	GList *cur = caption_list;
	int i = 0;
	while ( cur )
	{
		if ( hildon_caption_is_mandatory( HILDON_CAPTION(cur->data) ) )
		{
			hildon_caption_set_status( HILDON_CAPTION(cur->data), HILDON_CAPTION_OPTIONAL );
		}
		else
		{
			hildon_caption_set_status( HILDON_CAPTION(cur->data), HILDON_CAPTION_MANDATORY );
		}

		cur = cur->next;
		if ( ++i > num_icons )
		{
			i = 0;
		}
	}
}

static void destroy_callback( GtkWidget *widget )
{
	g_print( "Destroying the empty label\n" );
}

void _testCaptionControl(GtkWidget *parent, gchar **help)
{

	GtkWidget *control = NULL;
	GtkWidget *caption_control = NULL;
	GtkWidget *vbox = gtk_vbox_new( FALSE, 0 );
	GtkWidget *top_vbox = GTK_WIDGET(gtk_vbox_new( FALSE, 0 ));
	GtkWidget *hbox = GTK_WIDGET(gtk_hbox_new( FALSE, 0 ));
	GtkSizeGroup *group= GTK_SIZE_GROUP( gtk_size_group_new( GTK_SIZE_GROUP_HORIZONTAL ) );

	GtkWidget *some_image = gtk_image_new_from_file( "../share/themes/commonimages/question.png" );

	control = gtk_entry_new();
	caption_control = hildon_caption_new( group, _("Man Entry"), control,
			NULL, HILDON_CAPTION_MANDATORY);
	gtk_box_pack_start( GTK_BOX( top_vbox ), caption_control, FALSE, FALSE, 0 );

	g_signal_connect( G_OBJECT( control ), "destroy", G_CALLBACK( destroy_callback ), NULL );

	control = gtk_entry_new();
	caption_control = hildon_caption_new( group, _("O grow"), control,
			NULL, HILDON_CAPTION_OPTIONAL);
	g_signal_connect_swapped( control, "changed",
			G_CALLBACK( text_changed_callback ), caption_control );
	gtk_box_pack_start( GTK_BOX( top_vbox ), caption_control, FALSE, FALSE, 0 );

	gtk_box_pack_end( GTK_BOX( hbox ), some_image, FALSE, FALSE, 0 );
	gtk_box_pack_end( GTK_BOX( hbox ), top_vbox, TRUE, TRUE, 0 );

	gtk_box_pack_start( GTK_BOX( vbox ), hbox, FALSE, FALSE, 0 );

	control = gtk_combo_box_entry_new_text();
	gtk_combo_box_append_text(GTK_COMBO_BOX(control), _("First Item"));
	gtk_combo_box_append_text(GTK_COMBO_BOX(control), _("Second Item"));
	gtk_combo_box_append_text(GTK_COMBO_BOX(control), _("Third Item"));
	gtk_combo_box_append_text(GTK_COMBO_BOX(control), _("Fourth Item"));
	gtk_combo_box_append_text(GTK_COMBO_BOX(control), _("Fifth Item"));
	caption_control = hildon_caption_new( group, _("M Com"), control,
			NULL, HILDON_CAPTION_MANDATORY);
	gtk_box_pack_start( GTK_BOX( vbox ), caption_control, FALSE, FALSE, 0 );
	caption_list = g_list_append( caption_list, (gpointer)caption_control );

	control = gtk_label_new("This text should not be focusable");
	caption_control = hildon_caption_new (group, _("UFLabel"), control, NULL, HILDON_CAPTION_OPTIONAL);
	gtk_box_pack_start( GTK_BOX( vbox ), caption_control, FALSE, FALSE, 0 );
	caption_list = g_list_append (caption_list, (gpointer) caption_control );

	control = gtk_combo_box_new_text(); /* entry */

	gtk_combo_box_append_text(GTK_COMBO_BOX(control), _("Tango"));
	gtk_combo_box_append_text(GTK_COMBO_BOX(control), _("Mambo"));
	gtk_combo_box_append_text(GTK_COMBO_BOX(control), _("Merengue"));
	gtk_combo_box_append_text(GTK_COMBO_BOX(control), _("Salsa"));
	caption_control = hildon_caption_new( group, _("O Option Menu"), control,
			NULL, HILDON_CAPTION_MANDATORY);
	gtk_box_pack_start( GTK_BOX( vbox ), caption_control, FALSE, FALSE, 0 );
	caption_list = g_list_append( caption_list, (gpointer)caption_control );


	control = gtk_check_button_new();
	caption_control = hildon_caption_new( group, _("show icon"), control,
			NULL, HILDON_CAPTION_MANDATORY);
	g_signal_connect_swapped( control, "toggled",
			G_CALLBACK( icon_toggled_callback ), caption_control );
	gtk_box_pack_start( GTK_BOX( vbox ), caption_control, FALSE, FALSE, 0 );
	caption_list = g_list_append( caption_list, (gpointer)caption_control );

	control = gtk_check_button_new();
	caption_control = hildon_caption_new( group, _("toggle status"), control,
			NULL, HILDON_CAPTION_OPTIONAL);
	g_signal_connect_swapped( control, "toggled",
			G_CALLBACK( mandatory_toggled_callback ), caption_control );
	gtk_box_pack_start( GTK_BOX( vbox ), caption_control, FALSE, FALSE, 0 );
	caption_list = g_list_append( caption_list, (gpointer)caption_control );


	gtk_container_add( GTK_CONTAINER( parent ), vbox );

	gtk_widget_show_all( parent );

	if (help)
		*help = g_strdup ("");

}

Details

enum HildonCaptionStatus

typedef enum /*< skip >*/
{
    HILDON_CAPTION_OPTIONAL = 0,
    HILDON_CAPTION_MANDATORY
} HildonCaptionStatus;

Keys to set the HildonCaption to be optional or mandatory.

`HILDON_CAPTION_OPTIONAL`	Optional.
`HILDON_CAPTION_MANDATORY`	Mandatory.

enum HildonCaptionIconPosition

typedef enum /*< skip >*/
{
    HILDON_CAPTION_POSITION_LEFT = 0,
    HILDON_CAPTION_POSITION_RIGHT
} HildonCaptionIconPosition;

Keys to set the icon placement in HildonCaption.

`HILDON_CAPTION_POSITION_LEFT`	Show the icon on the left side.
`HILDON_CAPTION_POSITION_RIGHT`	Show the icon on the right side.

Since 0.14.5

HILDON_TYPE_CAPTION_STATUS

#define HILDON_TYPE_CAPTION_STATUS (hildon_caption_status_get_type ())

HILDON_TYPE_CAPTION_ICON_POSITION

#define HILDON_TYPE_CAPTION_ICON_POSITION (hildon_caption_icon_position_get_type ())

hildon_caption_icon_position_get_type ()

GType       hildon_caption_icon_position_get_type
                                            (void);

Returns :

hildon_caption_get_type ()

GType       hildon_caption_get_type         (void);

Initialises, and returns the type of a hildon caption.

Returns: GType of HildonCaption

Returns :

hildon_caption_new ()

GtkWidget*  hildon_caption_new              (GtkSizeGroup *group,
                                             const gchar *value,
                                             GtkWidget *control,
                                             GtkWidget *icon,
                                             HildonCaptionStatus flag);

Creates a new instance of hildon_caption widget, with a specific control and image. Note: Clicking on a focused caption will trigger the activate signal. The default behaviour for the caption's activate signal is to call gtk_widget_activate on it's control.

Returns : a GtkWidget pointer of Caption

`group` :	a GtkSizeGroup for controlling the size of related captions, Can be NULL
`value` :	the caption text to accompany the text entry. The widget makes a copy of this text.
`control` :	the control that is to be captioned
`icon` :	an icon to accompany the label - can be NULL in which case no icon is displayed
`flag` :	indicates whether this captioned control is mandatory or optional
Returns :

hildon_caption_get_sizegroup ()

GtkSizeGroup* hildon_caption_get_sizegroup  (const HildonCaption *caption);

Warning

hildon_caption_get_sizegroup is deprecated and should not be used in newly-written code. Use g_object_get, property :size-group

Query given captioned control for the GtkSizeGroup assigned to it.

Returns : a GtkSizeGroup

`caption` :	a HildonCaption
Returns :

hildon_caption_set_sizegroup ()

void        hildon_caption_set_sizegroup    (const HildonCaption *caption,
                                             GtkSizeGroup *new_group);

Warning

hildon_caption_set_sizegroup is deprecated and should not be used in newly-written code. use g_object_set, property :size-group

Sets a GtkSizeGroup of a given captioned control.

`caption` :	a HildonCaption
`new_group` :	a GtkSizeGroup

hildon_caption_is_mandatory ()

gboolean    hildon_caption_is_mandatory     (const HildonCaption *caption);

Query HildonCaption whether this captioned control is a mandatory one.

Returns : is this captioned control a mandatory one?

`caption` :	a HildonCaption
Returns :

hildon_caption_set_status ()

void        hildon_caption_set_status       (HildonCaption *caption,
                                             HildonCaptionStatus flag);

Sets HildonCaption status.

`caption` :	a HildonCaption
`flag` :	one of the values from HildonCaptionStatus

hildon_caption_get_status ()

HildonCaptionStatus hildon_caption_get_status
                                            (const HildonCaption *caption);

Gets HildonCaption status.

Returns : one of the values from HildonCaptionStatus

`caption` :	a HildonCaption
Returns :

hildon_caption_set_icon_position ()

void        hildon_caption_set_icon_position
                                            (HildonCaption *caption,
                                             HildonCaptionIconPosition pos);

Sets HildonCaption icon position.

`caption` :	a HildonCaption
`pos` :	one of the values from HildonCaptionIconPosition

Since 0.14.5

hildon_caption_get_icon_position ()

HildonCaptionIconPosition hildon_caption_get_icon_position
                                            (const HildonCaption *caption);

Gets HildonCaption icon position.

Returns : one of the values from HildonCaptionIconPosition.

`caption` :	a HildonCaption
Returns :

Since 0.14.5

hildon_caption_set_icon_image ()

void        hildon_caption_set_icon_image   (HildonCaption *caption,
                                             GtkWidget *icon);

Sets the icon to be used by this hildon_caption widget.

`caption` :	a HildonCaption
`icon` :	the GtkImage to use as the icon. calls gtk_widget_show on the icon if !GTK_WIDGET_VISIBLE(icon)

hildon_caption_get_icon_image ()

GtkWidget*  hildon_caption_get_icon_image   (const HildonCaption *caption);

Gets icon of HildonCaption

Returns : the GtkImage that is being used as the icon by the hildon_caption, or NULL if no icon is in use

`caption` :	a HildonCaption
Returns :

hildon_caption_set_label ()

void        hildon_caption_set_label        (HildonCaption *caption,
                                             const gchar *label);

Sets the label text that appears before the control. Separator character is added to the end of the label string. By default the separator is ":".

`caption` :	a HildonCaption
`label` :	the text to use

hildon_caption_get_label ()

gchar*      hildon_caption_get_label        (const HildonCaption *caption);

Gets label of HildonCaption

Returns : the text currently being used as the label of the caption control. The string is owned by the label and the caller should never free or modify this value.

`caption` :	a HildonCaption
Returns :

hildon_caption_set_separator ()

void        hildon_caption_set_separator    (HildonCaption *caption,
                                             const gchar *separator);

Sets the separator character that appears after the label. The default seaparator character is ":" separately.

`caption` :	a HildonCaption
`separator` :	the separator to use

hildon_caption_get_separator ()

gchar*      hildon_caption_get_separator    (const HildonCaption *caption);

Gets separator string of HildonCaption

Returns : the text currently being used as the separator of the caption control. The string is owned by the caption control and the caller should never free or modify this value.

`caption` :	a HildonCaption
Returns :

hildon_caption_set_label_alignment ()

void        hildon_caption_set_label_alignment
                                            (HildonCaption *caption,
                                             gfloat alignment);

Sets the vertical alignment to be used for the text part of the caption. Applications need to align the child control themselves.

`caption` :	a HildonCaption widget
`alignment` :	new vertical alignment

Since 0.12.0

hildon_caption_get_label_alignment ()

gfloat      hildon_caption_get_label_alignment
                                            (HildonCaption *caption);

Gets current vertical alignment for the text part.

`caption` :	a HildonCaption widget
Returns :	vertical alignment

Since 0.12.0

hildon_caption_get_control ()

GtkWidget*  hildon_caption_get_control      (const HildonCaption *caption);

Warning

hildon_caption_get_control is deprecated and should not be used in newly-written code. use gtk_bin_get_child instead

Gets caption's control.

Returns : a GtkWidget

`caption` :	a HildonCaption
Returns :

hildon_caption_set_control ()

void        hildon_caption_set_control      (HildonCaption *caption,
                                             GtkWidget *control);

Warning

hildon_caption_set_control is deprecated and should not be used in newly-written code. use gtk_container_add

Sets the control of the caption. The old control will be destroyed, unless the caller has added a reference to it. Function unparents the old control (if there is one) and adds the new control.

`caption` :	a HildonCaption
`control` :	the control to use. Control should not be NULL.

hildon_caption_set_child_expand ()

void        hildon_caption_set_child_expand (HildonCaption *caption,
                                             gboolean expand);

Sets child expandability.

`caption` :	a HildonCaption
`expand` :	gboolean to determine is the child expandable

hildon_caption_get_child_expand ()

gboolean    hildon_caption_get_child_expand (const HildonCaption *caption);

Gets childs expandability.

Returns : wheter the child is expandable or not.

`caption` :	a HildonCaption
Returns :