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;
                    HildonCaption;
GtkWidget*          hildon_caption_new                  (GtkSizeGroup *group,
                                                         const gchar *value,
                                                         GtkWidget *control,
                                                         GtkWidget *icon,
                                                         HildonCaptionStatus flag);
GtkSizeGroup*       hildon_caption_get_size_group       (const HildonCaption *caption);
void                hildon_caption_set_size_group       (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);
void                hildon_caption_set_child_expand     (HildonCaption *caption,
                                                         gboolean expand);
gboolean            hildon_caption_get_child_expand     (const HildonCaption *caption);
void                hildon_caption_set_label_markup     (HildonCaption *caption,
                                                         const gchar *markup);

Object Hierarchy

  GObject
   +----GInitiallyUnowned
         +----GtkObject
               +----GtkWidget
                     +----GtkContainer
                           +----GtkBin
                                 +----GtkEventBox
                                       +----HildonCaption

Implemented Interfaces

HildonCaption implements AtkImplementorIface and GtkBuildable.

Properties

  "icon"                     GtkWidget*            : Read / Write
  "icon-position"            HildonCaptionIconPosition  : Read / Write
  "label"                    gchar*                : Read / Write
  "markup"                   gchar*                : Write
  "separator"                gchar*                : Read / Write
  "size-group"               GtkSizeGroup*         : Read / Write
  "status"                   HildonCaptionStatus   : Read / Write

Child Properties

  "expand"                   gboolean              : Read / Write

Signals

  "activate"                                       : Run First / Action

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.

Details

enum HildonCaptionStatus

typedef enum
{
    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
{
    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.

HildonCaption

typedef struct _HildonCaption HildonCaption;

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.

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 : a GtkWidget pointer of Caption

hildon_caption_get_size_group ()

GtkSizeGroup*       hildon_caption_get_size_group       (const HildonCaption *caption);

Query given captioned control for the GtkSizeGroup assigned to it.

caption : a HildonCaption
Returns : a GtkSizeGroup

hildon_caption_set_size_group ()

void                hildon_caption_set_size_group       (const HildonCaption *caption,
                                                         GtkSizeGroup *new_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.

caption : a HildonCaption
Returns : is this captioned control a mandatory one?

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.

caption : a HildonCaption
Returns : one of the values from HildonCaptionStatus

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

hildon_caption_get_icon_position ()

HildonCaptionIconPosition hildon_caption_get_icon_position
                                                        (const HildonCaption *caption);

Gets HildonCaption icon position.

caption : a HildonCaption
Returns : one of the values from HildonCaptionIconPosition.

hildon_caption_set_icon_image ()

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

Sets the icon image widget 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

caption : a HildonCaption
Returns : the GtkImage widget that is being used as the icon by the hildon_caption, or NULL if no icon image is in use.

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

caption : a 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.

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

caption : a 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.

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

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

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 if the child is expandable

hildon_caption_get_child_expand ()

gboolean            hildon_caption_get_child_expand     (const HildonCaption *caption);

Gets childs expandability.

caption : a HildonCaption
Returns : wheter the child is expandable or not.

hildon_caption_set_label_markup ()

void                hildon_caption_set_label_markup     (HildonCaption *caption,
                                                         const gchar *markup);

Sets the label markup text that appears before the control. It acts like hildon_caption_set_label but is using the markup text that allows to specify text properties such as bold or italic.

caption : a HildonCaption
markup : the markup text to use

Property Details

The "icon" property

  "icon"                     GtkWidget*            : Read / Write

The icon shown on the caption area.

The "icon-position" property

  "icon-position"            HildonCaptionIconPosition  : Read / Write

If the icon is positioned on the left or right side.

Default value: HILDON_CAPTION_POSITION_RIGHT

The "label" property

  "label"                    gchar*                : Read / Write

Caption label.

Default value: NULL

The "markup" property

  "markup"                   gchar*                : Write

Caption markup. Mutually exclusive with label.

Default value: NULL

The "separator" property

  "separator"                gchar*                : Read / Write

The current separator.

Default value: "ecdg_ti_caption_separator"

The "size-group" property

  "size-group"               GtkSizeGroup*         : Read / Write

Current size group the caption is in.

The "status" property

  "status"                   HildonCaptionStatus   : Read / Write

Mandatory or optional status.

Default value: HILDON_CAPTION_OPTIONAL

Child Property Details

The "expand" child property

  "expand"                   gboolean              : Read / Write

Same as GtkBox expand. Wheter the child should be expanded or not.

Default value: FALSE

Signal Details

The "activate" signal

void                user_function                      (HildonCaption *hildoncaption,
                                                        gpointer       user_data)          : Run First / Action

hildoncaption : the object which received the signal.
user_data : user data set when the signal handler was connected.
Generated by GTK-Doc V1.10