HildonCaption

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

Synopsis


#include <hildon/hildon.h>

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 HildonCaption 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 its control.

group : a GtkSizeGroup for controlling the size of related captions or 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 or NULL in case no icon should be displayed.
flag : indicates whether this captioned control is mandatory or optional.
Returns : a new HildonCaption

hildon_caption_get_size_group ()

GtkSizeGroup*       hildon_caption_get_size_group       (const HildonCaption *caption);

Queries 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);

Queries whether caption is mandatory.

caption : a HildonCaption
Returns : Whether this captioned control is mandatory.

hildon_caption_set_status ()

void                hildon_caption_set_status           (HildonCaption *caption,
                                                         HildonCaptionStatus flag);

Sets caption's status.

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

hildon_caption_get_status ()

HildonCaptionStatus hildon_caption_get_status           (const HildonCaption *caption);

Gets caption's 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 caption's 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 caption's 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 caption.

caption : a HildonCaption
icon : the GtkImage to use as the icon. Calls gtk_widget_show() on the icon if it is not visible.

hildon_caption_get_icon_image ()

GtkWidget*          hildon_caption_get_icon_image       (const HildonCaption *caption);

Gets the icon image widget used by caption.

caption : a HildonCaption
Returns : the GtkImage widget that is being used as the icon by 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 ":". See also hildon_caption_set_separator().

caption : a HildonCaption
label : the text to use

hildon_caption_get_label ()

gchar*              hildon_caption_get_label            (const HildonCaption *caption);

Gets the label of caption

caption : a HildonCaption
Returns : the text currently being used as the label of caption. 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 ":".

caption : a HildonCaption
separator : the separator to use

hildon_caption_get_separator ()

gchar*              hildon_caption_get_separator        (const HildonCaption *caption);

Gets the separator string of caption

caption : a HildonCaption
Returns : the text currently being used as the separator of the caption control. The string is owned by caption 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 : whether 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