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)¶ Bases:
kivymd.theming.ThemableBehavior
,kivy.event.EventDispatcher
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)¶