CtkOverlay: CTK+ 3 Reference Manual

## CtkOverlay CtkOverlay — A container which overlays widgets on top of each other |

## Functions

CtkWidget * | ctk_overlay_new ()
void | ctk_overlay_add_overlay ()
void | ctk_overlay_reorder_overlay ()
gboolean | ctk_overlay_get_overlay_pass_through ()
void | ctk_overlay_set_overlay_pass_through ()

## Signals

gboolean | get-child-position | Run Last

## Types and Values

struct | CtkOverlay
struct | CtkOverlayClass

## Object Hierarchy

        GObject
        ╰── GInitiallyUnowned
            ╰── CtkWidget
                ╰── CtkContainer
                    ╰── CtkBin
                        ╰── CtkOverlay

## Implemented Interfaces

CtkOverlay implements AtkImplementorIface and CtkBuildable.

## Includes

    #include <ctk/ctk.h>

## Description

CtkOverlay is a container which contains a single main child, on top of which it can place “overlay” widgets. The position of each overlay widget is determined by its “halign” and “valign” properties. E.g. a widget with both alignments set to `CTK_ALIGN_START` will be placed at the top left corner of the CtkOverlay container, whereas an overlay with halign set to `CTK_ALIGN_CENTER` and valign set to `CTK_ALIGN_END` will be placed a the bottom edge of the CtkOverlay, horizontally centered. The position can be adjusted by setting the margin properties of the child to non-zero values.

More complicated placement of overlays is possible by connecting to the “get-child-position” signal.

An overlay’s minimum and natural sizes are those of its main child. The sizes of overlay children are not considered when measuring these preferred sizes.

### CtkOverlay as CtkBuildable

The CtkOverlay implementation of the CtkBuildable interface supports placing a child as an overlay by specifying “overlay” as the “type” attribute of a `<child>` element.

### CSS nodes

CtkOverlay has a single CSS node with the name “overlay”. Overlay children whose alignments cause them to be positioned at an edge get the style classes “.left”, “.right”, “.top”, and/or “.bottom” according to their position.

## Functions

### ctk_overlay_new ()

    CtkWidget *
    ctk_overlay_new (void);

Creates a new CtkOverlay.

#### Returns

a new CtkOverlay object.

Since: 3.2

### ctk_overlay_add_overlay ()

    void
    ctk_overlay_add_overlay (CtkOverlay *overlay,
                             CtkWidget *widget);

Adds `widget` to `overlay` .

The widget will be stacked on top of the main widget added with `ctk_container_add()`.

The position at which `widget` is placed is determined from its “halign” and “valign” properties.

#### Parameters

overlay | a CtkOverlay |
widget | a CtkWidget to be added to the container |

Since: 3.2

### ctk_overlay_reorder_overlay ()

    void
    ctk_overlay_reorder_overlay (CtkOverlay *overlay,
                                 CtkWidget *child,
                                 int index_);

Moves `child` to a new `index` in the list of `overlay` children. The list contains overlays in the order that these were added to `overlay` by default. See also “index”.

A widget’s index in the `overlay` children list determines which order the children are drawn if they overlap. The first child is drawn at the bottom. It also affects the default focus chain order.

#### Parameters

overlay | a CtkOverlay |
child | the overlaid CtkWidget to move |
index_ | the new index for `child` in the list of overlay children of `overlay` , starting from 0. If negative, indicates the end of the list |

Since: 3.18

### ctk_overlay_get_overlay_pass_through ()

    gboolean
    ctk_overlay_get_overlay_pass_through (CtkOverlay *overlay,
                                          CtkWidget *widget);

Convenience function to get the value of the “pass-through” child property for `widget` .

#### Parameters

overlay | a CtkOverlay |
widget | an overlay child of CtkOverlay |

#### Returns

whether the widget is a pass through child.

Since: 3.18

### ctk_overlay_set_overlay_pass_through ()

    void
    ctk_overlay_set_overlay_pass_through (CtkOverlay *overlay,
                                          CtkWidget *widget,
                                          gboolean pass_through);

Convenience function to set the value of the “pass-through” child property for `widget` .

#### Parameters

overlay | a CtkOverlay |
widget | an overlay child of CtkOverlay |
pass_through | whether the child should pass the input through |

Since: 3.18

## Types and Values

### struct CtkOverlay

    struct CtkOverlay;

### struct CtkOverlayClass

    struct CtkOverlayClass {
      CtkBinClass parent_class;

      gboolean (*get_child_position) (CtkOverlay    *overlay,
                                      CtkWidget     *widget,
                                      CtkAllocation *allocation);
    };

#### Members

`get_child_position` () | Signal emitted to determine the position and size of any overlay child widgets. |

## Signal Details

### The `“get-child-position”` signal

    gboolean
    user_function (CtkOverlay   *overlay,
                   CtkWidget    *widget,
                   CdkRectangle *allocation,
                   gpointer      user_data)

The ::get-child-position signal is emitted to determine the position and size of any overlay child widgets. A handler for this signal should fill `allocation` with the desired position and size for `widget` , relative to the 'main' child of `overlay` .

The default handler for this signal uses the `widget` 's halign and valign properties to determine the position and gives the widget its natural size (except that an alignment of `CTK_ALIGN_FILL` will cause the overlay to be full-width/height). If the main child is a CtkScrolledWindow, the overlays are placed relative to its contents.

#### Parameters

overlay | the CtkOverlay |
widget | the child widget to position |
allocation | return location for the allocation. | [type Cdk.Rectangle][out caller-allocates]
user_data | user data set when the signal handler was connected. |

#### Returns

`TRUE` if the `allocation` has been filled

Flags: Run Last