Kivy-examples 2.3.1.dev0__py3-none-any.whl

kivy/uix/layout.py

@@ -0,0 +1,322 @@
+'''
+Layout
+======
+
+Layouts are used to calculate and assign widget positions.
+
+The :class:`Layout` class itself cannot be used directly.
+You should use one of the following layout classes:
+
+- Anchor layout: :class:`kivy.uix.anchorlayout.AnchorLayout`
+- Box layout: :class:`kivy.uix.boxlayout.BoxLayout`
+- Float layout: :class:`kivy.uix.floatlayout.FloatLayout`
+- Grid layout: :class:`kivy.uix.gridlayout.GridLayout`
+- Page Layout: :class:`kivy.uix.pagelayout.PageLayout`
+- Relative layout: :class:`kivy.uix.relativelayout.RelativeLayout`
+- Scatter layout: :class:`kivy.uix.scatterlayout.ScatterLayout`
+- Stack layout: :class:`kivy.uix.stacklayout.StackLayout`
+
+
+Understanding the `size_hint` Property in `Widget`
+--------------------------------------------------
+
+The :attr:`~kivy.uix.Widget.size_hint` is a tuple of values used by
+layouts to manage the sizes of their children. It indicates the size
+relative to the layout's size instead of an absolute size (in
+pixels/points/cm/etc). The format is::
+
+    widget.size_hint = (width_proportion, height_proportion)
+
+The proportions are specified as floating point numbers in the range 0-1. For
+example, 0.5 represents 50%, 1 represents 100%.
+
+If you want a widget's width to be half of the parent's width and the
+height to be identical to the parent's height, you would do::
+
+    widget.size_hint = (0.5, 1.0)
+
+If you don't want to use a size_hint for either the width or height, set the
+value to None. For example, to make a widget that is 250px wide and 30%
+of the parent's height, do::
+
+    widget.size_hint = (None, 0.3)
+    widget.width = 250
+
+Being :class:`Kivy properties <kivy.properties>`, these can also be set via
+constructor arguments::
+
+    widget = Widget(size_hint=(None, 0.3), width=250)
+
+.. versionchanged:: 1.4.1
+    The `reposition_child` internal method (made public by mistake) has
+    been removed.
+
+'''
+
+__all__ = ('Layout', )
+
+from kivy.clock import Clock
+from kivy.uix.widget import Widget
+from kivy.compat import isclose
+
+
+class Layout(Widget):
+    '''Layout interface class, used to implement every layout. See module
+    documentation for more information.
+    '''
+
+    _trigger_layout = None
+
+    def __init__(self, **kwargs):
+        if self.__class__ == Layout:
+            raise Exception('The Layout class is abstract and \
+                cannot be used directly.')
+        if self._trigger_layout is None:
+            self._trigger_layout = Clock.create_trigger(self.do_layout, -1)
+        super(Layout, self).__init__(**kwargs)
+
+    def do_layout(self, *largs):
+        '''This function is called when a layout is called by a trigger.
+        If you are writing a new Layout subclass, don't call this function
+        directly but use :meth:`_trigger_layout` instead.
+
+        The function is by default called *before* the next frame, therefore
+        the layout isn't updated immediately. Anything depending on the
+        positions of e.g. children should be scheduled for the next frame.
+
+        .. versionadded:: 1.0.8
+        '''
+        raise NotImplementedError('Must be implemented in subclasses.')
+
+    def add_widget(self, widget, *args, **kwargs):
+        fbind = widget.fbind
+        fbind('size', self._trigger_layout)
+        fbind('size_hint', self._trigger_layout)
+        fbind('size_hint_max', self._trigger_layout)
+        fbind('size_hint_min', self._trigger_layout)
+        super(Layout, self).add_widget(widget, *args, **kwargs)
+
+    def remove_widget(self, widget, *args, **kwargs):
+        funbind = widget.funbind
+        funbind('size', self._trigger_layout)
+        funbind('size_hint', self._trigger_layout)
+        funbind('size_hint_max', self._trigger_layout)
+        funbind('size_hint_min', self._trigger_layout)
+        super(Layout, self).remove_widget(widget, *args, **kwargs)
+
+    def layout_hint_with_bounds(
+            self, sh_sum, available_space, min_bounded_size, sh_min_vals,
+            sh_max_vals, hint):
+        '''(internal) Computes the appropriate (size) hint for all the
+        widgets given (potential) min or max bounds on the widgets' size.
+        The ``hint`` list is updated with appropriate sizes.
+
+        It walks through the hints and for any widgets whose hint will result
+        in violating min or max constraints, it fixes the hint. Any remaining
+        or missing space after all the widgets are fixed get distributed
+        to the widgets making them smaller or larger according to their
+        size hint.
+
+        This algorithms knows nothing about the widgets other than what is
+        passed through the input params, so it's fairly generic for laying
+        things out according to constraints using size hints.
+
+        :Parameters:
+
+            `sh_sum`: float
+                The sum of the size hints (basically ``sum(size_hint)``).
+            `available_space`: float
+                The amount of pixels available for all the widgets
+                whose size hint is not None. Cannot be zero.
+            `min_bounded_size`: float
+                The minimum amount of space required according to the
+                `size_hint_min` of the widgets (basically
+                ``sum(size_hint_min)``).
+            `sh_min_vals`: list or iterable
+                Items in the iterable are the size_hint_min for each widget.
+                Can be None. The length should be the same as ``hint``
+            `sh_max_vals`: list or iterable
+                Items in the iterable are the size_hint_max for each widget.
+                Can be None. The length should be the same as ``hint``
+            `hint`: list
+                A list whose size is the same as the length of ``sh_min_vals``
+                and ``sh_min_vals`` whose each element is the corresponding
+                size hint value of that element. This list is updated in place
+                with correct size hints that ensure the constraints are not
+                violated.
+
+        :returns:
+            Nothing. ``hint`` is updated in place.
+        '''
+        if not sh_sum:
+            return
+        # TODO: test when children have size_hint, max/min of zero
+
+        # all divs are float denominator ;)
+        stretch_ratio = sh_sum / float(available_space)
+        if available_space <= min_bounded_size or \
+                isclose(available_space, min_bounded_size):
+            # too small, just set to min
+            for i, (sh, sh_min) in enumerate(zip(hint, sh_min_vals)):
+                if sh is None:
+                    continue
+
+                if sh_min is not None:
+                    hint[i] = sh_min * stretch_ratio  # set to min size
+                else:
+                    hint[i] = 0.  # everything else is zero
+            return
+
+        # these dicts take i (widget child) as key
+        not_mined_contrib = {}  # all who's sh > min_sh or had no min_sh
+        not_maxed_contrib = {}  # all who's sh < max_sh or had no max_sh
+        sh_mins_avail = {}  # the sh amt removable until we hit sh_min
+        sh_maxs_avail = {}  # the sh amt addable until we hit sh_max
+        oversize_amt = undersize_amt = 0
+        hint_orig = hint[:]
+
+        # first, for all the items, set them to be within their max/min
+        # size_hint bound, also find how much their size_hint can be reduced
+        # or increased
+        for i, (sh, sh_min, sh_max) in enumerate(
+                zip(hint, sh_min_vals, sh_max_vals)):
+            if sh is None:
+                continue
+
+            diff = 0
+
+            if sh_min is not None:
+                sh_min *= stretch_ratio
+                diff = sh_min - sh  # how much we are under the min
+
+                if diff > 0:
+                    hint[i] = sh_min
+                    undersize_amt += diff
+                else:
+                    not_mined_contrib[i] = None
+
+                sh_mins_avail[i] = hint[i] - sh_min
+            else:
+                not_mined_contrib[i] = None
+                sh_mins_avail[i] = hint[i]
+
+            if sh_max is not None:
+                sh_max *= stretch_ratio
+                diff = sh - sh_max
+
+                if diff > 0:
+                    hint[i] = sh_max  # how much we are over the max
+                    oversize_amt += diff
+                else:
+                    not_maxed_contrib[i] = None
+
+                sh_maxs_avail[i] = sh_max - hint[i]
+            else:
+                not_maxed_contrib[i] = None
+                sh_maxs_avail[i] = sh_sum - hint[i]
+
+            if i in not_mined_contrib:
+                not_mined_contrib[i] = max(0., diff)  # how much got removed
+            if i in not_maxed_contrib:
+                not_maxed_contrib[i] = max(0., diff)  # how much got added
+
+        # if margin is zero, the amount of the widgets that were made smaller
+        # magically equals the amount of the widgets that were made larger
+        # so we're all good
+        margin = oversize_amt - undersize_amt
+        if isclose(oversize_amt, undersize_amt, abs_tol=1e-15):
+            return
+
+        # we need to redistribute the margin among all widgets
+        # if margin is positive, then we have extra space because the widgets
+        # that were larger and were reduced contributed more, so increase
+        # the size hint for those that are allowed to be larger by the
+        # most allowed, proportionately to their size (or inverse size hint).
+        # similarly for the opposite case
+        if margin > 1e-15:
+            contrib_amt = not_maxed_contrib
+            sh_available = sh_maxs_avail
+            mult = 1.
+            contrib_proportion = hint_orig
+        elif margin < -1e-15:
+            margin *= -1.
+            contrib_amt = not_mined_contrib
+            sh_available = sh_mins_avail
+            mult = -1.
+
+            # when reducing the size of widgets proportionately, those with
+            # larger sh get reduced less, and those with smaller, more.
+            mn = min((h for h in hint_orig if h))
+            mx = max((h for h in hint_orig if h is not None))
+            hint_top = (2. * mn if mn else 1.) if mn == mx else mn + mx
+            contrib_proportion = [None if h is None else hint_top - h for
+                          h in hint_orig]
+
+        # contrib_amt is all the widgets that are not their max/min and
+        # can afford to be made bigger/smaller
+        # We only use the contrib_amt indices from now on
+        contrib_prop_sum = float(
+            sum((contrib_proportion[i] for i in contrib_amt)))
+
+        if contrib_prop_sum < 1e-9:
+            assert mult == 1.  # should only happen when all sh are zero
+            return
+
+        contrib_height = {
+            i: val / (contrib_proportion[i] / contrib_prop_sum) for
+            i, val in contrib_amt.items()}
+        items = sorted(
+            (i for i in contrib_amt),
+            key=lambda x: contrib_height[x])
+
+        j = items[0]
+        sum_i_contributed = contrib_amt[j]
+        last_height = contrib_height[j]
+        sh_available_i = {j: sh_available[j]}
+        contrib_prop_sum_i = contrib_proportion[j]
+
+        n = len(items)  # check when n <= 1
+        i = 1
+        if 1 < n:
+            j = items[1]
+            curr_height = contrib_height[j]
+
+        done = False
+        while not done and i < n:
+            while i < n and last_height == curr_height:
+                j = items[i]
+                sum_i_contributed += contrib_amt[j]
+                contrib_prop_sum_i += contrib_proportion[j]
+                sh_available_i[j] = sh_available[j]
+                curr_height = contrib_height[j]
+                i += 1
+            last_height = curr_height
+
+            while not done:
+                margin_height = ((margin + sum_i_contributed) /
+                                 (contrib_prop_sum_i / contrib_prop_sum))
+                if margin_height - curr_height > 1e-9 and i < n:
+                    break
+
+                done = True
+                for k, available_sh in list(sh_available_i.items()):
+                    if margin_height - available_sh / (
+                            contrib_proportion[k] / contrib_prop_sum) > 1e-9:
+                        del sh_available_i[k]
+                        sum_i_contributed -= contrib_amt[k]
+                        contrib_prop_sum_i -= contrib_proportion[k]
+                        margin -= available_sh
+                        hint[k] += mult * available_sh
+                        done = False
+
+                if not sh_available_i:  # all were under the margin
+                    break
+
+        if sh_available_i:
+            assert contrib_prop_sum_i and margin
+            margin_height = ((margin + sum_i_contributed) /
+                             (contrib_prop_sum_i / contrib_prop_sum))
+            for i in sh_available_i:
+                hint[i] += mult * (
+                    margin_height * contrib_proportion[i] / contrib_prop_sum -
+                    contrib_amt[i])

kivy/uix/modalview.py

@@ -0,0 +1,339 @@
+"""
+ModalView
+=========
+
+.. versionadded:: 1.4.0
+
+The :class:`ModalView` widget is used to create modal views. By default, the
+view will cover the whole "main" window.
+
+Remember that the default size of a Widget is size_hint=(1, 1). If you don't
+want your view to be fullscreen, either use size hints with values lower than
+1 (for instance size_hint=(.8, .8)) or deactivate the size_hint and use fixed
+size attributes.
+
+Examples
+--------
+
+Example of a simple 400x400 Hello world view::
+
+    view = ModalView(size_hint=(None, None), size=(400, 400))
+    view.add_widget(Label(text='Hello world'))
+
+By default, any click outside the view will dismiss it. If you don't
+want that, you can set :attr:`ModalView.auto_dismiss` to False::
+
+    view = ModalView(auto_dismiss=False)
+    view.add_widget(Label(text='Hello world'))
+    view.open()
+
+To manually dismiss/close the view, use the :meth:`ModalView.dismiss` method of
+the ModalView instance::
+
+    view.dismiss()
+
+Both :meth:`ModalView.open` and :meth:`ModalView.dismiss` are bind-able. That
+means you can directly bind the function to an action, e.g. to a button's
+on_press ::
+
+    # create content and add it to the view
+    content = Button(text='Close me!')
+    view = ModalView(auto_dismiss=False)
+    view.add_widget(content)
+
+    # bind the on_press event of the button to the dismiss function
+    content.bind(on_press=view.dismiss)
+
+    # open the view
+    view.open()
+
+
+ModalView Events
+----------------
+
+There are four events available: `on_pre_open` and `on_open` which are raised
+when the view is opening; `on_pre_dismiss` and `on_dismiss` which are raised
+when the view is closed.
+
+For `on_dismiss`, you can prevent the view from closing by explicitly
+returning `True` from your callback::
+
+    def my_callback(instance):
+        print('ModalView', instance, 'is being dismissed, but is prevented!')
+        return True
+    view = ModalView()
+    view.add_widget(Label(text='Hello world'))
+    view.bind(on_dismiss=my_callback)
+    view.open()
+
+
+.. versionchanged:: 1.5.0
+    The ModalView can be closed by hitting the escape key on the
+    keyboard if the :attr:`ModalView.auto_dismiss` property is True (the
+    default).
+
+"""
+
+__all__ = ('ModalView', )
+
+from kivy.animation import Animation
+from kivy.properties import (
+    StringProperty, BooleanProperty, ObjectProperty, NumericProperty,
+    ListProperty, ColorProperty)
+from kivy.uix.anchorlayout import AnchorLayout
+
+
+class ModalView(AnchorLayout):
+    """ModalView class. See module documentation for more information.
+
+    :Events:
+        `on_pre_open`:
+            Fired before the ModalView is opened. When this event is fired
+            ModalView is not yet added to window.
+        `on_open`:
+            Fired when the ModalView is opened.
+        `on_pre_dismiss`:
+            Fired before the ModalView is closed.
+        `on_dismiss`:
+            Fired when the ModalView is closed. If the callback returns True,
+            the dismiss will be canceled.
+
+    .. versionchanged:: 1.11.0
+        Added events `on_pre_open` and `on_pre_dismiss`.
+
+    .. versionchanged:: 2.0.0
+        Added property 'overlay_color'.
+
+    .. versionchanged:: 2.1.0
+        Marked `attach_to` property as deprecated.
+
+    """
+
+    # noinspection PyArgumentEqualDefault
+    auto_dismiss = BooleanProperty(True)
+    '''This property determines if the view is automatically
+    dismissed when the user clicks outside it.
+
+    :attr:`auto_dismiss` is a :class:`~kivy.properties.BooleanProperty` and
+    defaults to True.
+    '''
+
+    attach_to = ObjectProperty(None, deprecated=True)
+    '''If a widget is set on attach_to, the view will attach to the nearest
+    parent window of the widget. If none is found, it will attach to the
+    main/global Window.
+
+    :attr:`attach_to` is an :class:`~kivy.properties.ObjectProperty` and
+    defaults to None.
+    '''
+
+    background_color = ColorProperty([1, 1, 1, 1])
+    '''Background color, in the format (r, g, b, a).
+
+    This acts as a *multiplier* to the texture color. The default
+    texture is grey, so just setting the background color will give
+    a darker result. To set a plain color, set the
+    :attr:`background_normal` to ``''``.
+
+    The :attr:`background_color` is a
+    :class:`~kivy.properties.ColorProperty` and defaults to [1, 1, 1, 1].
+
+    .. versionchanged:: 2.0.0
+        Changed behavior to affect the background of the widget itself, not
+        the overlay dimming.
+        Changed from :class:`~kivy.properties.ListProperty` to
+        :class:`~kivy.properties.ColorProperty`.
+    '''
+
+    background = StringProperty(
+        'atlas://data/images/defaulttheme/modalview-background')
+    '''Background image of the view used for the view background.
+
+    :attr:`background` is a :class:`~kivy.properties.StringProperty` and
+    defaults to 'atlas://data/images/defaulttheme/modalview-background'.
+    '''
+
+    border = ListProperty([16, 16, 16, 16])
+    '''Border used for :class:`~kivy.graphics.vertex_instructions.BorderImage`
+    graphics instruction. Used for the :attr:`background_normal` and the
+    :attr:`background_down` properties. Can be used when using custom
+    backgrounds.
+
+    It must be a list of four values: (bottom, right, top, left). Read the
+    BorderImage instructions for more information about how to use it.
+
+    :attr:`border` is a :class:`~kivy.properties.ListProperty` and defaults to
+    (16, 16, 16, 16).
+    '''
+
+    overlay_color = ColorProperty([0, 0, 0, .7])
+    '''Overlay color in the format (r, g, b, a).
+    Used for dimming the window behind the modal view.
+
+    :attr:`overlay_color` is a :class:`~kivy.properties.ColorProperty` and
+    defaults to [0, 0, 0, .7].
+
+    .. versionadded:: 2.0.0
+    '''
+
+    # Internals properties used for graphical representation.
+
+    _anim_alpha = NumericProperty(0)
+
+    _anim_duration = NumericProperty(.1)
+
+    _window = ObjectProperty(allownone=True, rebind=True)
+
+    _is_open = BooleanProperty(False)
+
+    _touch_started_inside = None
+
+    __events__ = ('on_pre_open', 'on_open', 'on_pre_dismiss', 'on_dismiss')
+
+    def __init__(self, **kwargs):
+        self._parent = None
+        super(ModalView, self).__init__(**kwargs)
+
+    def open(self, *_args, **kwargs):
+        """Display the modal in the Window.
+
+        When the view is opened, it will be faded in with an animation. If you
+        don't want the animation, use::
+
+            view.open(animation=False)
+
+        """
+        from kivy.core.window import Window
+        if self._is_open:
+            return
+        self._window = Window
+        self._is_open = True
+        self.dispatch('on_pre_open')
+        Window.add_widget(self)
+        Window.bind(
+            on_resize=self._align_center,
+            on_keyboard=self._handle_keyboard)
+        self.center = Window.center
+        self.fbind('center', self._align_center)
+        self.fbind('size', self._align_center)
+        if kwargs.get('animation', True):
+            ani = Animation(_anim_alpha=1., d=self._anim_duration)
+            ani.bind(on_complete=lambda *_args: self.dispatch('on_open'))
+            ani.start(self)
+        else:
+            self._anim_alpha = 1.
+            self.dispatch('on_open')
+
+    def dismiss(self, *_args, **kwargs):
+        """ Close the view if it is open.
+
+        If you really want to close the view, whatever the on_dismiss
+        event returns, you can use the *force* keyword argument::
+
+            view = ModalView()
+            view.dismiss(force=True)
+
+        When the view is dismissed, it will be faded out before being
+        removed from the parent. If you don't want this animation, use::
+
+            view.dismiss(animation=False)
+
+        """
+        if not self._is_open:
+            return
+        self.dispatch('on_pre_dismiss')
+        if self.dispatch('on_dismiss') is True:
+            if kwargs.get('force', False) is not True:
+                return
+        if kwargs.get('animation', True):
+            Animation(_anim_alpha=0., d=self._anim_duration).start(self)
+        else:
+            self._anim_alpha = 0
+            self._real_remove_widget()
+
+    def _align_center(self, *_args):
+        if self._is_open:
+            self.center = self._window.center
+
+    def on_motion(self, etype, me):
+        super().on_motion(etype, me)
+        return True
+
+    def on_touch_down(self, touch):
+        """ touch down event handler. """
+        self._touch_started_inside = self.collide_point(*touch.pos)
+        if not self.auto_dismiss or self._touch_started_inside:
+            super().on_touch_down(touch)
+        return True
+
+    def on_touch_move(self, touch):
+        """ touch moved event handler. """
+        if not self.auto_dismiss or self._touch_started_inside:
+            super().on_touch_move(touch)
+        return True
+
+    def on_touch_up(self, touch):
+        """ touch up event handler. """
+        # Explicitly test for False as None occurs when shown by on_touch_down
+        if self.auto_dismiss and self._touch_started_inside is False:
+            self.dismiss()
+        else:
+            super().on_touch_up(touch)
+        self._touch_started_inside = None
+        return True
+
+    def on__anim_alpha(self, _instance, value):
+        """ animation progress callback. """
+        if value == 0 and self._is_open:
+            self._real_remove_widget()
+
+    def _real_remove_widget(self):
+        if not self._is_open:
+            return
+        self._window.remove_widget(self)
+        self._window.unbind(
+            on_resize=self._align_center,
+            on_keyboard=self._handle_keyboard)
+        self._is_open = False
+        self._window = None
+
+    def on_pre_open(self):
+        """ default pre-open event handler. """
+
+    def on_open(self):
+        """ default open event handler. """
+
+    def on_pre_dismiss(self):
+        """ default pre-dismiss event handler. """
+
+    def on_dismiss(self):
+        """ default dismiss event handler. """
+
+    def _handle_keyboard(self, _window, key, *_args):
+        if key == 27 and self.auto_dismiss:
+            self.dismiss()
+            return True
+
+
+if __name__ == '__main__':
+    from kivy.base import runTouchApp
+    from kivy.uix.button import Button
+    from kivy.core.window import Window
+    from kivy.uix.label import Label
+    from kivy.uix.gridlayout import GridLayout
+
+    # add view
+    content = GridLayout(cols=1)
+    content.add_widget(Label(text='This is a hello world'))
+    view = ModalView(size_hint=(None, None), size=(256, 256))
+    view.add_widget(content)
+
+    layout = GridLayout(cols=3)
+    for x in range(9):
+        btn = Button(text=f"click me {x}")
+        btn.bind(on_release=view.open)
+        layout.add_widget(btn)
+    Window.add_widget(layout)
+
+    view.open()
+    runTouchApp()