CtkFrame: CTK+ 3 Reference Manual

## CtkFrame CtkFrame — A bin with a decorative frame and optional label |

## Functions

CtkWidget * | ctk_frame_new ()
void | ctk_frame_set_label ()
void | ctk_frame_set_label_widget ()
void | ctk_frame_set_label_align ()
void | ctk_frame_set_shadow_type ()
const gchar * | ctk_frame_get_label ()
void | ctk_frame_get_label_align ()
CtkWidget * | ctk_frame_get_label_widget ()
CtkShadowType | ctk_frame_get_shadow_type ()

## Properties

char * | label | Read / Write
CtkWidget * | label-widget | Read / Write
float | label-xalign | Read / Write
float | label-yalign | Read / Write
CtkShadowType | shadow-type | Read / Write

## Types and Values

struct | CtkFrame
struct | CtkFrameClass

## Object Hierarchy

        GObject
        ╰── GInitiallyUnowned
            ╰── CtkWidget
                ╰── CtkContainer
                    ╰── CtkBin
                        ╰── CtkFrame
                            ╰── CtkAspectFrame

## Implemented Interfaces

CtkFrame implements AtkImplementorIface and CtkBuildable.

## Includes

    #include <ctk/ctk.h>

## 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 `ctk_frame_set_label_align()`.

### CtkFrame as CtkBuildable

The CtkFrame implementation of the CtkBuildable 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.

An example of a UI definition fragment with CtkFrame:

    1
    2
    3
    4
    5
    6
    7
    8
    <object class="CtkFrame">
      <child type="label">
        <object class="CtkLabel" id="frame-label"/>
      </child>
      <child>
        <object class="CtkEntry" id="frame-content"/>
      </child>
    </object>

### CSS nodes

    1
    2
    3
    4
    frame
    ├── border[.flat]
    ├── <label widget>
    ╰── <child>

CtkFrame has a main CSS node named “frame” and a subnode named “border”. The “border” node is used to draw the visible border. You can set the appearance of the border using CSS properties like “border-style” on the “border” node.

The border node can be given the style class “.flat”, which is used by themes to disable drawing of the border. To do this from code, call `ctk_frame_set_shadow_type()` with `CTK_SHADOW_NONE` to add the “.flat” class or any other shadow type to remove it.

## Functions

### ctk_frame_new ()

    CtkWidget *
    ctk_frame_new (const gchar *label);

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

#### Parameters

label | the text to use as the label of the frame. | [allow-none]

#### Returns

a new CtkFrame widget

### ctk_frame_set_label ()

    void
    ctk_frame_set_label (CtkFrame *frame,
                         const gchar *label);

Removes the current “label-widget”. If `label` is not `NULL`, creates a new CtkLabel with that text and adds it as the “label-widget”.

#### Parameters

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

### ctk_frame_set_label_widget ()

    void
    ctk_frame_set_label_widget (CtkFrame *frame,
                                CtkWidget *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.

#### Parameters

frame | a CtkFrame |
label_widget | the new label widget. | [nullable]

### ctk_frame_set_label_align ()

    void
    ctk_frame_set_label_align (CtkFrame *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.

#### Parameters

frame | a CtkFrame |
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. |

### ctk_frame_set_shadow_type ()

    void
    ctk_frame_set_shadow_type (CtkFrame *frame,
                               CtkShadowType type);

Sets the “shadow-type” for `frame` , i.e. whether it is drawn without (`CTK_SHADOW_NONE`) or with (other values) a visible border. Values other than `CTK_SHADOW_NONE` are treated identically by CtkFrame. The chosen type is applied by removing or adding the .flat class to the CSS node named border.

#### Parameters

frame | a CtkFrame |
type | the new CtkShadowType |

### ctk_frame_get_label ()

    const gchar *
    ctk_frame_get_label (CtkFrame *frame);

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

#### Parameters

frame | a CtkFrame |

#### Returns

the text in the label, or `NULL` if there was no label widget or the lable widget was not a CtkLabel. This string is owned by CTK+ and must not be modified or freed.

[nullable]

### ctk_frame_get_label_align ()

    void
    ctk_frame_get_label_align (CtkFrame *frame,
                               gfloat *xalign,
                               gfloat *yalign);

Retrieves the X and Y alignment of the frame’s label. See `ctk_frame_set_label_align()`.

#### Parameters

frame | a CtkFrame |
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]

### ctk_frame_get_label_widget ()

    CtkWidget *
    ctk_frame_get_label_widget (CtkFrame *frame);

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

#### Parameters

frame | a CtkFrame |

#### Returns

the label widget, or `NULL` if there is none.

[nullable][transfer none]

### ctk_frame_get_shadow_type ()

    CtkShadowType
    ctk_frame_get_shadow_type (CtkFrame *frame);

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

#### Parameters

frame | a CtkFrame |

#### Returns

the current shadow type of the frame.

## Types and Values

### struct CtkFrame

    struct CtkFrame;

### struct CtkFrameClass

    struct CtkFrameClass {
      CtkBinClass parent_class;

      void (*compute_child_allocation) (CtkFrame *frame,
                                        CtkAllocation *allocation);
    };

#### Members

`compute_child_allocation` () |  |

## Property Details

### The `“label”` property

      “label”                    char *

Text of the frame's label.

Owner: CtkFrame

Flags: Read / Write

Default value: NULL

### The `“label-widget”` property

      “label-widget”             CtkWidget *

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

Owner: CtkFrame

Flags: Read / Write

### The `“label-xalign”` property

      “label-xalign”             float

The horizontal alignment of the label.

Owner: CtkFrame

Flags: Read / Write

Allowed values: [0,1]

Default value: 0

### The `“label-yalign”` property

      “label-yalign”             float

The vertical alignment of the label.

Owner: CtkFrame

Flags: Read / Write

Allowed values: [0,1]

Default value: 0.5

### The `“shadow-type”` property

      “shadow-type”              CtkShadowType

Appearance of the frame border.

Owner: CtkFrame

Flags: Read / Write

Default value: CTK_SHADOW_ETCHED_IN