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 :