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