Document widget style property access

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.

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)
 

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)

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)
 

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)
 

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()
 

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)
 

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.

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)
 

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

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)
 

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)
 

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)
 

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

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

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)
 

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

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

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)
 

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)

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)
 

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
 

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)
 

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)
 

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
 

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)
 

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

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
 
 <!-- REMOVE WHEN RESOLVED -->
 <!-- rumdl-disable MD013 -->
 ::: toga.Widget
     options:
+        show_bases: false
         show_if_no_docstring: true
 <!-- rumdl-enable MD013 -->