Skip to content

docs: Document PackMixin and Pack style shorthand on Widget#4356

Open
arijiiiitttt wants to merge 3 commits into
beeware:mainfrom
arijiiiitttt:docs--Document-PackMixin-and-Pack-style-shorthand-on-Widget-#4353
Open

docs: Document PackMixin and Pack style shorthand on Widget#4356
arijiiiitttt wants to merge 3 commits into
beeware:mainfrom
arijiiiitttt:docs--Document-PackMixin-and-Pack-style-shorthand-on-Widget-#4353

Conversation

@arijiiiitttt
Copy link
Copy Markdown

@arijiiiitttt arijiiiitttt commented Apr 29, 2026

Fixes #4353

What changed

core/src/toga/widgets/base.py

  • Added a note to Widget.__init__ docstring explaining that because Widget inherits from PackMixin, Pack style properties can be set directly on any widget instance (e.g. widget.flex = 1 instead of widget.style.flex = 1).

docs/reference/api/widgets/widget.md

  • Added a usage example showing the Pack style shorthand syntax.
  • Added PackMixin to the reference section so it appears in the generated documentation with its docstring and property list.

Why

Users had no way of knowing that Pack style properties could be set directly on a widget. PackMixin appeared in the base classes of Widget but was not documented or linked anywhere, making it very hard to discover this feature.

PR Checklist:

  • I will abide by the BeeWare Code of Conduct
  • I have read and have followed the CONTRIBUTING.md file

Copy link
Copy Markdown
Member

@freakboy3742 freakboy3742 left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for the PR - however, what you've documented here conflicts with the specific advice that I gave in my comment on the original ticket: that ideally, PackMixin wouldn't be documented or surfaced at all. Instead, you've specifically documented PackMixin and included full documentation of the mixin.

We do need to document the relationship between styles, `*kwargs, and style-related properties on widgets - but we need to do that without referencing PackMixin.

Comment on lines 78 to +79
:param style: A style object. If no style is provided, a default style
will be applied to the widget.
will be applied to the widget.
Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The indentation here is required.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

More clearly document use of Pack parameters/properties for widgets

2 participants