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

gint | 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.

### 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.

## 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,
                                 gint position);

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` .

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 |
position | the new index for `child` in the list of overlay children of `overlay` , starting from 0. If negative, indicates the end of the list |

### 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”                    gint

The index of the overlay in the parent, -1 for the main child.

Flags: Read / Write

Allowed values: >= -1

Default value: 0

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

      “pass-through”             gboolean

Pass through input, does not affect main child.

Flags: Read / Write

Default value: FALSE

## 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