ae.kivy.widgets
ae.kivy.widgets module
this module provides constants and widgets for your multi-platform apps.
the generic constants for animations and vibration patterns (mostly used on mobile platforms).
most of the widgets provided by this module are based on the widgets of the Kivy framework, extended to work with app state variables, e.g. to support app styles and theming (dark or light) and user definable font sizes. some of them also change the application flow.
by importing this module the following generic widgets will be registered in the kivy widget class factory maps, to be available in the kv language for your app:
AppStateSlider
: extended version ofSlider
, changing the value of app state variables.FlowButton
: button to change the application flow.FlowDropDown
: attachable menu-like popup, based onDropDown
.FlowInput
: dynamic kivy widget based onTextInput
with application flow support.FlowPopup
: dynamic auto-content-sizing popup to query user input or to show messages.FlowSelector
: attachable popup used for dynamic elliptic auto-spreading menus and toolbars.FlowToggler
: toggle button based onImageLabel
andToggleButtonBehavior
to change the application flow or any flag or application state.HelpToggler
is a toggle button widget that switches the app’s help and tour mode on and off.ImageLabel
: dynamic kivy widget extending the KivyLabel
widget with an image.MessageShowPopup
: simple message box widget based onFlowPopup
.OptionalButton
: dynamic kivy widget based onFlowButton
which can be dynamically hidden.ShortenedButton
: dynamic kivy widget based onFlowButton
shortening the button text.Tooltip
displays text blocks that are automatically positioned next to any widget to providing e.g. i18n context help texts or app tour/onboarding info.UserNameEditorPopup
: popup window used e.g. to enter new user, finally registered in the app config files.
tooltip popup to display context-sensitive help and app tour texts
the tooltip popup widget class Tooltip
allows you to target any widget by pointing with an
arrow to it. the position and size of this widget gets automatically calculated from the targeted widget position and
size and the tooltip text size. and if the screen/window size is not big enough then the tooltip texts get scrollable.
Hint
use cases of the class Tooltip
are e.g. the help texts prepared and displayed by the
method help_display()
as well as the “explaining widget” tooltips in an app tour.
help activation and de-activation
use the widget class HelpToggler
provided by this module to toggle
the active state of the help mode.
Hint
the HelpToggler
class is using the low-level touch events to prevent the dispatch of the
Kivy events on_press, on_release and on_dismiss, to allow to show help texts for opened dropdowns and popups,
without closing/dismissing them.
to attach help texts to your widget instances add the behavior class HelpBehavior
.
Module Attributes
sine 3 x deeper repeating animation, used e.g. |
|
very long/~2.4s vibrate pattern for critical error notification (sending SOS to the mobile world;) |
|
long/~2s vibrate pattern for error notification. |
|
short/~1.2s vibrate pattern for fun/love notification. |
|
default file name of the main kv file of your app |
Classes
|
propagate changes of pos/size properties of one or more widgets plus their parents to attributes/callbacks. |
|
slider widget with help text to change app state value. |
|
overwrite/extend |
|
button to change the application flow. |
|
flow based widget class to implement dynamic menu-like user selections and toolbars. |
|
text input/edit widget with optional autocompletion. |
|
popup for dynamic and auto-sizing dialogs and other top-most or modal windows. |
|
attachable popup used for dynamic elliptic auto-spreading menus and toolbars. |
|
toggle button changing flow id. |
|
widget to activate and deactivate the help mode. |
|
base label used for all labels and buttons - declared in widgets.kv and also in this module to inherit from. |
|
flow popup to display info or error messages. |
|
semi-transparent and optional click-through container to display help and tour page texts. |
- ANI_SINE_DEEPER_REPEAT3 = <kivy.animation.Sequence object>
sine 3 x deeper repeating animation, used e.g. to animate help layout (see
Tooltip
widget)
- CRITICAL_VIBRATE_PATTERN = (0.0, 0.12, 0.12, 0.12, 0.12, 0.12, 0.12, 0.24, 0.12, 0.24, 0.12, 0.24, 0.12, 0.12, 0.12, 0.12, 0.12, 0.12)
very long/~2.4s vibrate pattern for critical error notification (sending SOS to the mobile world;)
- ERROR_VIBRATE_PATTERN = (0.0, 0.09, 0.09, 0.18, 0.18, 0.27, 0.18, 0.36, 0.27, 0.45)
long/~2s vibrate pattern for error notification.
- LOVE_VIBRATE_PATTERN = (0.0, 0.12, 0.12, 0.21, 0.03, 0.12, 0.12, 0.12)
short/~1.2s vibrate pattern for fun/love notification.
- MAIN_KV_FILE_NAME = 'main.kv'
default file name of the main kv file of your app
- class AbsolutePosSizeBinder(*widgets, bind_window_size=False)[source]
Bases:
object
propagate changes of pos/size properties of one or more widgets plus their parents to attributes/callbacks.
create an instance of this class passing the widget(s) to observe on change of their pos/size. then call the methods
pos_to_attribute()
,pos_to_callback()
,size_to_attribute()
andsize_to_callback()
to specify the propagation of the changed pos and/or size. to remove the change propagation call the methodunbind()
.Note
the pos attribute/callback propagations are providing absolute window coordinates.
- __init__(*widgets, bind_window_size=False)[source]
instantiate binder specifying the monitored widget(s).
- Parameters:
widgets¶ (
Widget
) – widget(s) to observe changes of their pos and size properties. if specified more than one widget then the pos/size coordinates of the rectangle that is enclosing all specified widgets are propagated.bind_window_size¶ (
bool
) – pass True to propagate pos and size changes if window size changes.
- _wid_pos_changed(wid, new_pos)[source]
propagate pos property change to target attributes and subscribed observers.
- _wid_size_changed(wid, new_size)[source]
propagate size property change to target attributes and subscribed observers.
- _rel_pos_changed(_rel, _new_pos)[source]
propagate pos property change of relative/scrollable layout/container.
- _rel_size_changed(_rel, _new_size)[source]
propagate size change of relative/scrollable layout/container.
- pos_to_attribute(target, attribute, converter=None)[source]
request the propagation of the changed (absolute) widget(s) position to an object attribute.
- Parameters:
target¶ (
Any
) – the object which attribute will be changed on change of pos.attribute¶ (
str
) – the name of the attribute to assign the new/changed absolute position.converter¶ (
Optional
[Callable
[[Widget
,List
[float
]],Any
]]) – optional pos value converter, returning the final value assigned to the attribute.
- size_to_attribute(target, attribute, converter=None)[source]
request the propagation of the changed widget(s) size to an object attribute.
- Parameters:
- class AppStateSlider(**kwargs)[source]
Bases:
HelpBehavior
,ShadersMixin
,Slider
slider widget with help text to change app state value.
- app_state_name
name of the app state to be changed by this slider value
- class HelpToggler(**kwargs)[source]
Bases:
ReliefCanvas
,Image
widget to activate and deactivate the help mode.
To prevent dismiss of opened popups and dropdowns at help mode activation, this singleton instance has to:
be registered in its __init__ to the
help_activator
attribute andhave a
on_touch_down()
method that is eating the activation touch event (returning True) anda
on_touch_down()
method not passing an activation touch in all DropDown/Popup widgets.
- ani_value
float value (range: 0.0 - 1.0) to animate this button in help/tour mode
- __init__(**kwargs)[source]
initialize an instance of this class and also
help_activator
.
- on_touch_down(touch)[source]
touch down event handler to toggle help mode while preventing dismiss of open dropdowns/popups.
- Parameters:
touch¶ (
MotionEvent
) – touch event.- Return type:
- Returns:
True if touch happened on this button (and will get no further processed => eaten).
- class ImageLabel(**kwargs)[source]
Bases:
ReliefCanvas
,ShadersMixin
,Label
base label used for all labels and buttons - declared in widgets.kv and also in this module to inherit from.
Note
hide-able label needs extra handling, because even setting width/height to zero the text can still be visible, especially in dark mode and even with having the text-color-alpha==0. to fully hide the texture in all cases, set either the text to an empty string or the opacity to zero.
- __repr__()[source]
added for easier debugging of
FlowButton
andFlowToggler
widgets.
- class FlowButton(**kwargs)[source]
Bases:
HelpBehavior
,SlideSelectBehavior
,TouchableBehavior
,ButtonBehavior
,ImageLabel
button to change the application flow.
- long_tap_flow_id
flow id that will be set when this button gets long tap event
- tap_flow_id
the new flow id that will be set when this button get tapped
- tap_kwargs
kwargs dict passed to event handler (change_flow) when button get tapped
- on_long_tap(touch)[source]
long tap/click default handler.
- Parameters:
touch¶ (
MotionEvent
) – motion/touch event data with the touched widget in touch.grab_current.
- class FlowDropDown(**kwargs)[source]
Bases:
ContainerChildrenAutoWidthBehavior
,DynamicChildrenBehavior
,SlideSelectBehavior
,ReliefCanvas
,DropDown
flow based widget class to implement dynamic menu-like user selections and toolbars.
- close_kwargs
kwargs passed to all close action flow change event handlers
- content
layout container
container/content children, like buttons, text inputs or sliders
- parent_popup_to_close
parent popup widget instance to be closed if this dropdown closes
- _real_dismiss(*_args)[source]
overridden to ensure that return value of on_dismiss-dispatch get recognized.
- dismiss(*args)[source]
override DropDown method to prevent dismiss of any dropdown/popup while clicking on activator widget.
- Parameters:
args¶ – args to be passed to DropDown.dismiss().
- close(*args)
override DropDown method to prevent dismiss of any dropdown/popup while clicking on activator widget.
- Parameters:
args¶ – args to be passed to DropDown.dismiss().
- on_container(instance, value)[source]
sync
content
widget andmenu_items
list with container widget.
- on_touch_down(touch)[source]
prevent the processing of a touch on the help activator widget by this dropdown.
- Parameters:
touch¶ (
MotionEvent
) – motion/touch event data.- Return type:
- Returns:
True if event got processed/used.
- class ExtTextInputCutCopyPaste(**kwargs)[source]
Bases:
TextInputCutCopyPaste
overwrite/extend
kivy.uix.textinput.TextInputCutCopyPaste
w/ translatable and autocomplete options.- __init__(**kwargs)[source]
create
Bubble
instance to display the cut/copy/paste options.the monkey patch of
TextInputCutCopyPaste
which was done inFlowInput._show_cut_copy_paste()
has to be temporarily reset before the super() call below, to prevent endless recursion because else the other super(cls, instance) call (in python2 style withinTextInputCutCopyPaste.__init__()
) results in the same instance (instead of the overwritten instance).
- class FlowInput(**kwargs)[source]
Bases:
HelpBehavior
,ShadersMixin
,TextInput
text input/edit widget with optional autocompletion.
until version 0.1.43 of this portion the background and text color of
FlowInput
did automatically get switched by a change of the light_theme app state. now all colors left unchanged (before only the ones with <unchanged>):* background_color: Window.clearcolor # default: 1, 1, 1, 1 * cursor_color: app.font_color # default: 1, 0, 0, 1 * disabled_foreground_color: <unchanged> # default: 0, 0, 0, .5 * foreground_color: app.font_color # default: 0, 0, 0, 1 * hint_text_color: <unchanged> # default: 0.5, 0.5, 0.5, 1.0 * selection_color: <unchanged> # default: 0.1843, 0.6549, 0.8313, .5
- to implement a dark background for the dark theme we would need also to change the images in the properties:
background_active, background_disabled_normal and self.background_normal.
the images/colors of the bubble that is showing e.g. on long press of the TextInput widget (cut/copy/paste/…) kept unchanged - only the font_size get adapted and the bubble button texts get translated. for that the class
ExtTextInputCutCopyPaste
provided by this portion inherits from the original bubble classTextInputCutCopyPaste
.the original bubble class is getting monkey patched shortly/temporarily in the moment of the instantiation to translate the bubble menu options, change the font sizes and add additional menu options to memorize/forget auto-completion texts.
- focus_flow_id
flow id that will be set when this widget get focus
- unfocus_flow_id
flow id that will be set when this widget lost focus
-
auto_complete_selector_index_ink:
Union
[Tuple
[float
,float
,float
],List
[float
],Tuple
[float
,float
,float
,float
]] color and alpha used to highlight the currently selected text of all matching autocompletion texts
- _change_selector_index(delta)[source]
change/update/set the index of the matching texts in the opened autocompletion dropdown.
- delete_text_from_ac(*_args)[source]
check if current text is in autocompletion list and if yes then remove it.
called by FlowInput kbd event handler and from menu button added by ExtTextInputCutCopyPaste.on_parent().
- Parameters:
_args¶ – unused event args.
- extend_ac_with_text(*_args)[source]
add non-empty text to autocompletion texts.
- Parameters:
_args¶ – unused event args.
- keyboard_on_key_down(window, keycode, text, modifiers)[source]
overwritten TextInput/FocusBehavior kbd event handler.
- Parameters:
- Return type:
- Returns:
True if key event get processed/used by this method.
- keyboard_on_textinput(window, text)[source]
overridden to suppress any user input if tour is running/active.
- class FlowPopup(**kwargs)[source]
Bases:
ModalBehavior
,DynamicChildrenBehavior
,SlideSelectBehavior
,ReliefCanvas
,BoxLayout
popup for dynamic and auto-sizing dialogs and other top-most or modal windows.
the scrollable
container
(aScrollView
instance) can only have one child, referenced by thecontent
attribute, which can be any widget (e.g. a label). use a layout forcontent
to display multiple widgets. setoptimal_content_width
and/oroptimal_content_height
to make the popup size as small as possible, using e.g. minimum_width respectively minimum_height ifcontent
is a layout that is providing and updating this property, ortext_size_guess()
if it is a label or button widget.Hint
texture_size
could provide a more accurate size thantext_size_guess()
, but should be used with care to prevent recursive property change loops.this class is very simular to
Popup
and can be used as replacement, incompatible are the following attributes ofPopup
andModalView
:background
: FlowPopup has noBorderImage
.border
: FlowPopup is using aRoundedRectangle
.title_align
: is ‘center’ and could be changed via the title_bar id.title_color
is the app.font_color.title_font
is the default font.title_size
is the default button height (button_height
).
- Events:
- on_pre_open:
fired before the FlowPopup is opened and got added to the main window.
- on_open:
fired when the FlowPopup is opened.
- on_pre_dismiss:
fired before the FlowPopup is closed.
- on_dismiss:
fired when the FlowPopup is closed. if the callback returns True, the popup will stay opened.
- close_kwargs
kwargs passed to all close action flow change event handlers.
close_kwargs
is aDictProperty
. the default depends the action of the penultimate flow id in theae.gui_app.flow_path
: is empty or ‘enter’ dict then it defaults to an empty flow, else to an empty dict.
- container: Widget
popup scrollable layout underneath the title bar and the parent of the
content
container.container
is anObjectProperty
and is read-only.
- content
popup main content container, displayed as a child of the scrollable layout
container
.content
is anObjectProperty
and has to be specified either in the kv language as children or via the content kwarg.
sequence of the content widgets and close button.
menu_items
is anObjectProperty
and includes by default the content widgets as well as the close button of this popup.
- optimal_content_width
width of the content to be fully displayed/visible.
optimal_content_width
is aNumericProperty
. if 0 or None or not explicitly set then it defaults to the main window width and - in landscape orientation - minus theside_spacing
and the width needed by thequery_data_maps
widgets.
- optimal_content_height
height of the content to be fully displayed/visible.
optimal_content_height
is aNumericProperty
. if 0 or None or not explicitly set then it defaults to the main window height minus the height oftitle
and - in portrait orientation - minus theside_spacing
and the height needed by thequery_data_maps
widgets.
- parent_popup_to_close
parent popup widget instance to be closed if this popup closes.
parent_popup_to_close
is aObjectProperty
and defaults to None.
-
query_data_maps:
List
[Dict
[str
,Any
]] list of child data dicts to instantiate the query widgets (most likely
FlowButton
) of this popup.query_data_maps
is aListProperty
and defaults to an empty list.
- separator_height
height of the separator.
separator_height
is aNumericProperty
and defaults to 3sp.
- side_spacing
padding in pixels from Window.width in landscape-orientation, and from Window.height in portrait-orientation.
side_spacing
is aNumericProperty
and defaults to 192sp.
- title
title string of the popup.
title
is aStringProperty
and defaults to an empty string.
- _anim_alpha
internal opacity/alpha for fade-in/-out animations
- _anim_duration
internal time in seconds for fade-in/-out animations
- _max_height
popup max height (calculated from Window/side_spacing)
- _max_width
popup max width (calculated from Window/side_spacing)
- __events__ = ('on_pre_open', 'on_open', 'on_pre_dismiss', 'on_dismiss')
- background_color
background ink tuple in the format (red, green, blue, alpha).
the
background_color
is aColorProperty
and defaults toclearcolor
.
- overlay_color
ink (color + alpha) tuple in the format (red, green, blue, alpha) used for dimming of the main window.
overlay_color
is aColorProperty
and defaults to the current color valueclearcolor
with an alpha of 0.6 (set in__init__()
).
- separator_color
color used by the separator between title and the content-/container-layout.
separator_color
is aColorProperty
and defaults to the current value of thefont_color
property.
- add_widget(widget, index=0, canvas=None)[source]
add container and content widgets.
first call set container from kv rule, 2nd the content, 3rd raise error.
- close(*_args, **kwargs)[source]
close/dismiss container/layout (ae.gui_app popup handling compatibility for all GUI frameworks).
Note
prevents close/dismiss of any dropdown/popup while clicking on help activator widget.
- on_content(_instance, value)[source]
optional single widget (to be added to the container layout) set directly or via FlowPopup kwargs.
- class FlowSelector(**kwargs)[source]
Bases:
ModalBehavior
,DynamicChildrenBehavior
,FlowButton
attachable popup used for dynamic elliptic auto-spreading menus and toolbars.
this app flow based menu-like popup consists of a central button and animated elliptic-auto-spreading menu items.
any widget class can be used for the menu items of this class, although
ShortenedButton
instances are best-prepared to auto-shorten the text property.- Events:
- on_pre_open:
fired before the FlowSelector is opened and got added to the main window.
- on_open:
fired when the FlowSelector is opened.
- on_pre_dismiss:
fired before the FlowSelector is closed.
- on_dismiss:
fired when the FlowSelector is closed. if the callback returns True, the menu will stay opened.
inspired by https://github.com/kivy-garden/garden.modernmenu
- attached_widget
widget from which this instance got opened.
The
open()
method will automatically set this property whilstclose()
will set it back to None.
- close_kwargs
kwargs passed to all close action flow change event handlers.
close_kwargs
is aDictProperty
. the default depends the action of the penultimate flow id in theae.gui_app.flow_path
: is empty or ‘enter’ dict then it defaults to an empty flow, else to an empty dict.
- is_open
True if the
open()
method of this instance got called.close()
sets this value to False.is_open
is aBooleanProperty
and defaults to False.
- parent_popup_to_close
parent menu/popup widget instance to be closed if this menu closes.
parent_popup_to_close
is aListProperty
and defaults to an empty list.
- radian_offset
start/end angle offset (in radians) for the elliptically positioned items of an elliptic menu.
radian_offset
is aNumericProperty
and defaults to 9 degrees (as radian, respectivelytau * 9.0 / 360.0
).
- separator_height
line width of the border of the menu-back-button and of the connectors between the menu and its items.
separator_height
is aNumericProperty
and defaults to 1sp.
- scale_x
spread/widen factor of the menu item ellipse in x direction.
scale_x
is aNumericProperty
and defaults to 1.0.
- scale_y
spread/widen factor of the menu item ellipse in y direction.
scale_y
is aNumericProperty
and defaults to 1.0.
- _anim_alpha
internal opacity/alpha for fade-in/-out animations
- _anim_duration
internal time in seconds for fade-in/-out animations
- _creation_direction = 1.0
creation-ellipse-direction of the menu buttons/items
- _start_radian = 0.0
angle of the first menu item
- _item_radian = 0.0
angle of each menu item
- __events__ = ('on_pre_open', 'on_open', 'on_pre_dismiss', 'on_dismiss')
- overlay_color
ink (color + alpha) tuple in the format (red, green, blue, alpha) used for dimming of the main window.
overlay_color
is aColorProperty
and defaults to the current color valueclearcolor
with an alpha of 0.6 (set in__init__()
).
- separator_color
color used to draw the border of the menu-back-button.
separator_color
is aColorProperty
and defaults to the current value of thefont_color
property.
- container: Widget
parent widget of the menu items (for compatibility with other popups/dropdowns).
container
is anObjectProperty
and is read-only.
sequence of the menu items widgets (for compatibility with
SlideSelectBehavior
).menu_items
is anListProperty
and defaults to the items specified via thechild_data_maps
property and the kv language.
- _layout_items(*_args)[source]
calculate the radians/angles and positions of the menu-items.
given an offset angle of 9 degrees the (start-angle direction menu-item-angle) for the 9 block regions from top-left … center/middle … bottom-right would be:
left
center
right
top
0 -72
180+180
180 +72
middle
81-162
90+360
99+162
bottom
72 -72
180-180
108 +72
- add_widget(widget, index=0, canvas=None)[source]
manage children added via kv, python and
ae.kivy_dyn_chi.DynamicChildrenBehavior
.
- close(*_args, **kwargs)[source]
close/dismiss menu (ae.gui_app popup handling compatibility for all GUI frameworks).
Note
prevents close/dismiss of any dropdown/popup while clicking on help activator widget.
- Parameters:
_args¶ – arguments (to have compatible signature for DropDown/Popup/ModalView widgets).
kwargs¶ – keyword arguments (compatible signature for DropDown/Popup/ModalView widgets): force: pass True to force closing, ignoring return value of dispatch(‘on_dismiss’) animation: pass False to close this menu without fade-out animation
- open(attach_to, **kwargs)[source]
display flow selector menu items, with animation and as a popup in modal mode.
- class FlowToggler(**kwargs)[source]
Bases:
HelpBehavior
,SlideSelectBehavior
,TouchableBehavior
,ToggleButtonBehavior
,ImageLabel
toggle button changing flow id.
- long_tap_flow_id
flow id that will be set when this button gets long tap event
- tap_flow_id
the new flow id that will be set when this toggle button get released
- tap_kwargs
kwargs dict passed to event handler (change_flow) when button get tapped
- on_long_tap(touch)[source]
long tap/click default handler.
- Parameters:
touch¶ (
MotionEvent
) – motion/touch event data with the touched widget in touch.grab_current.
- class MessageShowPopup(**kwargs)[source]
Bases:
FlowPopup
flow popup to display info or error messages.
- _container: Widget
- attach_to: Optional[Widget]
- _layout_finished: bool
- _opened_item: Optional[Widget]
- _touch_moved_outside: bool
- message
popup window message text to display
- title
popup window title text to display
- class Tooltip(**kwargs)[source]
Bases:
ScrollView
semi-transparent and optional click-through container to display help and tour page texts.
- tip_text
tooltip text string to display.
tip_text
is aStringProperty
and defaults to an empty string.
- anchor_spe
anchor pos and direction, see
AnchorSpecType
(read-only)
- has_tour
True if a tour exists for the current app flow/help context (read-only)
- tap_thru
True if user can tap widgets behind/covered by this tooltip win (read-only)
- tour_start_pos
screen position of the optionally displayed tour start button (read-only)
- tour_start_size
size of the optionally displayed tour start button (read-only)
- targeted_widget
target widget to display tooltip text for (mostly a button, but could any, e.g. a layout widget).
targeted_widget
is aObjectProperty
and defaults to the main app help_activator.
- collide_tap_thru_toggler(touch_x, touch_y)[source]
check if touch is on the tap through toggler pseudo button.
- collide_tour_start_button(touch_x, touch_y)[source]
check if touch is on the tap through toggler pseudo button.
- on_size(*_args)[source]
(re-)position help_activator tooltip correctly after help text loading and layout resizing.
- on_targeted_widget(*_args)[source]
targeted widget changed event handler.
- Parameters:
_args¶ – change event args (unused).
- on_touch_down(touch)[source]
check for additional events added by this class.
- Parameters:
touch¶ (
MotionEvent
) – motion/touch event data.- Return type:
- Returns:
True if event got processed/used.