diff --git a/changes/4353.doc.md b/changes/4353.doc.md new file mode 100644 index 0000000000..a88b865d02 --- /dev/null +++ b/changes/4353.doc.md @@ -0,0 +1 @@ +The Widget reference now explains how style properties can be provided through a style object, constructor keyword arguments, or direct widget attributes. diff --git a/core/src/toga/widgets/activityindicator.py b/core/src/toga/widgets/activityindicator.py index c3fc56b8fa..4b671b39f3 100644 --- a/core/src/toga/widgets/activityindicator.py +++ b/core/src/toga/widgets/activityindicator.py @@ -20,7 +20,8 @@ def __init__( will be applied to the widget. :param running: Describes whether the indicator is running at the time it is created. - :param kwargs: Initial style properties. + :param kwargs: Initial [Pack](/reference/api/style/pack.md) style properties. + These override matching properties on the `style` argument. """ super().__init__(id, style, **kwargs) diff --git a/core/src/toga/widgets/base.py b/core/src/toga/widgets/base.py index 326722858d..4192eb5b1f 100644 --- a/core/src/toga/widgets/base.py +++ b/core/src/toga/widgets/base.py @@ -69,10 +69,17 @@ def __init__( This is an abstract base class; it cannot be instantiated. + Properties provided by the widget's style can also be passed as constructor + keyword arguments, or read and written directly on the widget. For example, + `widget.margin = 10` is equivalent to `widget.style.margin = 10`. + By default, the widget will use [Pack](/reference/api/style/pack.md), + style attributes, but Toga allows for other style representations. + :param id: The ID for the widget. :param style: A style object. If no style is provided, a default style will be applied to the widget. - :param kwargs: Initial style properties. + :param kwargs: Initial style properties. These override any matching + properties on the `style` argument. """ if style is None: style = Pack(**kwargs) diff --git a/core/src/toga/widgets/box.py b/core/src/toga/widgets/box.py index 6b10b85b45..47d6d07f15 100644 --- a/core/src/toga/widgets/box.py +++ b/core/src/toga/widgets/box.py @@ -24,7 +24,8 @@ def __init__( :param style: A style object. If no style is provided, a default style will be applied to the widget. :param children: An optional list of children for to add to the Box. - :param kwargs: Initial style properties. + :param kwargs: Initial [Pack](/reference/api/style/pack.md) style properties. + These override matching properties on the `style` argument. """ super().__init__(id, style, **kwargs) diff --git a/core/src/toga/widgets/button.py b/core/src/toga/widgets/button.py index ac2414257e..c81bbda412 100644 --- a/core/src/toga/widgets/button.py +++ b/core/src/toga/widgets/button.py @@ -42,7 +42,8 @@ def __init__( :param on_press: A handler that will be invoked when the button is pressed. :param enabled: Is the button enabled (i.e., can it be pressed?). Optional; by default, buttons are created in an enabled state. - :param kwargs: Initial style properties. + :param kwargs: Initial [Pack](/reference/api/style/pack.md) style properties. + These override matching properties on the `style` argument. """ super().__init__(id, style, **kwargs) diff --git a/core/src/toga/widgets/canvas/canvas.py b/core/src/toga/widgets/canvas/canvas.py index 58798b6d60..995da0cee8 100644 --- a/core/src/toga/widgets/canvas/canvas.py +++ b/core/src/toga/widgets/canvas/canvas.py @@ -164,7 +164,8 @@ def __init__( :param on_alt_release: Initial [`on_alt_release`][toga.Canvas.on_alt_release] handler. :param on_alt_drag: Initial [`on_alt_drag`][toga.Canvas.on_alt_drag] handler. - :param kwargs: Initial style properties. + :param kwargs: Initial [Pack](/reference/api/style/pack.md) style properties. + These override matching properties on the `style` argument. """ self._root_state = State() diff --git a/core/src/toga/widgets/dateinput.py b/core/src/toga/widgets/dateinput.py index c01f2225a0..ec91992f84 100644 --- a/core/src/toga/widgets/dateinput.py +++ b/core/src/toga/widgets/dateinput.py @@ -48,7 +48,8 @@ def __init__( :param min: The earliest date (inclusive) that can be selected. :param max: The latest date (inclusive) that can be selected. :param on_change: A handler that will be invoked when the value changes. - :param kwargs: Initial style properties. + :param kwargs: Initial [Pack](/reference/api/style/pack.md) style properties. + These override matching properties on the `style` argument. """ super().__init__(id, style, **kwargs) diff --git a/core/src/toga/widgets/detailedlist.py b/core/src/toga/widgets/detailedlist.py index f3fa09f80d..e5589a4d6e 100644 --- a/core/src/toga/widgets/detailedlist.py +++ b/core/src/toga/widgets/detailedlist.py @@ -83,7 +83,8 @@ def __init__( :param on_secondary_action: Initial [`on_secondary_action`][toga.DetailedList.on_secondary_action] handler. :param on_refresh: Initial [`on_refresh`][toga.DetailedList.on_refresh] handler. - :param kwargs: Initial style properties. + :param kwargs: Initial [Pack](/reference/api/style/pack.md) style properties. + These override matching properties on the `style` argument. """ # Prime the attributes and handlers that need to exist when the widget is # created. diff --git a/core/src/toga/widgets/divider.py b/core/src/toga/widgets/divider.py index 08bb674e6c..dc3b0c778e 100644 --- a/core/src/toga/widgets/divider.py +++ b/core/src/toga/widgets/divider.py @@ -27,7 +27,8 @@ def __init__( [`Direction.HORIZONTAL`][toga.constants.Direction.HORIZONTAL] or [`Direction.VERTICAL`][toga.constants.Direction.VERTICAL]; defaults to [`Direction.HORIZONTAL`][toga.constants.Direction.HORIZONTAL] - :param kwargs: Initial style properties. + :param kwargs: Initial [Pack](/reference/api/style/pack.md) style properties. + These override matching properties on the `style` argument. """ super().__init__(id, style, **kwargs) diff --git a/core/src/toga/widgets/imageview.py b/core/src/toga/widgets/imageview.py index 7fa9bf187f..62c52fd568 100644 --- a/core/src/toga/widgets/imageview.py +++ b/core/src/toga/widgets/imageview.py @@ -83,7 +83,8 @@ def __init__( :param id: The ID for the widget. :param style: A style object. If no style is provided, a default style will be applied to the widget. - :param kwargs: Initial style properties. + :param kwargs: Initial [Pack](/reference/api/style/pack.md) style properties. + These override matching properties on the `style` argument. """ # Prime the image attribute self._image = None diff --git a/core/src/toga/widgets/label.py b/core/src/toga/widgets/label.py index caf12a2c45..cfc3156ef6 100644 --- a/core/src/toga/widgets/label.py +++ b/core/src/toga/widgets/label.py @@ -19,7 +19,8 @@ def __init__( :param id: The ID for the widget. :param style: A style object. If no style is provided, a default style will be applied to the widget. - :param kwargs: Initial style properties. + :param kwargs: Initial [Pack](/reference/api/style/pack.md) style properties. + These override matching properties on the `style` argument. """ super().__init__(id, style, **kwargs) diff --git a/core/src/toga/widgets/mapview.py b/core/src/toga/widgets/mapview.py index 9fa7a9693b..eb4a50a39f 100644 --- a/core/src/toga/widgets/mapview.py +++ b/core/src/toga/widgets/mapview.py @@ -153,7 +153,8 @@ def __init__( :param pins: The initial pins to display on the map. :param on_select: A handler that will be invoked when the user selects a map pin. - :param kwargs: Initial style properties. + :param kwargs: Initial [Pack](/reference/api/style/pack.md) style properties. + These override matching properties on the `style` argument. """ super().__init__(id, style, **kwargs) diff --git a/core/src/toga/widgets/multilinetextinput.py b/core/src/toga/widgets/multilinetextinput.py index 0b2e84fe02..c695e59511 100644 --- a/core/src/toga/widgets/multilinetextinput.py +++ b/core/src/toga/widgets/multilinetextinput.py @@ -39,7 +39,8 @@ def __init__( there is no user content to display. :param on_change: A handler that will be invoked when the value of the widget changes. - :param kwargs: Initial style properties. + :param kwargs: Initial [Pack](/reference/api/style/pack.md) style properties. + These override matching properties on the `style` argument. """ super().__init__(id, style, **kwargs) diff --git a/core/src/toga/widgets/numberinput.py b/core/src/toga/widgets/numberinput.py index 29d1c4c6dd..9626409b43 100644 --- a/core/src/toga/widgets/numberinput.py +++ b/core/src/toga/widgets/numberinput.py @@ -105,7 +105,8 @@ def __init__( :param readonly: Can the value of the widget be modified by the user? :param on_change: A handler that will be invoked when the value of the widget changes. - :param kwargs: Initial style properties. + :param kwargs: Initial [Pack](/reference/api/style/pack.md) style properties. + These override matching properties on the `style` argument. """ # The initial setting of min requires calling get_value(), # which in turn interrogates min. Prime those values with diff --git a/core/src/toga/widgets/optioncontainer.py b/core/src/toga/widgets/optioncontainer.py index 812d46c09a..3f75c7d239 100644 --- a/core/src/toga/widgets/optioncontainer.py +++ b/core/src/toga/widgets/optioncontainer.py @@ -419,7 +419,8 @@ def __init__( [OptionContainer content][toga.widgets.optioncontainer.OptionContainerContentT] to display in the OptionContainer. :param on_select: Initial [`on_select`][toga.OptionContainer.on_select] handler. - :param kwargs: Initial style properties. + :param kwargs: Initial [Pack](/reference/api/style/pack.md) style properties. + These override matching properties on the `style` argument. """ # noqa: E501 self._content = OptionList(self) self.on_select = None diff --git a/core/src/toga/widgets/progressbar.py b/core/src/toga/widgets/progressbar.py index 63c4b70ea2..390b46e670 100644 --- a/core/src/toga/widgets/progressbar.py +++ b/core/src/toga/widgets/progressbar.py @@ -30,7 +30,8 @@ def __init__( clipped. Defaults to 0.0. :param running: Describes whether the indicator is running at the time it is created. Default is False. - :param kwargs: Initial style properties. + :param kwargs: Initial [Pack](/reference/api/style/pack.md) style properties. + These override matching properties on the `style` argument. """ super().__init__(id, style, **kwargs) diff --git a/core/src/toga/widgets/scrollcontainer.py b/core/src/toga/widgets/scrollcontainer.py index 701be9d580..996782be4c 100644 --- a/core/src/toga/widgets/scrollcontainer.py +++ b/core/src/toga/widgets/scrollcontainer.py @@ -42,7 +42,8 @@ def __init__( :param vertical: Should vertical scrolling be permitted? :param on_scroll: Initial [`on_scroll`][toga.ScrollContainer.on_scroll] handler. :param content: The content to display in the scroll window. - :param kwargs: Initial style properties. + :param kwargs: Initial [Pack](/reference/api/style/pack.md) style properties. + These override matching properties on the `style` argument. """ self._content: Widget | None = None diff --git a/core/src/toga/widgets/selection.py b/core/src/toga/widgets/selection.py index fa79848402..a17231e7da 100644 --- a/core/src/toga/widgets/selection.py +++ b/core/src/toga/widgets/selection.py @@ -45,7 +45,8 @@ def __init__( `items` will be selected. :param on_change: Initial [`on_change`][toga.Selection.on_change] handler. :param enabled: Whether the user can interact with the widget. - :param kwargs: Initial style properties. + :param kwargs: Initial [Pack](/reference/api/style/pack.md) style properties. + These override matching properties on the `style` argument. """ self._items: ListSourceT | ListSource diff --git a/core/src/toga/widgets/slider.py b/core/src/toga/widgets/slider.py index d117a57d64..0d23e6478d 100644 --- a/core/src/toga/widgets/slider.py +++ b/core/src/toga/widgets/slider.py @@ -69,7 +69,8 @@ def __init__( :param on_press: Initial [`on_press`][toga.Slider.on_press] handler. :param on_release: Initial [`on_release`][toga.Slider.on_release] handler. :param enabled: Whether the user can interact with the widget. - :param kwargs: Initial style properties. + :param kwargs: Initial [Pack](/reference/api/style/pack.md) style properties. + These override matching properties on the `style` argument. """ super().__init__(id, style, **kwargs) diff --git a/core/src/toga/widgets/splitcontainer.py b/core/src/toga/widgets/splitcontainer.py index 17a9f5f77f..5f068fabe9 100644 --- a/core/src/toga/widgets/splitcontainer.py +++ b/core/src/toga/widgets/splitcontainer.py @@ -49,7 +49,8 @@ def __init__( :param content: Initial [SplitContainer content][toga.widgets.splitcontainer.SplitContainerContentT] of the container. Defaults to both panels being empty. - :param kwargs: Initial style properties. + :param kwargs: Initial [Pack](/reference/api/style/pack.md) style properties. + These override matching properties on the `style` argument. """ self._content: list[SplitContainerContentT] = [None, None] super().__init__(id, style, **kwargs) diff --git a/core/src/toga/widgets/switch.py b/core/src/toga/widgets/switch.py index 8681bdbb66..0c316c16e8 100644 --- a/core/src/toga/widgets/switch.py +++ b/core/src/toga/widgets/switch.py @@ -39,7 +39,8 @@ def __init__( value. :param enabled: Is the switch enabled (i.e., can it be pressed?). Optional; by default, switches are created in an enabled state. - :param kwargs: Initial style properties. + :param kwargs: Initial [Pack](/reference/api/style/pack.md) style properties. + These override matching properties on the `style` argument. """ super().__init__(id, style, **kwargs) diff --git a/core/src/toga/widgets/table.py b/core/src/toga/widgets/table.py index a0913bdeb8..465f4bb8e5 100644 --- a/core/src/toga/widgets/table.py +++ b/core/src/toga/widgets/table.py @@ -115,7 +115,8 @@ def __init__( For backwards compatibility, this is set to False if no columns or headings are provided. :param headings: **DEPRECATED** A list of heading strings for columns. - :param kwargs: Initial style properties. + :param kwargs: Initial [Pack](/reference/api/style/pack.md) style properties. + These override matching properties on the `style` argument. """ self._data: ListSourceT | ListSource diff --git a/core/src/toga/widgets/textinput.py b/core/src/toga/widgets/textinput.py index 9ebce42bed..80a9522a9d 100644 --- a/core/src/toga/widgets/textinput.py +++ b/core/src/toga/widgets/textinput.py @@ -78,7 +78,8 @@ def __init__( :param on_lose_focus: A handler that will be invoked when the widget loses input focus. :param validators: A list of validators to run on the value of the input. - :param kwargs: Initial style properties. + :param kwargs: Initial [Pack](/reference/api/style/pack.md) style properties. + These override matching properties on the `style` argument. """ super().__init__(id, style, **kwargs) diff --git a/core/src/toga/widgets/timeinput.py b/core/src/toga/widgets/timeinput.py index e6d1ad39aa..12b53fab37 100644 --- a/core/src/toga/widgets/timeinput.py +++ b/core/src/toga/widgets/timeinput.py @@ -39,7 +39,8 @@ def __init__( :param min: The earliest time (inclusive) that can be selected. :param max: The latest time (inclusive) that can be selected. :param on_change: A handler that will be invoked when the value changes. - :param kwargs: Initial style properties. + :param kwargs: Initial [Pack](/reference/api/style/pack.md) style properties. + These override matching properties on the `style` argument. """ super().__init__(id, style, **kwargs) diff --git a/core/src/toga/widgets/tree.py b/core/src/toga/widgets/tree.py index 64df0b3933..de3978c059 100644 --- a/core/src/toga/widgets/tree.py +++ b/core/src/toga/widgets/tree.py @@ -115,7 +115,8 @@ def __init__( For backwards compatibility, this is set to False if no columns or headings are provided. :param headings: **DEPRECATED** A list of heading strings for columns. - :param kwargs: Initial style properties. + :param kwargs: Initial [Pack](/reference/api/style/pack.md) style properties. + These override matching properties on the `style` argument. """ self._data: TreeSourceT | TreeSource diff --git a/core/src/toga/widgets/webview.py b/core/src/toga/widgets/webview.py index 2c365af4b7..6211be339a 100644 --- a/core/src/toga/widgets/webview.py +++ b/core/src/toga/widgets/webview.py @@ -68,7 +68,8 @@ def __init__( to a different URI. :param on_webview_load: A handler that will be invoked when the web view finishes loading. - :param kwargs: Initial style properties. + :param kwargs: Initial [Pack](/reference/api/style/pack.md) style properties. + These override matching properties on the `style` argument. """ super().__init__(id, style, **kwargs) diff --git a/docs/en/reference/api/style/pack.md b/docs/en/reference/api/style/pack.md index 8132a5c8c8..41761db910 100644 --- a/docs/en/reference/api/style/pack.md +++ b/docs/en/reference/api/style/pack.md @@ -12,6 +12,20 @@ Some properties, despite always storing their value in a consistent form, are mo Toga has a [layout debug mode][debug-layout] to aid in visually debugging or exploring Pack layouts. +## Using Pack properties on widgets + +Pack is the default style representation for Toga widgets. You can provide Pack properties as keyword arguments when constructing a widget, or read and write them directly on the widget. For example, these statements set the same margin: + +```python +import toga + +widget = toga.Label("Hello", margin=10) +widget.margin = 10 +widget.style.margin = 10 +``` + +When a widget is constructed with both a `style` object and Pack keyword arguments, the keyword arguments override matching properties on the style object. See the [`kwargs` parameter of `Widget`](/reference/api/widgets/widget.md#toga.Widget) for the common widget constructor arguments. Toga also allows widgets to use other style representations. + ## Reference ::: toga.style.pack.Pack diff --git a/docs/en/reference/api/widgets/widget.md b/docs/en/reference/api/widgets/widget.md index 89e747ccf8..995f161ea2 100644 --- a/docs/en/reference/api/widgets/widget.md +++ b/docs/en/reference/api/widgets/widget.md @@ -4,12 +4,32 @@ This class exists only for actual widgets to inherit from; it should not be be instantiated directly. +Every widget has a `style` object that controls its layout and presentation. By default, this is a [`Pack`][toga.style.Pack] style. Style properties can be set in any of these equivalent ways: + +```python +import toga +from toga.style import Pack + +# Provide a style object. +widget = toga.Label("Hello", style=Pack(margin=10)) + +# Provide style properties as constructor keyword arguments. +widget = toga.Label("Hello", margin=10) + +# Read or write a style property directly on the widget. +widget.margin = 10 +assert widget.margin == widget.style.margin +``` + +When both a `style` object and style keyword arguments are provided, the keyword arguments override matching properties from the style object. See the [Pack reference][toga.style.Pack] for the available default style properties. + ## Reference ::: toga.Widget options: + show_bases: false show_if_no_docstring: true