WrapBox

Added in version 1.7.

class WrapBox(**properties: Any)

Superclasses: Widget, InitiallyUnowned, Object

Implemented Interfaces: Accessible, Buildable, ConstraintTarget, Orientable

A box-like widget that can wrap into multiple lines.

AdwWrapBox is similar to Box, but can wrap lines when the widgets cannot fit otherwise. Unlike FlowBox, the children aren’t arranged into a grid and behave more like words in a wrapping label.

Like GtkBox, AdwWrapBox is orientable and has spacing:

• child_spacing between children in the same line;

• line_spacing between lines.

::: note

Unlike GtkBox, AdwWrapBox cannot follow the CSS border-spacing property.

Use the natural_line_length property to determine the layout’s natural size, e.g. when using it in a Popover.

Normally, a horizontal AdwWrapBox wraps left to right and top to bottom for left-to-right languages. Both of these directions can be reversed, using the pack_direction and wrap_reverse properties. Additionally, the alignment of each line can be controlled with the align property.

Lines can be justified using the justify property, filling the entire line by either increasing child size or spacing depending on the value. Set justify_last_line to justify the last line as well.

By default, AdwWrapBox wraps as soon as the previous line cannot fit any more children without shrinking them past their natural size. Set wrap_policy to minimum to only wrap once all the children in the previous line have been shrunk to their minimum size.

To make each line take the same amount of space, set line_homogeneous to TRUE.

Spacing and natural line length can scale with the text scale factor, use the child_spacing_unit, line_spacing_unit and/or natural_line_length_unit properties to enable that behavior.

See WrapLayout.

CSS nodes

AdwWrapBox uses a single CSS node with name wrap-box.

Accessibility

AdwWrapBox uses the group role.

Constructors

class WrapBox

classmethod new() → Widget

Creates a new AdwWrapBox.

Added in version 1.7.

Methods

class WrapBox

append(child: Widget) → None

Adds child as the last child to self.

Added in version 1.7.

Parameters:

child – the widget to append

get_align() → float

Gets the alignment of the children within each line.

Added in version 1.7.

get_child_spacing() → int

Gets spacing between widgets on the same line.

Added in version 1.7.

get_child_spacing_unit() → LengthUnit

Gets the length unit for child spacing.

Added in version 1.7.

get_justify() → JustifyMode

Gets whether and how each complete line is stretched to fill the entire widget.

Added in version 1.7.

get_justify_last_line() → bool

Gets whether the last line should be stretched to fill the entire widget.

Added in version 1.7.

get_line_homogeneous() → bool

Gets whether all lines should take the same amount of space.

Added in version 1.7.

get_line_spacing() → int

Gets the spacing between lines.

See line_spacing_unit.

Added in version 1.7.

get_line_spacing_unit() → LengthUnit

Gets the length unit for line spacing.

Added in version 1.7.

get_natural_line_length() → int

Gets the natural size for each line.

Added in version 1.7.

get_natural_line_length_unit() → LengthUnit

Gets the length unit for line spacing.

Added in version 1.7.

get_pack_direction() → PackDirection

Gets the direction children are packed in each line.

Added in version 1.7.

get_wrap_policy() → WrapPolicy

Gets the policy for line wrapping.

Added in version 1.7.

get_wrap_reverse() → bool

Gets whether wrap direction is reversed.

Added in version 1.7.

insert_child_after(child: Widget, sibling: Widget | None = None) → None

Inserts child in the position after sibling in the list of self children.

If sibling is NULL, inserts child at the first position.

Added in version 1.7.

Parameters:

• child – the widget to insert

• sibling – the sibling after which to insert child

prepend(child: Widget) → None

Adds child as the first child to self.

Added in version 1.7.

Parameters:

child – the widget to prepend

remove(child: Widget) → None

Removes a child widget from self.

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

Added in version 1.7.

Parameters:

child – the child to remove

remove_all() → None

Removes all children from self.

Added in version 1.8.

reorder_child_after(child: Widget, sibling: Widget | None = None) → None

Moves child to the position after sibling in the list of self children.

If sibling is NULL, moves child to the first position.

Added in version 1.7.

Parameters:

• child – the widget to move, must be a child of self

• sibling – the sibling to move child after

set_align(align: float) → None

Sets the alignment of the children within each line.

0 means the children are placed at the start of the line, 1 means they are placed at the end of the line. 0.5 means they are placed in the middle of the line.

Alignment is only used when justify is set to none, or on the last line when the justify_last_line is FALSE.

Added in version 1.7.

Parameters:

align – the child alignment

set_child_spacing(child_spacing: int) → None

Sets the spacing between widgets on the same line.

See child_spacing_unit.

Added in version 1.7.

Parameters:

child_spacing – the child spacing

set_child_spacing_unit(unit: LengthUnit) → None

Sets the length unit for child spacing.

Allows the spacing to vary depending on the text scale factor.

See child_spacing.

Added in version 1.7.

Parameters:

unit – the length unit

set_justify(justify: JustifyMode) → None

Determines whether and how each complete line should be stretched to fill the entire widget.

If set to fill, each widget in the line will be stretched, keeping consistent spacing, so that the line fills the entire widget.

If set to spread, the spacing between widgets will be increased, keeping widget sizes intact. The first and last widget will be aligned with the beginning and end of the line. If the line only contains a single widget, it will be stretched regardless.

If set to none, the line will not be stretched and the children will be placed together within the line, according to align.

By default this doesn’t affect the last line, as it will be incomplete. Use justify_last_line to justify it as well.

Added in version 1.7.

Parameters:

justify – the justify mode

set_justify_last_line(justify_last_line: bool) → None

Sets whether the last line should be stretched to fill the entire widget.

See justify.

Added in version 1.7.

Parameters:

justify_last_line – whether to justify the last line

set_line_homogeneous(homogeneous: bool) → None

Sets whether all lines should take the same amount of space.

Added in version 1.7.

Parameters:

homogeneous – whether lines should be homogeneous

set_line_spacing(line_spacing: int) → None

Sets the spacing between lines.

Added in version 1.7.

Parameters:

line_spacing – the line spacing

set_line_spacing_unit(unit: LengthUnit) → None

Sets the length unit for line spacing.

Allows the spacing to vary depending on the text scale factor.

See line_spacing.

Added in version 1.7.

Parameters:

unit – the length unit

set_natural_line_length(natural_line_length: int) → None

Sets the natural size for each line.

It should be used to limit the line lengths, for example when used in popovers.

See natural_line_length_unit.

Added in version 1.7.

Parameters:

natural_line_length – the natural length

set_natural_line_length_unit(unit: LengthUnit) → None

Sets the length unit for natural line length.

Allows the length to vary depending on the text scale factor.

See natural_line_length.

Added in version 1.7.

Parameters:

unit – the length unit

set_pack_direction(pack_direction: PackDirection) → None

Sets the direction children are packed in each line.

Added in version 1.7.

Parameters:

pack_direction – the new line direction

set_wrap_policy(wrap_policy: WrapPolicy) → None

Sets the policy for line wrapping.

If set to natural, the box will wrap to the next line as soon as the previous line cannot fit any more children without shrinking them past their natural size.

If set to minimum, the box will try to fit as many children into each line as possible, shrinking them down to their minimumsize before wrapping to the next line.

Added in version 1.7.

Parameters:

wrap_policy – the new wrap policy

set_wrap_reverse(wrap_reverse: bool) → None

Sets whether wrap direction should be reversed.

By default, lines wrap downwards in a horizontal box, and towards the end in a vertical box. If set to TRUE, they wrap upwards or towards the start respectively.

Added in version 1.7.

Parameters:

wrap_reverse – whether to reverse wrap direction

Properties

class WrapBox

props.align: float

The type of the None singleton.

Added in version 1.7.

props.child_spacing: int

The type of the None singleton.

Added in version 1.7.

props.child_spacing_unit: LengthUnit

The type of the None singleton.

Added in version 1.7.

props.justify: JustifyMode

The type of the None singleton.

Added in version 1.7.

props.justify_last_line: bool

The type of the None singleton.

Added in version 1.7.

props.line_homogeneous: bool

The type of the None singleton.

Added in version 1.7.

props.line_spacing: int

The type of the None singleton.

Added in version 1.7.

props.line_spacing_unit: LengthUnit

The type of the None singleton.

Added in version 1.7.

props.natural_line_length: int

The type of the None singleton.

Added in version 1.7.

props.natural_line_length_unit: LengthUnit

The type of the None singleton.

Added in version 1.7.

props.pack_direction: PackDirection

The type of the None singleton.

Added in version 1.7.

props.wrap_policy: WrapPolicy

The type of the None singleton.

Added in version 1.7.

props.wrap_reverse: bool

The type of the None singleton.

Added in version 1.7.