Layouts Overview#

Box Layout#

The Box layout organizes widgets into rows and columns. In v0.3.0, Box accepts additional parameters for sizing, styling, and identification.

Box([
    [Text('Row 1')],
    [Text('Row 2'), Button('Click')]
])

Key Attributes:

  • widgets (list): A nested list defining the structure of rows and columns.

  • css (str): Inline CSS string applied to the Box container.

  • margin (tuple | int): Margin around the box content.

  • spacing (int): Spacing between widgets inside the box.

  • size (tuple): Preferred size as (width, height).

  • fixed_size (tuple): Fixed size as (width, height).

  • min_size (tuple): Minimum size as (width, height).

  • max_size (tuple): Maximum size as (width, height).

  • id (any): Identifier for dynamic retrieval via GET().

Example:

from clera import Box, Text, Button

Box(
    [
        [Text('Row 1 Text')],
        [Button(value='Row 2 Button')]
    ],
    margin=10,
    spacing=5,
    id='-main-box-'
)

Grid Layout#

The Grid layout arranges widgets in a tabular structure based on specified rows and columns. Accepts the same extended parameters as Box.

Grid([
    [Text('Row 1')],
    [Text('Row 2'), Button('Click')]
])

Key Attributes:

  • widgets (list): A nested list defining the structure of rows and columns.

  • css (str): Inline CSS string applied to the Grid container.

  • margin (tuple | int): Margin around the grid content.

  • spacing (int): Spacing between widgets.

  • size (tuple): Preferred size as (width, height).

  • fixed_size (tuple): Fixed size as (width, height).

  • min_size (tuple): Minimum size as (width, height).

  • max_size (tuple): Maximum size as (width, height).

  • id (any): Identifier for dynamic retrieval via GET().

Splitter#

The Splitter layout divides the window into resizable panes. The user can drag the divider handle at runtime to resize panes. Supports horizontal and vertical orientation.

Splitter(widgets=[layout1, layout2], orientation='horizontal')

Key Attributes:

  • widgets (list): A list of layouts or widgets to place in each pane.

  • orientation (str): 'horizontal' or 'vertical'. Defaults to 'horizontal'.

  • sizes (list): Initial pixel sizes for each pane, e.g. [200, 400].

  • handle_width (int): Width of the drag handle in pixels. Defaults to 5.

  • live_resize (bool): If True, panes resize in real time while dragging. Defaults to True.

  • collapsible (bool): Allows panes to be collapsed to zero width. Defaults to True.

  • state (any): Restores a previously saved splitter state.

  • id (any): Identifier for dynamic retrieval via GET().

Example:

from clera import Window, Box, Splitter, Text, ListWidget

window = Window()

sidebar = Box([[ListWidget(list_items=['File 1', 'File 2', 'File 3'])]])
content = Box([[Text('Select a file from the sidebar', alignment='center')]])

Splitter(
    widgets=[sidebar, content],
    orientation='horizontal',
    sizes=[200, 600],
    handle_width=4
)

window.run()

Stack#

The Stack widget manages multiple widgets in a stacked layout, where only one is visible at a time.

Stack(widgets=[layout1, layout2])

Key Attributes:

  • widgets (list): A list of widgets to stack.

Example:

first_layout = Box([[Text('First View')]])
second_layout = Box([[Text('Second View')]])

Stack(
   widgets=[
      first_layout,
      second_layout,
   ]
)

Column#

The Column layout places widgets in a single vertical column. In v0.3.0, Column accepts margin and spacing parameters.

Column(widgets=[widget1, widget2], margin=5, spacing=4)

Key Attributes:

  • widgets (list): Widgets to place in the column.

  • margin (tuple): Margin around the column content.

  • spacing (tuple): Spacing between widgets.

Additional Layout Features#

Group Layout

The Group layout organizes button widgets within a container. It supports vertical or horizontal orientation and allows nesting other layouts within.

Key Attributes:

  • widgets (list): List of child button widgets.

  • orientation (str): vertical or horizontal.

  • strict (bool): Enforces strict alignment of child widgets if True.

Example:

from clera import Group, Button, Text

group(
    widgets=[
        Button(value='Action 1'),
        Button(value='Action 2')
    ],
    orientation='vertical'
)

Fieldset Layout

The Fieldset layout groups related widgets together under a labeled border, making it ideal for forms or sections.

Key Attributes:

  • label (str): Title of the fieldset.

  • widgets (list): List of widgets inside the fieldset.

  • orientation (str): vertical or horizontal.

Example:

from clera import Fieldset, Input, Button

fieldset(
    label='Login Details',
    widgets=[
        Input(placeholder='Username'),
        Input(placeholder='Password', type='password'),
        Button(value='Login')
    ],
    orientation='vertical'
)