TapTargetView¶
Provide value and improve engagement by introducing users to new features and functionality at relevant moments.
Usage¶
from kivy.lang import Builder
from kivymd.app import MDApp
from kivymd.uix.taptargetview import MDTapTargetView
KV = '''
Screen:
MDFloatingActionButton:
id: button
icon: "plus"
pos: 10, 10
on_release: app.tap_target_start()
'''
class TapTargetViewDemo(MDApp):
def build(self):
screen = Builder.load_string(KV)
self.tap_target_view = MDTapTargetView(
widget=screen.ids.button,
title_text="This is an add button",
description_text="This is a description of the button",
widget_position="left_bottom",
)
return screen
def tap_target_start(self):
if self.tap_target_view.state == "close":
self.tap_target_view.start()
else:
self.tap_target_view.stop()
TapTargetViewDemo().run()
Widget position¶
Sets the position of the widget relative to the floating circle.
self.tap_target_view = MDTapTargetView(
...
widget_position="right",
)
self.tap_target_view = MDTapTargetView(
...
widget_position="left",
)
self.tap_target_view = MDTapTargetView(
...
widget_position="top",
)
self.tap_target_view = MDTapTargetView(
...
widget_position="bottom",
)
self.tap_target_view = MDTapTargetView(
...
widget_position="left_top",
)
self.tap_target_view = MDTapTargetView(
...
widget_position="right_top",
)
self.tap_target_view = MDTapTargetView(
...
widget_position="left_bottom",
)
self.tap_target_view = MDTapTargetView(
...
widget_position="right_bottom",
)
If you use the widget_position = "center"
parameter then you must
definitely specify the title_position
.
self.tap_target_view = MDTapTargetView(
...
widget_position="center",
title_position="left_top",
)
Text options¶
self.tap_target_view = MDTapTargetView(
...
title_text="Title text",
description_text="Description text",
)
You can use the following options to control font size, color, and boldness:
self.tap_target_view = MDTapTargetView(
...
title_text="Title text",
title_text_size="36sp",
description_text="Description text",
description_text_color=[1, 0, 0, 1]
)
But you can also use markup to set these values.
self.tap_target_view = MDTapTargetView(
...
title_text="[size=36]Title text[/size]",
description_text="[color=#ff0000ff]Description text[/color]",
)
Events control¶
self.tap_target_view.bind(on_open=self.on_open, on_close=self.on_close)
def on_open(self, instance_tap_target_view):
'''Called at the time of the start of the widget opening animation.'''
print("Open", instance_tap_target_view)
def on_close(self, instance_tap_target_view):
'''Called at the time of the start of the widget closed animation.'''
print("Close", instance_tap_target_view)
Note
See other parameters in the MDTapTargetView
class.
API - kivymd.uix.taptargetview
¶
- class kivymd.uix.taptargetview.MDTapTargetView(**kwargs)¶
Rough try to mimic the working of Android’s TapTargetView.
- Events
- widget¶
Widget to add
TapTargetView
upon.widget
is anObjectProperty
and defaults to None.
- outer_radius¶
Radius for outer circle.
outer_radius
is anNumericProperty
and defaults to dp(200).
- outer_circle_color¶
Color for the outer circle in
rgb
format.self.tap_target_view = MDTapTargetView( ... outer_circle_color=(1, 0, 0) )
outer_circle_color
is anListProperty
and defaults totheme_cls.primary_color
.
- outer_circle_alpha¶
Alpha value for outer circle.
outer_circle_alpha
is anNumericProperty
and defaults to 0.96.
- target_radius¶
Radius for target circle.
target_radius
is anNumericProperty
and defaults to dp(45).
- target_circle_color¶
Color for target circle in
rgb
format.self.tap_target_view = MDTapTargetView( ... target_circle_color=(1, 0, 0) )
target_circle_color
is anListProperty
and defaults to [1, 1, 1].
- title_text¶
Title to be shown on the view.
title_text
is anStringProperty
and defaults to ‘’.
- title_text_size¶
Text size for title.
title_text_size
is anNumericProperty
and defaults to dp(25).
- title_text_color¶
Text color for title.
title_text_color
is anListProperty
and defaults to [1, 1, 1, 1].
- title_text_bold¶
Whether title should be bold.
title_text_bold
is anBooleanProperty
and defaults to True.
- description_text¶
Description to be shown below the title (keep it short).
description_text
is anStringProperty
and defaults to ‘’.
- description_text_size¶
Text size for description text.
description_text_size
is anNumericProperty
and defaults to dp(20).
- description_text_color¶
Text size for description text.
description_text_color
is anListProperty
and defaults to [0.9, 0.9, 0.9, 1].
- description_text_bold¶
Whether description should be bold.
description_text_bold
is anBooleanProperty
and defaults to False.
- draw_shadow¶
Whether to show shadow.
draw_shadow
is anBooleanProperty
and defaults to False.
- cancelable¶
Whether clicking outside the outer circle dismisses the view.
cancelable
is anBooleanProperty
and defaults to False.
- widget_position¶
Sets the position of the widget on the
outer_circle
. Available options are ‘left’, ‘right’, ‘top’, ‘bottom’, ‘left_top’, ‘right_top’, ‘left_bottom’, ‘right_bottom’, ‘center’.widget_position
is anOptionProperty
and defaults to ‘left’.
- title_position¶
Sets the position of :attr`~title_text` on the outer circle. Only works if :attr`~widget_position` is set to ‘center’. In all other cases, it calculates the :attr`~title_position` itself. Must be set to other than ‘auto’ when :attr`~widget_position` is set to ‘center’.
Available options are ‘auto’, ‘left’, ‘right’, ‘top’, ‘bottom’, ‘left_top’, ‘right_top’, ‘left_bottom’, ‘right_bottom’, ‘center’.
title_position
is anOptionProperty
and defaults to ‘auto’.
- stop_on_outer_touch¶
Whether clicking on outer circle stops the animation.
stop_on_outer_touch
is anBooleanProperty
and defaults to False.
- stop_on_target_touch¶
Whether clicking on target circle should stop the animation.
stop_on_target_touch
is anBooleanProperty
and defaults to True.
- state¶
State of
MDTapTargetView
.state
is anOptionProperty
and defaults to ‘close’.
- stop(self, *args)¶
Starts widget close animation.
- start(self, *args)¶
Starts widget opening animation.
- on_open(self, *args)¶
Called at the time of the start of the widget opening animation.
- on_close(self, *args)¶
Called at the time of the start of the widget closed animation.
- on_draw_shadow(self, instance, value)¶
- on_description_text(self, instance, value)¶
- on_description_text_size(self, instance, value)¶
- on_description_text_bold(self, instance, value)¶
- on_title_text(self, instance, value)¶
- on_title_text_size(self, instance, value)¶
- on_title_text_bold(self, instance, value)¶
- on_outer_radius(self, instance, value)¶
- on_target_radius(self, instance, value)¶
- on_target_touch(self)¶
- on_outer_touch(self)¶
- on_outside_click(self)¶