GUI Size Hints

This example shows how to use size hints to control the size of a GUI element.

The size_hint property is a tuple of two values. The first value is the width, and the second value is the height. The values are in percent of the parent element. For example, a size hint of (0.5, 0.5) would make the element half the width and half the height of the parent element.

Screen shot
6_size_hints.py
  1"""Sizing widgets using size hint keyword arguments
  2
  3The following keyword arguments can be used to set preferred size
  4information for layouts which arrange widgets
  5
  6* size_hint
  7* size_hint_max
  8* size_hint_min
  9
 10Please note the following:
 11
 12* These do nothing outside a layout
 13* They are only hints, and do not guarantee that a specific size will
 14  be provided.
 15
 16If Arcade and Python are properly installed, you can run this example with:
 17python -m arcade.examples.gui.6_size_hints
 18"""
 19
 20from __future__ import annotations
 21
 22import textwrap
 23
 24import arcade
 25from arcade.gui import (
 26    UIAnchorLayout,
 27    UIBoxLayout,
 28    UILabel,
 29    UIOnChangeEvent,
 30    UISpace,
 31    UITextArea,
 32    UIView,
 33)
 34
 35arcade.resources.load_kenney_fonts()
 36
 37SIZE_HINT_TEXT = textwrap.dedent(
 38    """
 39    UIWidgets provide three properties,
 40    which are used by layouts to determine the size of a widget.
 41
 42These properties are:
 43
 44* size_hint - percentage of the layout size
 45* size_hint_max - maximum size in pixels
 46* size_hint_min - minimum size in pixels
 47
 48Theses properties can be None, or a tuple of two values. The first value is
 49the width, and the second value is the height.
 50
 51If a value is None, the layout will use the widget's natural size for that dimension.
 52
 53    """.strip()
 54)
 55
 56
 57class MyView(UIView):
 58    def __init__(self):
 59        super().__init__()
 60        self.background_color = arcade.uicolor.BLUE_BELIZE_HOLE
 61
 62        root = self.ui.add(UIAnchorLayout())
 63        content = root.add(UIBoxLayout(size_hint=(1, 1)), anchor_x="left", anchor_y="top")
 64
 65        # title and information
 66        header_box = content.add(
 67            UIBoxLayout(space_between=5, align="left", size_hint=(1, 0)),
 68        )
 69        header_box.with_border(color=arcade.uicolor.DARK_BLUE_MIDNIGHT_BLUE)
 70        header_box.with_padding(all=10)
 71
 72        title = header_box.add(UILabel("Size Hint Example", font_size=24, bold=True))
 73        header_box.add(UISpace(color=arcade.uicolor.WHITE_CLOUDS, height=2, width=title.width))
 74
 75        # create text area and set the minimal size to the content size
 76        text = header_box.add(
 77            UITextArea(
 78                text=SIZE_HINT_TEXT,
 79                width=800,  # give text enough space to not wrap
 80                font_size=14,
 81                size_hint=(1, 1),
 82                bold=True,
 83            )
 84        )
 85        text.with_padding(top=10)
 86        text.size_hint_min = (
 87            None,
 88            text.layout.content_height + 50,
 89        )  # set minimal height to content height + padding
 90
 91        # add interactive demo
 92        content_anchor = content.add(UIAnchorLayout())
 93        content_anchor.with_border(color=arcade.uicolor.DARK_BLUE_MIDNIGHT_BLUE)
 94        content_anchor.with_padding(left=10, bottom=10)
 95
 96        center_box = content_anchor.add(
 97            UIBoxLayout(size_hint=(0.8, 0.5), align="left", space_between=20)
 98        )
 99
100        width_slider_box = center_box.add(UIBoxLayout(vertical=False, size_hint=(1, 0)))
101        width_slider_box.add(UILabel("Modify size_hint:", bold=True))
102        width_slider = width_slider_box.add(
103            arcade.gui.UISlider(min_value=0, max_value=10, value=0, size_hint=None, height=30)
104        )
105        width_value = width_slider_box.add(UILabel(bold=True))
106
107        content_anchor.add(UISpace(height=50))
108
109        # create a horizontal UIBoxLayout to show the effect of the sliders
110        demo_box = center_box.add(UIBoxLayout(vertical=False, size_hint=(0.8, 1)))
111        demo_box.with_background(color=arcade.uicolor.GRAY_ASBESTOS)
112
113        # create a dummy widget to show the effect of the sliders
114        dummy1 = demo_box.add(UILabel(bold=True))
115        dummy1.with_background(color=arcade.uicolor.YELLOW_ORANGE)
116        dummy2 = demo_box.add(UILabel(bold=True))
117        dummy2.with_background(color=arcade.uicolor.GREEN_EMERALD)
118
119        def update_size_hint_value(value: float):
120            width_value.text = f"({value:.2f})"
121            dummy1.size_hint = (value / 10, 1)
122            dummy1.text = f"size_hint = ({value / 10:.2f}, 1)"
123
124            dummy2.size_hint = (1 - value / 10, 1)
125            dummy2.text = f"size_hint = ({1 - value / 10:.2f}, 1)"
126
127        @width_slider.event("on_change")
128        def on_change(event: UIOnChangeEvent):
129            update_size_hint_value(event.new_value)
130
131        initial_value = 10
132        width_slider.value = initial_value
133        update_size_hint_value(initial_value)
134
135        content_anchor.add(UISpace(height=20))
136
137        self.ui.execute_layout()
138        self.ui.debug()
139
140
141def main():
142    window = arcade.Window(title="UIExample: Size Hints")
143    window.show_view(MyView())
144    window.run()
145
146
147if __name__ == "__main__":
148    main()