GtkOverlay: GTK+ 3 Reference Manual

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

## Functions

GtkWidget * | gtk_overlay_new ()
void | gtk_overlay_add_overlay ()
void | gtk_overlay_reorder_overlay ()
gboolean | gtk_overlay_get_overlay_pass_through ()
void | gtk_overlay_set_overlay_pass_through ()

## Child Properties

int | index | Read / Write
gboolean | pass-through | Read / Write

## Signals

gboolean | get-child-position | Run Last

## Types and Values

struct | GtkOverlay
struct | GtkOverlayClass

## Object Hierarchy

        GObject
        ╰── GInitiallyUnowned
            ╰── GtkWidget
                ╰── GtkContainer
                    ╰── GtkBin
                        ╰── GtkOverlay

## Implemented Interfaces

GtkOverlay implements AtkImplementorIface and GtkBuildable.

## Includes

    #include <gtk/gtk.h>

## Description

GtkOverlay 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 `GTK_ALIGN_START` will be placed at the top left corner of the GtkOverlay container, whereas an overlay with halign set to `GTK_ALIGN_CENTER` and valign set to `GTK_ALIGN_END` will be placed a the bottom edge of the GtkOverlay, 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.

### GtkOverlay as GtkBuildable

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

### CSS nodes

GtkOverlay 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

### gtk_overlay_new ()

    GtkWidget *
    gtk_overlay_new (void);

Creates a new GtkOverlay.

#### Returns

a new GtkOverlay object.

Since: 3.2

### gtk_overlay_add_overlay ()

    void
    gtk_overlay_add_overlay (GtkOverlay *overlay,
                             GtkWidget *widget);

Adds `widget` to `overlay` .

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

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

#### Parameters

overlay | a GtkOverlay |
widget | a GtkWidget to be added to the container |

Since: 3.2

### gtk_overlay_reorder_overlay ()

    void
    gtk_overlay_reorder_overlay (GtkOverlay *overlay,
                                 GtkWidget *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 GtkOverlay |
child | the overlaid GtkWidget 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

### gtk_overlay_get_overlay_pass_through ()

    gboolean
    gtk_overlay_get_overlay_pass_through (GtkOverlay *overlay,
                                          GtkWidget *widget);

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

#### Parameters

overlay | a GtkOverlay |
widget | an overlay child of GtkOverlay |

#### Returns

whether the widget is a pass through child.

Since: 3.18

### gtk_overlay_set_overlay_pass_through ()

    void
    gtk_overlay_set_overlay_pass_through (GtkOverlay *overlay,
                                          GtkWidget *widget,
                                          gboolean pass_through);

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

#### Parameters

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

Since: 3.18

## Types and Values

### struct GtkOverlay

    struct GtkOverlay;

### struct GtkOverlayClass

    struct GtkOverlayClass {
      GtkBinClass parent_class;

      gboolean (*get_child_position) (GtkOverlay    *overlay,
                                      GtkWidget     *widget,
                                      GtkAllocation *allocation);
    };

#### Members

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

## Child Property Details

### The `“index”` child property

      “index”                    int

The index of the overlay child in the parent (or -1 for the main child). See `gtk_overlay_reorder_overlay()`.

Owner: GtkOverlay

Flags: Read / Write

Allowed values: >= -1

Default value: 0

Since: 3.18

### The `“pass-through”` child property

      “pass-through”             gboolean

Whether to pass input through the overlay child to the main child. (Of course, this has no effect when set on the main child itself.)

Note that this is implemented by calling `gdk_window_set_pass_through()` on the window that the overlay child is placed in. If the descendents of the overlay child have their own windows, you need to manually call that function on them to achieve the desired effect.

Owner: GtkOverlay

Flags: Read / Write

Default value: FALSE

Since: 3.18

## Signal Details

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

    gboolean
    user_function (GtkOverlay   *overlay,
                   GtkWidget    *widget,
                   GdkRectangle *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 `GTK_ALIGN_FILL` will cause the overlay to be full-width/height). If the main child is a GtkScrolledWindow, the overlays are placed relative to its contents.

#### Parameters

overlay | the GtkOverlay |
widget | the child widget to position |
allocation | return location for the allocation. | [type Gdk.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