From 0edd68f1e19ba6958a864b93d49adccea8d93c65 Mon Sep 17 00:00:00 2001 From: pushfoo <36696816+pushfoo@users.noreply.github.com> Date: Sat, 17 May 2025 22:31:43 -0400 Subject: [PATCH 1/4] Improve the UIGridLayout top-level docstring * Fix formatting * Rephrase for clarity --- arcade/gui/widgets/layout.py | 31 ++++++++++++++++++------------- 1 file changed, 18 insertions(+), 13 deletions(-) diff --git a/arcade/gui/widgets/layout.py b/arcade/gui/widgets/layout.py index 4a10d19d38..086989cd45 100644 --- a/arcade/gui/widgets/layout.py +++ b/arcade/gui/widgets/layout.py @@ -425,24 +425,29 @@ def __str__(self): class UIGridLayout(UILayout): - """Place widgets in a grid. + """Arranges each child widget over one or more columns and rows. - Widgets can span multiple columns and rows. - By default, the layout will only use the minimal required space (``size_hint = (0, 0)``). + The layout's ``size_hint`` requests a target size as a :py:class:`tuple` + of ``(x, y)`` floats as ratios relative to the layout's parent: - Widgets can provide a ``size_hint`` to request dynamic space relative to the layout size. - A size_hint of ``(1, 1)`` will fill the available space, while ``(0.1, 0.1)`` - will use maximum 10% of the layouts total size. + * The default of ``(0, 0)`` requests the minimum possible space + * ``(1.0, 1.0)`` requests the maximum possible space + * ``(0.1, 0.1)`` requests 10% of the layout parent's total size - Children are resized based on ``size_hint``. Maximum and minimum - ``size_hint``s only take effect if a ``size_hint`` is given. + Each child widget's ``size_hint`` value will be used to: - The layouts ``size_hint_min`` is automatically - updated based on the minimal required space by children, after layouting. + * control its size within the layout + * automatically re-calculate the layout's ``size_hint_min`` - The width of columns and height of rows are calculated based on the size hints of the children. - The highest size_hint_min of a child in a column or row is used. If a child has no size_hint, - the actual size is considered. + The widths of each column and height of each row is calculated are calculated + from the size hint values of child widgets along each. For each, the maximum + ``size_hint_min`` along its axis will be used. If a widget lacks ``size_hint`` + values, its current "actual" size will be used instead. + + .. note:: + + Maximum and minimum size hints only take effect when a ``size_hint`` + is set. Args: x: ``x`` coordinate of bottom left corner. From ed423b4b485ba65148acad147090f10ecf9d89c2 Mon Sep 17 00:00:00 2001 From: pushfoo <36696816+pushfoo@users.noreply.github.com> Date: Sat, 17 May 2025 22:35:20 -0400 Subject: [PATCH 2/4] Add quotes to string literals for alignment --- arcade/gui/widgets/layout.py | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/arcade/gui/widgets/layout.py b/arcade/gui/widgets/layout.py index 086989cd45..54b290fbf0 100644 --- a/arcade/gui/widgets/layout.py +++ b/arcade/gui/widgets/layout.py @@ -454,11 +454,11 @@ class UIGridLayout(UILayout): y: ``y`` coordinate of bottom left corner. width: Width of the layout. height: Height of the layout. - align_horizontal: Align children in orthogonal direction. - Options include ``left``, ``center``, and ``right``. - align_vertical: Align children in orthogonal direction. Options - include ``top``, ``center``, and ``bottom``. - children: Initial list of children. More can be added later. + align_horizontal: Align children in along the X axis to the + ``"left"``, ``"center"``, or ``"right"``. + align_vertical: Align children in along the Y axis to the + ``"top"``, ``"center"``, or ``"bottom"``. + children: An initial iterable of children. More can be added later. size_hint: A size hint for :py:class:`~arcade.gui.UILayout`, if the :py:class:`~arcade.gui.UIWidget` would like to grow. size_hint_max: Maximum width and height in pixels. From 370d6bb1349a7a38317c3550cc51b2ef850e64ca Mon Sep 17 00:00:00 2001 From: pushfoo <36696816+pushfoo@users.noreply.github.com> Date: Sat, 17 May 2025 22:54:46 -0400 Subject: [PATCH 3/4] Fix phrasing in top-level docstring --- arcade/gui/widgets/layout.py | 14 ++++++++++---- 1 file changed, 10 insertions(+), 4 deletions(-) diff --git a/arcade/gui/widgets/layout.py b/arcade/gui/widgets/layout.py index 54b290fbf0..ca0939eb5c 100644 --- a/arcade/gui/widgets/layout.py +++ b/arcade/gui/widgets/layout.py @@ -439,10 +439,16 @@ class UIGridLayout(UILayout): * control its size within the layout * automatically re-calculate the layout's ``size_hint_min`` - The widths of each column and height of each row is calculated are calculated - from the size hint values of child widgets along each. For each, the maximum - ``size_hint_min`` along its axis will be used. If a widget lacks ``size_hint`` - values, its current "actual" size will be used instead. + The width of each column and height of each row will be calculated + on update by reading the sizing data of each child widget. For each + row/column, the corresponding values along its axis will be read + from widgets along its axis: + + * the maximum ``size_hint_min`` of its widgets + * the minimum ``size_hint_max`` of its widgets + + If any widget lacks size hint data, its "actual" will be used instead. + See :py:meth:`~.do_layout` to learn more. .. note:: From 68c4725d5a1c6d644ec559471be1a6010c9e213c Mon Sep 17 00:00:00 2001 From: pushfoo <36696816+pushfoo@users.noreply.github.com> Date: Sat, 17 May 2025 23:42:26 -0400 Subject: [PATCH 4/4] Elaborate on UIGridLayout.do_layout's docstring --- arcade/gui/widgets/layout.py | 24 ++++++++++++++++-------- 1 file changed, 16 insertions(+), 8 deletions(-) diff --git a/arcade/gui/widgets/layout.py b/arcade/gui/widgets/layout.py index ca0939eb5c..386532d707 100644 --- a/arcade/gui/widgets/layout.py +++ b/arcade/gui/widgets/layout.py @@ -662,18 +662,26 @@ def _update_size_hints(self): ) def do_layout(self): - """Executes the layout algorithm. - - Children are placed in a grid layout based on the size hints. + """Arrange children in the grid based on their size hints. Algorithm --------- - 0. generate list for all rows and columns - 1. per column, collect max of size_hint_min and max size_hint (widths) - 2. per row, collect max of size_hint_min and max size_hint (heights) - 3. use box layout algorithm to distribute space - 4. place widgets in grid layout + 0. Generate lists of child widgets for each row and column + 1. For each column, calculate the following values: + + * If a widget lacks size hints, substitute the "actual" width instead + * The :py:func:`max` of all its child ``size_hint_min[0]`` values + * The :py:func:`max` of all its child ``size_hint[0]`` values + + 2. For each row, calculate the following values: + + * If a widget lacks size hints, substitute the "actual" height instead + * The :py:func:`max` of all its child ``size_hint_min[1]`` values + * The :py:func:`max` of all its child ``size_hint[1]`` values + + 3. Use box layout algorithm to allocate on-screen space + 4. Re-size and place the widgets to match the calculated grid layout """