TapTargetView

See also

TapTargetView, GitHub

TapTargetView, Material archive

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:

• title_text_size

• title_text_color

• title_text_bold

• description_text_size

• description_text_color

• description_text_bold

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

on_open

Called at the time of the start of the widget opening animation.

on_close

Called at the time of the start of the widget closed animation.

widget

Widget to add TapTargetView upon.

widget is an ObjectProperty and defaults to None.

outer_radius

Radius for outer circle.

outer_radius is an NumericProperty 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 an ListProperty and defaults to theme_cls.primary_color.

outer_circle_alpha

Alpha value for outer circle.

outer_circle_alpha is an NumericProperty and defaults to 0.96.

target_radius

Radius for target circle.

target_radius is an NumericProperty 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 an ListProperty and defaults to [1, 1, 1].

title_text

Title to be shown on the view.

title_text is an StringProperty and defaults to ‘’.

title_text_size

Text size for title.

title_text_size is an NumericProperty and defaults to dp(25).

title_text_color

Text color for title.

title_text_color is an ListProperty and defaults to [1, 1, 1, 1].

title_text_bold

Whether title should be bold.

title_text_bold is an BooleanProperty and defaults to True.

description_text

Description to be shown below the title (keep it short).

description_text is an StringProperty and defaults to ‘’.

description_text_size

Text size for description text.

description_text_size is an NumericProperty and defaults to dp(20).

description_text_color

Text size for description text.

description_text_color is an ListProperty and defaults to [0.9, 0.9, 0.9, 1].

description_text_bold

Whether description should be bold.

description_text_bold is an BooleanProperty and defaults to False.

draw_shadow

Whether to show shadow.

draw_shadow is an BooleanProperty and defaults to False.

cancelable

Whether clicking outside the outer circle dismisses the view.

cancelable is an BooleanProperty 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 an OptionProperty 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 an OptionProperty and defaults to ‘auto’.

stop_on_outer_touch

Whether clicking on outer circle stops the animation.

stop_on_outer_touch is an BooleanProperty and defaults to False.

stop_on_target_touch

Whether clicking on target circle should stop the animation.

stop_on_target_touch is an BooleanProperty and defaults to True.

state

State of MDTapTargetView.

state is an OptionProperty 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)