Version

Quick search

Table Of Contents

Action Bar

New in version 1.8.0.

_images/actionbar.png

The ActionBar widget is like Android’s ActionBar, where items are stacked horizontally. When the area becomes to small, widgets are moved into the ActionOverflow area.

An ActionBar contains an ActionView with various ContextualActionViews. An ActionView will contain an ActionPrevious having title, app_icon and previous_icon properties. An ActionView will contain subclasses of ActionItems. Some predefined ones include an ActionButton, an ActionToggleButton, an ActionCheck, an ActionSeparator and an ActionGroup.

An ActionGroup is used to display ActionItems in a group. An ActionView will always display an ActionGroup after other ActionItems. An ActionView contains an ActionOverflow, but this is only made visible when required i.e. the available area is too small to fit all the widgets. A ContextualActionView is a subclass of an:class:ActionView.

Changed in version 1.10.1: ActionGroup core rewritten from Spinner to pure DropDown

exception kivy.uix.actionbar.ActionBarException[source]

Bases: Exception

ActionBarException class

class kivy.uix.actionbar.ActionItem[source]

Bases: builtins.object

ActionItem class, an abstract class for all ActionBar widgets. To create a custom widget for an ActionBar, inherit from this class. See module documentation for more information.

background_down

Background image of the ActionItem used for the default graphical representation when an ActionItem is pressed.

background_down is a StringProperty and defaults to ‘atlas://data/images/defaulttheme/action_item_down’.

background_normal

Background image of the ActionItem used for the default graphical representation when the ActionItem is not pressed.

background_normal is a StringProperty and defaults to ‘atlas://data/images/defaulttheme/action_item’.

important

Determines if an ActionItem is important or not. If an item is important and space is limited, this item will be displayed in preference to others.

important is a BooleanProperty and defaults to False.

inside_group

(internal) Determines if an ActionItem is displayed inside an ActionGroup or not.

inside_group is a BooleanProperty and defaults to False.

minimum_width

Minimum Width required by an ActionItem.

minimum_width is a NumericProperty and defaults to ’90sp’.

mipmap

Defines whether the image/icon dispayed on top of the button uses a mipmap or not.

mipmap is a BooleanProperty and defaults to True.

pack_width

(read-only) The actual width to use when packing the items. Equal to the greater of minimum_width and width.

pack_width is an AliasProperty.

class kivy.uix.actionbar.ActionButton(**kwargs)[source]

Bases: kivy.uix.button.Button, kivy.uix.actionbar.ActionItem

ActionButton class, see module documentation for more information.

The text color, width and size_hint_x are set manually via the Kv language file. It covers a lot of cases: with/without an icon, with/without a group and takes care of the padding between elements.

You don’t have much control over these properties, so if you want to customize its appearance, we suggest you create you own button representation. You can do this by creating a class that subclasses an existing widget and an ActionItem:

class MyOwnActionButton(Button, ActionItem):
    pass

You can then create your own style using the Kv language.

icon

Source image to use when the Button is part of the ActionBar. If the Button is in a group, the text will be preferred.

icon is a StringProperty and defaults to None.

class kivy.uix.actionbar.ActionToggleButton(**kwargs)[source]

Bases: kivy.uix.actionbar.ActionItem, kivy.uix.togglebutton.ToggleButton

ActionToggleButton class, see module documentation for more information.

icon

Source image to use when the Button is part of the ActionBar. If the Button is in a group, the text will be preferred.

class kivy.uix.actionbar.ActionCheck(**kwargs)[source]

Bases: kivy.uix.actionbar.ActionItem, kivy.uix.checkbox.CheckBox

ActionCheck class, see module documentation for more information.

class kivy.uix.actionbar.ActionSeparator(**kwargs)[source]

Bases: kivy.uix.actionbar.ActionItem, kivy.uix.widget.Widget

ActionSeparator class, see module documentation for more information.

background_image

Background image for the separators default graphical representation.

background_image is a StringProperty and defaults to ‘atlas://data/images/defaulttheme/separator’.

class kivy.uix.actionbar.ActionDropDown(**kwargs)[source]

Bases: kivy.uix.dropdown.DropDown

ActionDropDown class, see module documentation for more information.

class kivy.uix.actionbar.ActionGroup(**kwargs)[source]

Bases: kivy.uix.actionbar.ActionItem, kivy.uix.button.Button

ActionGroup class, see module documentation for more information.

add_widget(item)[source]

Add a new widget as a child of this widget.

Parameters:
widget: Widget

Widget to add to our list of children.

index: int, defaults to 0

Index to insert the widget in the list. Notice that the default of 0 means the widget is inserted at the beginning of the list and will thus be drawn on top of other sibling widgets. For a full discussion of the index and widget hierarchy, please see the Widgets Programming Guide.

New in version 1.0.5.

canvas: str, defaults to None

Canvas to add widget’s canvas to. Can be ‘before’, ‘after’ or None for the default canvas.

New in version 1.9.0.

>>> from kivy.uix.button import Button
>>> from kivy.uix.slider import Slider
>>> root = Widget()
>>> root.add_widget(Button())
>>> slider = Slider()
>>> root.add_widget(slider)
clear_widgets()[source]

Remove all (or the specified) children of this widget. If the ‘children’ argument is specified, it should be a list (or filtered list) of children of the current widget.

Changed in version 1.8.0: The children argument can be used to specify the children you want to remove.

dropdown_width

If non zero, provides the width for the associated DropDown. This is useful when some items in the ActionGroup’s DropDown are wider than usual and you don’t want to make the ActionGroup widget itself wider.

dropdown_width is a NumericProperty and defaults to 0.

New in version 1.10.0.

is_open

By default, the DropDown is not open. Set to True to open it.

is_open is a BooleanProperty and defaults to False.

mode

Sets the current mode of an ActionGroup. If mode is ‘normal’, the ActionGroups children will be displayed normally if there is enough space, otherwise they will be displayed in a spinner. If mode is ‘spinner’, then the children will always be displayed in a spinner.

mode is an OptionProperty and defaults to ‘normal’.

separator_image

Background Image for an ActionSeparator in an ActionView.

separator_image is a StringProperty and defaults to ‘atlas://data/images/defaulttheme/separator’.

separator_width

Width of the ActionSeparator in an ActionView.

separator_width is a NumericProperty and defaults to 0.

use_separator

Specifies whether to use a separator after/before this group or not.

use_separator is a BooleanProperty and defaults to False.

class kivy.uix.actionbar.ActionOverflow(**kwargs)[source]

Bases: kivy.uix.actionbar.ActionGroup

ActionOverflow class, see module documentation for more information.

add_widget(action_item, index=0)[source]

Add a new widget as a child of this widget.

Parameters:
widget: Widget

Widget to add to our list of children.

index: int, defaults to 0

Index to insert the widget in the list. Notice that the default of 0 means the widget is inserted at the beginning of the list and will thus be drawn on top of other sibling widgets. For a full discussion of the index and widget hierarchy, please see the Widgets Programming Guide.

New in version 1.0.5.

canvas: str, defaults to None

Canvas to add widget’s canvas to. Can be ‘before’, ‘after’ or None for the default canvas.

New in version 1.9.0.

>>> from kivy.uix.button import Button
>>> from kivy.uix.slider import Slider
>>> root = Widget()
>>> root.add_widget(Button())
>>> slider = Slider()
>>> root.add_widget(slider)
overflow_image

Image to be used as an Overflow Image.

overflow_image is a StringProperty and defaults to ‘atlas://data/images/defaulttheme/overflow’.

class kivy.uix.actionbar.ActionView(**kwargs)[source]

Bases: kivy.uix.boxlayout.BoxLayout

ActionView class, see module documentation for more information.

action_previous

Previous button for an ActionView.

action_previous is an ObjectProperty and defaults to None.

add_widget(action_item, index=0)[source]

Add a new widget as a child of this widget.

Parameters:
widget: Widget

Widget to add to our list of children.

index: int, defaults to 0

Index to insert the widget in the list. Notice that the default of 0 means the widget is inserted at the beginning of the list and will thus be drawn on top of other sibling widgets. For a full discussion of the index and widget hierarchy, please see the Widgets Programming Guide.

New in version 1.0.5.

canvas: str, defaults to None

Canvas to add widget’s canvas to. Can be ‘before’, ‘after’ or None for the default canvas.

New in version 1.9.0.

>>> from kivy.uix.button import Button
>>> from kivy.uix.slider import Slider
>>> root = Widget()
>>> root.add_widget(Button())
>>> slider = Slider()
>>> root.add_widget(slider)
background_color

Background color in the format (r, g, b, a).

background_color is a ListProperty and defaults to [1, 1, 1, 1].

background_image

Background image of an ActionViews default graphical representation.

background_image is a StringProperty and defaults to ‘atlas://data/images/defaulttheme/action_view’.

overflow_group

Widget to be used for the overflow.

overflow_group is an ObjectProperty and defaults to an instance of ActionOverflow.

remove_widget(widget)[source]

Remove a widget from the children of this widget.

Parameters:
widget: Widget

Widget to remove from our children list.

>>> from kivy.uix.button import Button
>>> root = Widget()
>>> button = Button()
>>> root.add_widget(button)
>>> root.remove_widget(button)
use_separator

Specify whether to use a separator before every ActionGroup or not.

use_separator is a BooleanProperty and defaults to False.

class kivy.uix.actionbar.ContextualActionView(**kwargs)[source]

Bases: kivy.uix.actionbar.ActionView

ContextualActionView class, see the module documentation for more information.

class kivy.uix.actionbar.ActionPrevious(**kwargs)[source]

Bases: kivy.uix.boxlayout.BoxLayout, kivy.uix.actionbar.ActionItem

ActionPrevious class, see module documentation for more information.

app_icon

Application icon for the ActionView.

app_icon is a StringProperty and defaults to the window icon if set, otherwise ‘data/logo/kivy-icon-32.png’.

app_icon_height

Height of app_icon image.

app_icon_height is a NumericProperty and defaults to 0.

app_icon_width

Width of app_icon image.

app_icon_width is a NumericProperty and defaults to 0.

color

Text color, in the format (r, g, b, a)

color is a ListProperty and defaults to [1, 1, 1, 1].

markup

If True, the text will be rendered using the MarkupLabel: you can change the style of the text using tags. Check the Text Markup documentation for more information.

markup is a BooleanProperty and defaults to False.

previous_image

Image for the ‘previous’ ActionButtons default graphical representation.

previous_image is a StringProperty and defaults to ‘atlas://data/images/defaulttheme/previous_normal’.

previous_image_height

Height of previous_image image.

app_icon_width is a NumericProperty and defaults to 0.

previous_image_width

Width of previous_image image.

width is a NumericProperty and defaults to 0.

title

Title for ActionView.

title is a StringProperty and defaults to ‘’.

with_previous

Specifies whether the previous_icon will be shown or not. Note that it is up to the user to implement the desired behavior using the on_press or similar events.

with_previous is a BooleanProperty and defaults to True.

class kivy.uix.actionbar.ActionBar(**kwargs)[source]

Bases: kivy.uix.boxlayout.BoxLayout

ActionBar class, which acts as the main container for an ActionView instance. The ActionBar determines the overall styling aspects of the bar. ActionItems are not added to this class directly, but to the contained ActionView instance.

Events:
on_previous

Fired when action_previous of action_view is pressed.

Please see the module documentation for more information.

action_view

action_view of the ActionBar.

action_view is an ObjectProperty and defaults to None or the last ActionView instance added to the ActionBar.

add_widget(view)[source]

Add a new widget as a child of this widget.

Parameters:
widget: Widget

Widget to add to our list of children.

index: int, defaults to 0

Index to insert the widget in the list. Notice that the default of 0 means the widget is inserted at the beginning of the list and will thus be drawn on top of other sibling widgets. For a full discussion of the index and widget hierarchy, please see the Widgets Programming Guide.

New in version 1.0.5.

canvas: str, defaults to None

Canvas to add widget’s canvas to. Can be ‘before’, ‘after’ or None for the default canvas.

New in version 1.9.0.

>>> from kivy.uix.button import Button
>>> from kivy.uix.slider import Slider
>>> root = Widget()
>>> root.add_widget(Button())
>>> slider = Slider()
>>> root.add_widget(slider)
background_color

Background color, in the format (r, g, b, a).

background_color is a ListProperty and defaults to [1, 1, 1, 1].

background_image

Background image of the ActionBars default graphical representation.

background_image is a StringProperty and defaults to ‘atlas://data/images/defaulttheme/action_bar’.

border

The border to be applied to the background_image.

border is a ListProperty and defaults to [2, 2, 2, 2]