Gtk.Box

Example

Subclasses:

Gtk.ShortcutsGroup, Gtk.ShortcutsSection

Methods

Inherited:

Gtk.Widget (183), GObject.Object (37), Gtk.Accessible (17), Gtk.Buildable (1), Gtk.Orientable (2)

Structs:

Gtk.WidgetClass (18), GObject.ObjectClass (5)

class	new (orientation, spacing)
	append (child)
	get_baseline_child ()
	get_baseline_position ()
	get_homogeneous ()
	get_spacing ()
	insert_child_after (child, sibling)
	prepend (child)
	remove (child)
	reorder_child_after (child, sibling)
	set_baseline_child (child)
	set_baseline_position (position)
	set_homogeneous (homogeneous)
	set_spacing (spacing)

Virtual Methods

Inherited:

Gtk.Widget (25), GObject.Object (7), Gtk.Accessible (6), Gtk.Buildable (9)

Properties

Inherited:

Gtk.Widget (35), Gtk.Accessible (1), Gtk.Orientable (1)

Name	Type	Flags	Short Description
baseline-child	int	r/w/en
baseline-position	Gtk.BaselinePosition	r/w/en
homogeneous	bool	r/w/en
spacing	int	r/w/en

Signals

Inherited:

Gtk.Widget (13), GObject.Object (1)

Fields

Inherited:

Gtk.Widget (13), GObject.Object (1)

Name	Type	Access	Description
parent_instance	Gtk.Widget	r

Class Details

class Gtk.Box(**kwargs)

Bases:

Gtk.Widget, Gtk.Orientable

Abstract:

No

Structure:

Gtk.BoxClass

Arranges child widgets into a single row or column.

<picture> <source srcset=”box-dark.png” media=”(prefers-color-scheme: dark)”> <img alt=”An example Gtk.Box" src=”box.png”> </picture>

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

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

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

Use [method`Gtk`.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 [method`Gtk`.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 [enum`Gtk`.AccessibleRole.group] role.

Starting from GTK 4.12, GtkBox uses the [enum`Gtk`.AccessibleRole.generic] role.

classmethod new(orientation, spacing)

Parameters:

• orientation (Gtk.Orientation) – the box’s orientation

• spacing (int) – the number of pixels to place between children

Returns:

a new GtkBox.

Return type:

Gtk.Widget

Creates a new box.

append(child)

Parameters:

child (Gtk.Widget) – the widget to append

Adds a child at the end.

get_baseline_child()

Returns:

the baseline child

Return type:

int

Gets the value set by [method`Gtk`.Box.set_baseline_child].

New in version 4.12.

get_baseline_position()

Returns:

the baseline position

Return type:

Gtk.BaselinePosition

Gets the value set by [method`Gtk`.Box.set_baseline_position].

get_homogeneous()

Returns:

true if the box is homogeneous

Return type:

bool

Returns whether the box is homogeneous.

In a homogeneous box all children are the same size.

get_spacing()

Returns:

spacing between children

Return type:

int

Gets the value set by [method`Gtk`.Box.set_spacing].

insert_child_after(child, sibling)

Parameters:

• child (Gtk.Widget) – the widget to insert

• sibling (Gtk.Widget or None) – the sibling after which to insert child

Inserts a child at a specific position.

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

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

prepend(child)

Parameters:

child (Gtk.Widget) – the widget to prepend

Adds a child at the beginning.

remove(child)

Parameters:

child (Gtk.Widget) – the child to remove

Removes a child widget from the box.

The child must have been added before with [method`Gtk`.Box.append], [method`Gtk`.Box.prepend], or [method`Gtk`.Box.insert_child_after].

reorder_child_after(child, sibling)

Parameters:

• child (Gtk.Widget) – the widget to move, must be a child of self

• sibling (Gtk.Widget or None) – the sibling to move child after

Moves a child to a different position.

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

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

set_baseline_child(child)

Parameters:

child (int) – a child position, or -1

Sets the baseline child of a box.

This affects only vertical boxes.

New in version 4.12.

set_baseline_position(position)

Parameters:

position (Gtk.BaselinePosition) – the baseline position

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.

set_homogeneous(homogeneous)

Parameters:

homogeneous (bool) – true to create equal allotments, false for variable allotments

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

set_spacing(spacing)

Parameters:

spacing (int) – the number of pixels to put between children

Sets the number of pixels to place between children.

Property Details

Gtk.Box.props.baseline_child

Name:

baseline-child

Type:

int

Default Value:

-1

Flags:

READABLE, WRITABLE, EXPLICIT_NOTIFY

The position of the child that determines the baseline.

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

New in version 4.12.

Gtk.Box.props.baseline_position

Name:

baseline-position

Type:

Gtk.BaselinePosition

Default Value:

Gtk.BaselinePosition.CENTER

Flags:

READABLE, WRITABLE, EXPLICIT_NOTIFY

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

Gtk.Box.props.homogeneous

Name:

homogeneous

Type:

bool

Default Value:

False

Flags:

READABLE, WRITABLE, EXPLICIT_NOTIFY

Whether the children should all be the same size.

Gtk.Box.props.spacing

Name:

spacing

Type:

int

Default Value:

0

Flags:

READABLE, WRITABLE, EXPLICIT_NOTIFY

The amount of space between children.