GUI Layouts
Included Layouts
The GUI module provides a way to layout your GUI elements in a structured way. Layouts dynamically resize the elements based on the size of the window.
The layouts are an optional part of the GUI, but highly recommended to use. Mixing self positioning and layout positioning is possible, but can lead to unexpected results.
Layouts apply their layouting right before the rendering phase,
so the layout is always up-to-date for the rendering,
but will not be consistent after instantiation in your __init__() method.
To circumvent this, you can trigger a layout run by calling the UIManager.execute_layout().
The following layouts are available:
-
The UIBoxLayout class is used to arrange widgets in a horizontal or vertical box layout. Here are some key points to understand:
1. Orientation: The layout can be either horizontal or vertical, controlled by the vertical parameter.
2. Alignment: Widgets can be aligned within the layout using the align parameter.
3. Spacing: The layout can have spacing between the widgets, controlled by the space_between parameter.
4. Size Hints: The layout resizes widgets based on their size_hint, size_hint_min and size_hint_max.
5. Size: The layout automatically updates its size_hint_min based on the minimal required space by its children after layout phase.
In summary, UIBoxLayout provides a simple way to arrange widgets in a horizontal or vertical layout, allowing for alignment and spacing between the widgets.
-
The UIAnchorLayout class is used to arrange widgets in the center or at the edges of the layout. All children are independently anchored the specified anchor points.
Here are some key points to understand:
1. Anchor: The widget can be anchored to the center or at the edges of the layout using the anchor_x and anchor_y parameters. In addition to the anchor point, the widget can be offset from the anchor point using the offset_x and offset_y parameters.
2. Padding: The layout can have padding to ensure spacing to the borders, controlled by the padding parameter.
3. Size: The UIAnchorLayout is the only layout which by default fills the whole available space. (Default size_hint=(1, 1))
3. Size Hints: The layout resizes widgets based on their size_hint, size_hint_min and size_hint_max.
In summary, UIAnchorLayout provides a way to anchor widgets to a position within the layout. This allows for flexible positioning of widgets within the layout.
-
The UIGridLayout class is used to arrange widgets in a grid format. Here are some key points to understand:
1. Grid Structure: The layout is divided into a specified number of columns and rows. Widgets can be placed in these grid cells.
2. Spanning: Widgets can span multiple columns and/or rows using the column_span and row_span parameters.
3. Dynamic Sizing: Widgets can provide a size_hint to request dynamic space relative to the layout size. This means that the widget can grow or shrink based on the available space in the layout.
4. Alignment: Widgets can be aligned within their grid cells using the align_horizontal and align_vertical parameters.
5. Spacing: The layout can have horizontal and vertical spacing between the grid cells, controlled by the horizontal_spacing and vertical_spacing parameters.
6. Size: The layout automatically updates its size_hint_min based on the minimal required space by its children after layouting.
7. Size Hints: The layout resizes widgets based on their size_hint, size_hint_min and size_hint_max.
In summary, UIGridLayout provides a flexible way to arrange widgets in a grid, allowing for dynamic resizing and alignment based on the layout’s size and the widgets’ size hints.
When to use which layout?
Choosing the right layout depends on the desired layout structure. But often there are multiple ways to achieve the same layout.
Here are some guidelines to help you choose the right layout:
Use UIAnchorLayout for anchoring widgets to a position within the layout. This is mostly useful to position widgets freely within the bounds of the layout. Commonly used as the root layout for the whole GUI.
Use UIBoxLayout for simple horizontal or vertical layouts. This is useful for arranging widgets in a row or column. Multiple UIBoxLayout can be nested to create more complex layouts.
Use UIGridLayout for arranging widgets in a grid format. This is useful for creating a grid of widgets, where columns and rows should each have a fixed size.