## GtkFrame

GtkFrame — A bin with a decorative frame and optional label

## Synopsis

    #include <gtk/gtk.h>

    struct              GtkFrame;
    GtkWidget *         gtk_frame_new                       (const gchar *label);
    void                gtk_frame_set_label                 (GtkFrame *frame,
                                                             const gchar *label);
    void                gtk_frame_set_label_widget          (GtkFrame *frame,
                                                             GtkWidget *label_widget);
    void                gtk_frame_set_label_align           (GtkFrame *frame,
                                                             gfloat xalign,
                                                             gfloat yalign);
    void                gtk_frame_set_shadow_type           (GtkFrame *frame,
                                                             GtkShadowType type);
    const gchar *       gtk_frame_get_label                 (GtkFrame *frame);
    void                gtk_frame_get_label_align           (GtkFrame *frame,
                                                             gfloat *xalign,
                                                             gfloat *yalign);
    GtkWidget *         gtk_frame_get_label_widget          (GtkFrame *frame);
    GtkShadowType       gtk_frame_get_shadow_type           (GtkFrame *frame);

## Object Hierarchy

      GObject
       +----GInitiallyUnowned
             +----GtkWidget
                   +----GtkContainer
                         +----GtkBin
                               +----GtkFrame
                                     +----GtkAspectFrame

## Implemented Interfaces

GtkFrame implements AtkImplementorIface and GtkBuildable.

## Properties

      "label"                    gchar*                : Read / Write
      "label-widget"             GtkWidget*            : Read / Write
      "label-xalign"             gfloat                : Read / Write
      "label-yalign"             gfloat                : Read / Write
      "shadow-type"              GtkShadowType         : Read / Write

## Description

The frame widget is a Bin that surrounds its child with a decorative frame and an optional label. If present, the label is drawn in a gap in the top side of the frame. The position of the label can be controlled with `gtk_frame_set_label_align()`.

### GtkFrame as GtkBuildable

The GtkFrame implementation of the GtkBuildable interface supports placing a child in the label position by specifying "label" as the "type" attribute of a <child> element. A normal content child can be specified without specifying a <child> type attribute.

Example 94. A UI definition fragment with GtkFrame

    1
    2
    3
    4
    5
    6
    7
    8

    <object class="GtkFrame">
      <child type="label">
        <object class="GtkLabel" id="frame-label"/>
      </child>
      <child>
        <object class="GtkEntry" id="frame-content"/>
      </child>
    </object>

## Details

### struct GtkFrame

    struct GtkFrame;

### gtk_frame_new ()

    GtkWidget *         gtk_frame_new                       (const gchar *label);

Creates a new GtkFrame, with optional label `label`. If `label` is `NULL`, the label is omitted.

`label` : | the text to use as the label of the frame
Returns : | a new GtkFrame widget

### gtk_frame_set_label ()

    void                gtk_frame_set_label                 (GtkFrame *frame,
                                                             const gchar *label);

Sets the text of the label. If `label` is `NULL`, the current label is removed.

`frame` : | a GtkFrame
`label` : | the text to use as the label of the frame. [allow-none]

### gtk_frame_set_label_widget ()

    void                gtk_frame_set_label_widget          (GtkFrame *frame,
                                                             GtkWidget *label_widget);

Sets the label widget for the frame. This is the widget that will appear embedded in the top edge of the frame as a title.

`frame` : | a GtkFrame
`label_widget` : | the new label widget

### gtk_frame_set_label_align ()

    void                gtk_frame_set_label_align           (GtkFrame *frame,
                                                             gfloat xalign,
                                                             gfloat yalign);

Sets the alignment of the frame widget's label. The default values for a newly created frame are 0.0 and 0.5.

`frame` : | a GtkFrame
`xalign` : | The position of the label along the top edge of the widget. A value of 0.0 represents left alignment; 1.0 represents right alignment.
`yalign` : | The y alignment of the label. A value of 0.0 aligns under the frame; 1.0 aligns above the frame. If the values are exactly 0.0 or 1.0 the gap in the frame won't be painted because the label will be completely above or below the frame.

### gtk_frame_set_shadow_type ()

    void                gtk_frame_set_shadow_type           (GtkFrame *frame,
                                                             GtkShadowType type);

Sets the shadow type for `frame`.

`frame` : | a GtkFrame
`type` : | the new GtkShadowType

### gtk_frame_get_label ()

    const gchar *       gtk_frame_get_label                 (GtkFrame *frame);

If the frame's label widget is a GtkLabel, returns the text in the label widget. (The frame will have a GtkLabel for the label widget if a non-`NULL` argument was passed to `gtk_frame_new()`.)

`frame` : | a GtkFrame
Returns : | the text in the label, or `NULL` if there was no label widget or the lable widget was not a GtkLabel. This string is owned by GTK+ and must not be modified or freed.

### gtk_frame_get_label_align ()

    void                gtk_frame_get_label_align           (GtkFrame *frame,
                                                             gfloat *xalign,
                                                             gfloat *yalign);

Retrieves the X and Y alignment of the frame's label. See `gtk_frame_set_label_align()`.

`frame` : | a GtkFrame
`xalign` : | location to store X alignment of frame's label, or `NULL`. [out][allow-none]
`yalign` : | location to store X alignment of frame's label, or `NULL`. [out][allow-none]

### gtk_frame_get_label_widget ()

    GtkWidget *         gtk_frame_get_label_widget          (GtkFrame *frame);

Retrieves the label widget for the frame. See `gtk_frame_set_label_widget()`.

`frame` : | a GtkFrame
Returns : | the label widget, or `NULL` if there is none. [transfer none]

### gtk_frame_get_shadow_type ()

    GtkShadowType       gtk_frame_get_shadow_type           (GtkFrame *frame);

Retrieves the shadow type of the frame. See `gtk_frame_set_shadow_type()`.

`frame` : | a GtkFrame
Returns : | the current shadow type of the frame.

## Property Details

### The `"label"` property

      "label"                    gchar*                : Read / Write

Text of the frame's label.

Default value: NULL

### The `"label-widget"` property

      "label-widget"             GtkWidget*            : Read / Write

A widget to display in place of the usual frame label.

### The `"label-xalign"` property

      "label-xalign"             gfloat                : Read / Write

The horizontal alignment of the label.

Allowed values: [0,1]

Default value: 0

### The `"label-yalign"` property

      "label-yalign"             gfloat                : Read / Write

The vertical alignment of the label.

Allowed values: [0,1]

Default value: 0.5

### The `"shadow-type"` property

      "shadow-type"              GtkShadowType         : Read / Write

Appearance of the frame border.

Default value: GTK_SHADOW_ETCHED_IN