Touch & Ripple Behaviors¶
morphui.uix.behaviors.touch
¶
MorphButtonBehavior(**kwargs)
¶
Bases: EventDispatcher
A mixin class that provides button-like behavior to widgets.
This behavior can be mixed into other widgets to give them the ability to respond to press and release events, similar to a button. It defines properties and methods for handling touch events and managing the pressed state of the widget.
The behavior dispatches press/release events similar to
:class:~kivy.uix.behaviors.ButtonBehavior.
Events
on_press() -> None
Event fired when the widget is pressed.
on_release() -> None
Event fired when the widget is released.
Examples:
Create a button-like label:
class ButtonLabel(MorphButtonBehavior, Label):
pass
label = ButtonLabel(text="Click me")
label.bind(on_press=lambda instance: print("Pressed!"))
label.bind(on_release=lambda instance: print("Released!"))
always_release = BooleanProperty(True)
class-attribute
instance-attribute
¶
Whether to always trigger the release action on touch up.
When set to True, the release action will be triggered on touch up events, regardless of whether the touch up occurs within the bounds of the widget. This can be useful for ensuring that the release action is always executed after a press.
:attr:always_release is a
:class:~kivy.properties.BooleanProperty and defaults to True.
pressed = BooleanProperty(False)
class-attribute
instance-attribute
¶
Indicates whether the widget is currently being pressed.
This property is set to True when a touch event begins on the widget and is set to False when the touch event ends. It can be used to track the pressed state of the widget for visual feedback or other logic.
:attr:pressed is a :class:~kivy.properties.BooleanProperty
and defaults to False.
active = BooleanProperty(False)
class-attribute
instance-attribute
¶
Indicates whether the widget is currently active.
This property is set to True when the widget is in an active state (e.g., pressed or toggled on) and is set to False when it is not active. It can be used to track the active state of the widget for visual feedback or other logic.
:attr:active is a :class:~kivy.properties.BooleanProperty
and defaults to False.
min_state_time = NumericProperty(0.035)
class-attribute
instance-attribute
¶
The minimum period of time which the widget must remain in the 'down' state.
This property defines the minimum duration that the widget must remain in the 'down' state before it can be released. This can help prevent accidental taps or quick presses from triggering the release action too quickly.
:attr:min_state_time is a :class:~kivy.properties.NumericProperty
and defaults to 0.035.
on_touch_down(touch)
¶
Handle touch down events to initiate the press action.
This method is called when a touch event begins on the widget. If the touch event occurs within the widget's bounds, the press action will be triggered.
If the widget also includes ripple behavior (e.g.,
:class:MorphRippleBaseBehavior), it will be called to display
the ripple effect.
| PARAMETER | DESCRIPTION |
|---|---|
touch
|
The touch event that triggered the press action.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
bool
|
True if the touch event was handled, False otherwise. |
Notes
This implementation is based on Kivy button behavior's, see
:meth:~kivy.uix.behaviors.ButtonBehavior.on_touch_down
on_touch_move(touch)
¶
Handle touch move events to update the pressed state.
This method is called when a touch event moves within the widget. If the touch is still within the widget's bounds, the pressed state will be maintained.
If the touch moves outside the widget's bounds, and a ripple animation is in progress, the ripple animation will be finished.
| PARAMETER | DESCRIPTION |
|---|---|
touch
|
The touch event that triggered the move action.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
bool
|
True if the touch event was handled, False otherwise. |
Notes
This implementation is based on Kivy button behavior's, see
:meth:~kivy.uix.behaviors.ButtonBehavior.on_touch_move.
on_touch_up(touch)
¶
Handle touch up events to complete the press action.
This method is called when a touch event ends on the widget. If the touch event was previously registered, the release action will be triggered.
If the widget also includes ripple behavior (e.g.,
:class:MorphRippleBaseBehavior), it will be called to finish
the ripple animation.
| PARAMETER | DESCRIPTION |
|---|---|
touch
|
The touch event that triggered the release action.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
bool | None
|
True if the touch event was handled, False otherwise. None if the widget is disabled or if the release action is not allowed due to touch being outside the widget bounds. |
Notes
This implementation is based on Kivy button behavior's, see
:meth:~kivy.uix.behaviors.ButtonBehavior.on_touch_up
trigger_action(duration=0.1)
¶
Programmatically trigger a press and release action.
This method simulates a press and release action on the widget. It can be used to programmatically activate the button behavior without user interaction.
| PARAMETER | DESCRIPTION |
|---|---|
duration
|
The duration (in seconds) to wait between the press and release actions. Default is 0.1 seconds.
TYPE:
|
Notes
This implementation is based on Kivy button behavior's, see
:meth:~kivy.uix.behaviors.ButtonBehavior.trigger_action
on_press()
¶
Event fired when the widget is pressed.
This event is dispatched when a touch down event occurs on the widget and the widget is not disabled. It can be used to trigger custom behavior when the widget is pressed.
on_release()
¶
Event fired when the widget is released.
This event is dispatched when a touch up event occurs on the widget and the widget is not disabled. It can be used to trigger custom behavior when the widget is released.
MorphRippleBehavior(**kwargs)
¶
Bases: EventDispatcher
A base behavior class that provides ripple effect functionality.
This behavior can be mixed into other widgets to add a ripple effect that responds to touch events. It defines properties for customizing the appearance and animation of the ripple effect, as well as methods for handling touch events and managing the ripple animation.
This class is intended to be subclassed by specific ripple effect
implementations, which should define the ripple_canvas_instructions
method to specify how the ripple effect is drawn on the canvas.
ripple_color = ColorProperty(None)
class-attribute
instance-attribute
¶
The color of the ripple effect.
This property defines the color of the ripple effect when it is displayed. It is specified as a list of four floats representing the RGBA color components, each ranging from 0 to 1.
If set to None, ripple color will fall back to interaction color with pressed state opacity, if available, otherwise to gray.
:attr:ripple_color is a
:class:~kivy.properties.ColorProperty and defaults to gray
([0.75, 0.75, 0.75, 0.5]).
ripple_duration_in = NumericProperty(0.2)
class-attribute
instance-attribute
¶
The duration of the ripple fade-in animation in seconds.
This property defines how long it takes for the ripple effect to fully appear after a touch event. A shorter duration results in a quicker ripple effect, while a longer duration creates a slower, more pronounced effect.
:attr:ripple_duration_in is a
:class:~kivy.properties.NumericProperty and defaults to 0.3.
ripple_duration_in_long = NumericProperty(1.2)
class-attribute
instance-attribute
¶
The duration of the ripple fade-in animation for long presses.
This property defines how long it takes for the ripple effect to fully appear during a long press touch event. A longer duration results in a more pronounced ripple effect.
:attr:ripple_duration_in_long is a
:class:~kivy.properties.NumericProperty and defaults to 0.6.
ripple_duration_out = NumericProperty(0.2)
class-attribute
instance-attribute
¶
The duration of the ripple fade-out animation in seconds.
This property defines how long it takes for the ripple effect to disappear after being fully visible. A shorter duration results in a quicker fade-out effect, while a longer duration creates a slower, more gradual effect.
:attr:ripple_duration_out is a
:class:~kivy.properties.NumericProperty and defaults to 0.3.
ripple_transition_in = StringProperty('out_sine')
class-attribute
instance-attribute
¶
The easing function used for the ripple fade-in animation.
This property defines the easing function that controls the acceleration and deceleration of the ripple effect as it fades in.
:attr:ripple_transition_in is a
:class:~kivy.properties.StringProperty and defaults to 'out_sine'.
ripple_transition_out = StringProperty('in_sine')
class-attribute
instance-attribute
¶
The easing function used for the ripple fade-out animation.
This property defines the easing function that controls the acceleration and deceleration of the ripple effect as it fades out.
:attr:ripple_transition_out is a
:class:~kivy.properties.StringProperty and defaults to 'in_sine'.
ripple_enabled = BooleanProperty(True)
class-attribute
instance-attribute
¶
Whether the ripple effect is enabled.
This property allows for enabling or disabling the ripple effect dynamically. When set to True, the ripple effect will be shown on touch events. When set to False, no ripple effect will be displayed, but the touch events will still be processed normally.
:attr:ripple_enabled is a
:class:~kivy.properties.BooleanProperty and defaults to True.
ripple_pos = ListProperty([0, 0], length=4)
class-attribute
instance-attribute
¶
The position of the ripple effect on the widget.
This property defines the (x, y) coordinates where the ripple effect originates. The coordinates are relative to the widget's position.
:attr:ripple_pos is a
:class:~kivy.properties.ListProperty and defaults to [0, 0].
ripple_initial_radius = NumericProperty(5.0)
class-attribute
instance-attribute
¶
The initial radius of the ripple effect when it starts.
This property defines the starting size of the ripple effect when a touch event occurs. A value of 0 means the ripple starts from a point, while higher values make the ripple start larger.
This property can be adjusted to create different visual effects for the ripple animation, allowing for greater flexibility in design.
:attr:ripple_initial_radius is a
:class:~kivy.properties.NumericProperty and defaults to 15.
ripple_layer = OptionProperty('interaction', options=('interaction', 'overlay'))
class-attribute
instance-attribute
¶
The layer on which the ripple effect is drawn.
This property allows you to specify whether the ripple effect should be drawn on the 'interaction' layer (between surface and content) or the 'overlay' layer (on top of the widget).
:attr:ripple_layer is a
:class:~kivy.properties.OptionProperty and defaults to 'interaction'.
determine_ripple_color()
¶
Get the effective ripple color, falling back to interaction color.
This method returns the ripple color if it is set, otherwise it tries to use the interaction color with the pressed state opacity. If neither is available, it defaults to a gray color.
| RETURNS | DESCRIPTION |
|---|---|
List[float]
|
The effective ripple color. |
show_ripple_effect(touch_pos)
¶
Display the ripple effect for a touch event if ripple is enabled.
| PARAMETER | DESCRIPTION |
|---|---|
touch_pos
|
The position of the touch event.
TYPE:
|
start_ripple_animation()
¶
Start the ripple animation.
finish_ripple_animation()
¶
Finish the ripple animation immediately.
fade_ripple_animation(*args)
¶
Fade out the ripple animation.
ripple_canvas_instructions()
¶
Define the canvas instructions for rendering the rectangular ripple effect.
This method creates the necessary canvas instructions to draw a rounded rectangular ripple effect that expands from the touch point.
Notes
- The ripple is drawn using a RoundedRectangle instruction, with its size determined by the current ripple radius.
- Stencil instructions are used to ensure the ripple is clipped to the bounds of the widget.
- Call :meth:
_evaluate_ripple_posbefore invoking this method to set the correct ripple position.
trigger_ripple(*args)
¶
Manually trigger the ripple effect at the center of the widget.
This method can be used to programmatically display the ripple effect at the center of the widget, without requiring a touch event.
MorphToggleButtonBehavior(**kwargs)
¶
Bases: MorphButtonBehavior
A mixin class that provides toggle button behavior to widgets.
This behavior can be mixed into other widgets to give them the ability to act as toggle buttons, allowing them to switch between 'normal' and 'down' states. It supports grouping of toggle buttons to allow only one button in a group to be in the 'down' state at a time.
The behavior dispatches press/release events similar to
:class:~kivy.uix.behaviors.ButtonBehavior.
Properties
state : str The current state of the toggle button, either 'normal' or 'down'. group : str | None The group identifier for the toggle button. Buttons in the same group will enforce mutual exclusivity. allow_no_selection : bool Whether the toggle button allows no selection in its group.
Events
on_press() -> None
Event fired when the widget is pressed.
on_release() -> None
Event fired when the widget is released.
Examples:
Create a toggle button:
class MyToggleButton(MorphToggleButtonBehavior, Button):
pass
toggle_button = MyToggleButton(text="Toggle me")
toggle_button.bind(on_press=lambda instance: print("Pressed!"))
toggle_button.bind(on_release=lambda instance: print("Released!"))
Notes
This implementation is based on Kivy's ToggleButtonBehavior, see
:class:~kivy.uix.behaviors.ToggleButtonBehavior.
group = StringProperty(None, allownone=True)
class-attribute
instance-attribute
¶
The group identifier for the toggle button.
Buttons in the same group will enforce mutual exclusivity, meaning that only one button in the group can be in the 'down' state at a time.
:attr:group is a :class:~kivy.properties.StringProperty
and defaults to None.
allow_no_selection = BooleanProperty(True)
class-attribute
instance-attribute
¶
Whether the toggle button allows no selection in its group.
If set to True, the toggle button can be deselected, allowing
no button in the group to be in the 'active' state. If set to
False, at least one button in the group must be active at
all times.
:attr:allow_no_selection is a :class:~kivy.properties.BooleanProperty
and defaults to True.
get_widgets(group)
staticmethod
¶
Get all toggle button widgets in the specified group.
This static method retrieves all toggle button instances that belong to the specified group.
| PARAMETER | DESCRIPTION |
|---|---|
group
|
The group identifier.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
List[Any]
|
A list of toggle button instances in the specified group. |
refresh_toggle_group()
¶
Refresh the toggle button's group registration.
This method ensures that the toggle button is correctly registered in its current group. It removes the button from its previous group (if any) and adds it to the new group.