Gtk.Box¶

class — extends Widget, Accessible, Buildable, ConstraintTarget, Orientable

Arranges child widgets into a single row or column.

Whether it is a row or column depends on the value of its Orientable.orientation property. Within the other dimension, all children are allocated the same size. The Widget.halign and Widget.valign properties can be used on the children to influence their allocation.

Use repeated calls to Box.append to pack widgets into a GtkBox from start to end. Use Box.remove to remove widgets from the GtkBox. Box.insert_child_after can be used to add a child at a particular position.

Use Box.set_homogeneous to specify whether or not all children of the GtkBox are forced to get the same amount of space.

Use Box.set_spacing to determine how much space will be minimally placed between all children in the GtkBox. Note that spacing is added between the children.

Use Box.reorder_child_after to move a child to a different place in the box.

CSS nodes¶

GtkBox uses a single CSS node with name box.

Accessibility¶

Until GTK 4.10, GtkBox used the AccessibleRole.group role.

Starting from GTK 4.12, GtkBox uses the AccessibleRole.generic role.

Constructors¶

new¶

@classmethod
def new(cls, orientation: Orientation | int, spacing: int) -> Widget

Creates a new box.

Parameters:

orientation — the box’s orientation
spacing — the number of pixels to place between children

Methods¶

append¶

def append(self, child: Widget) -> None

Adds a child at the end.

Parameters:

child — the widget to append

get_baseline_child¶

def get_baseline_child(self) -> int

Gets the value set by Box.set_baseline_child.

get_baseline_position¶

def get_baseline_position(self) -> BaselinePosition

Gets the value set by Box.set_baseline_position.

get_homogeneous¶

def get_homogeneous(self) -> bool

Returns whether the box is homogeneous.

In a homogeneous box all children are the same size.

get_spacing¶

def get_spacing(self) -> int

Gets the value set by Box.set_spacing.

insert_child_after¶

def insert_child_after(self, child: Widget, sibling: Widget | None = ...) -> None

Inserts a child at a specific position.

The child is added after sibling in the list of box children.

If sibling is NULL, the child is placed at the beginning.

Parameters:

child — the widget to insert
sibling — the sibling after which to insert child

prepend¶

def prepend(self, child: Widget) -> None

Adds a child at the beginning.

Parameters:

child — the widget to prepend

remove¶

def remove(self, child: Widget) -> None

Removes a child widget from the box.

The child must have been added before with Box.append, Box.prepend, or Box.insert_child_after.

Parameters:

child — the child to remove

reorder_child_after¶

def reorder_child_after(self, child: Widget, sibling: Widget | None = ...) -> None

Moves a child to a different position.

The child is moved to the position after sibling in the list of box children.

If sibling is NULL, the child is placed at the beginning.

Parameters:

child — the widget to move, must be a child of box
sibling — the sibling to move child after

set_baseline_child¶

def set_baseline_child(self, child: int) -> None

Sets the baseline child of a box.

This affects only vertical boxes.

Parameters:

child — a child position, or -1

set_baseline_position¶

def set_baseline_position(self, position: BaselinePosition | int) -> None

Sets the baseline position of a box.

This affects only horizontal boxes with at least one baseline aligned child. If there is more vertical space available than requested, and the baseline is not allocated by the parent then position is used to allocate the baseline with respect to the extra space available.

Parameters:

position — the baseline position

set_homogeneous¶

def set_homogeneous(self, homogeneous: bool) -> None

Sets whether or not all children are given equal space in the box.

Parameters:

homogeneous — true to create equal allotments, false for variable allotments

set_spacing¶

def set_spacing(self, spacing: int) -> None

Sets the number of pixels to place between children.

Parameters:

spacing — the number of pixels to put between children

Properties¶

baseline_child¶

baseline_child: int  # read/write

The position of the child that determines the baseline.

This is only relevant if the box is in vertical orientation.

baseline_position¶

baseline_position: BaselinePosition | int  # read/write

How to position baseline-aligned widgets if extra space is available.

homogeneous¶

homogeneous: bool  # read/write

Whether the children should all be the same size.

spacing¶

spacing: int  # read/write

The amount of space between children.