Deutsche version   Deutsche Version

Motivation

With smaller apps, the implemented functions can be triggered by a button. With larger apps, however, the available space quickly decreases and the layout becomes confusing. A side bar can help here. There are a number of implementations, but I haven't found a sufficiently extensive one and developed one myself. Almost all properties are adjustable. If something is missing, write to me: E-Mail to Ulli.


Version history

Version Anpassungen
1.0 (2021-01-28) Initial version

Download

Usage

Pixel vs. DIP

Detect Swiping

SideBar Structure

SideBar Items

Openening and Closing

Reference

Properties

Functions

Events

Example

SideBarTest

Tools

Download

The UrsAI2SideBar ZIP archive for download. The archive contains the source code, the compiled binary for uploading to the App Inventor and a sample application.

Usage

Pixel vs. DIP

App Inventor 2 uses the unit of pixels to define the width and height of elements. However, this does not mean a (hardware) pixel on the display, but a DIP (Device Independent Pixel). DIP-Width and DIP-Height are adjusted to the resolution and the dimensions of the display. A DIP therefore has approximately the same dimension on all devices. To avoid confusion, the term DIP is used throughout and unless otherwise specified, DIP is meant.

Detect Swiping

During the creation of the component (constructor), the extension places an additional, narrow, transparent view (SwipeDetector class) over the left edge of the display. Swiping from the left edge of the display to the right to open the SideBar is detected via this strip. The width of the strip can be set using the SwipeDetectorWidth property.

SideBar Structure

After opening the SideBar, the entire display is covered by the SideBarFrame (yellow). SideBarFrame is divided into two areas. On the left a container (listViewContainer, green) for the visible elements of the SideBar and on the right a semi-transparent field (shadowField, violet) that covers the rest of the display.

The width of the visible SideBar (= width of listViewContainer) can be specified in percent of the display width via the property SidebarWidthPercentage. The property BackgroundColor defines the background color.

listViewContainer is a container for imageViewContainer, which is used to align the cover picture, and an Android ListView, which contains the actual SideBar items.

The title image is set via the Image property. If None is selected, no picture will be displayed. FitImageSize is used to fit the width of the image to the width of the SideBar. The aspect ratio is retained. Alternatively, the image can be aligned in relation to the SideBar using the ImageAlignment property.

SideBar Items

A ListView element consists of up to three components: an optional symbol (Icon), a text field and optionally a CheckBox or Switch.

The SideBar items can be defined using the ItemsFromString property using a comma-separated list. Alternatively, the SideBar can be filled from a file (designer property ItemsFromFile or function LoadItemsFromFile). As a third option, the SideBar can be defined using a list (SetSideBarItems function).

The definition for a SideBar item consists of up to four elements, each separated by a double colon ("::"):

<hypertext>[::[<icon name>][::[<icon color>][::<T|F>]]]

When optional settings are omitted, the separator symbol ("::") must still be specified. Examples of valid definitions:

Definition of the SideBar items via list::

Definition of the SideBar items via a file:

Info...::info::blue
Goto <b>Screen2</b>::mobile_screen_share
E-Mail::email::#ff00ff00::f
Backup <b><font color="red">urgent!</font></b>::backup
Share::share::red::true
Exit::exit_to_app::green

Definition of the SideBar items via the designer property:

Individual SideBar items can be changed later without having to reload a completely new definition. This is done using the SetImtemX functions., e.g. SetItemChecked. The HasItemCheckBox and GetItemChecked functions provide information on whether a SideBar item has a CheckBox / Switch and what its checked state is.

The ItemSelected or Item#Selected event is triggered when a SideBar item without a CheckBox / Switch is tapped. Item#Selected is available five times.

For items with a CheckBox / Switch, the checked state changes when you tap on it. The ItemCheckedChanged event is triggered (ItemSelected is not triggered).

Opening and Closing

The SideBar can be opened in two ways, either by program using the Show function or the user swipes from the left edge of the display o the right. Opening by swiping can be prevented using the Enabled property

Closing is done by calling the Hide function. The user closes the SideBar by tapping the shadow field (see SideBar structure) or swiping from right to left on the SideBar.

The BeforeOpening and AfterClosing events accompany these processes.

The IsOpened property can be used to query whether the SideBar is currently opened.


Reference

Note: The properties and functions do not affect an already opened SideBar!

Properties

BackgroundColor
Defines the background color of the SideBar. The default is white
Enabled
Specifies whether the SideBar is active, i.e. whether it can be opened by swiping.
FitImageSize
Specifies whether the width of the cover picture should be adjusted to the width of the SideBar. The aspect ratio is retained.
FontSize
Specifies the font size for the SideBar items. The default is 16.0.
IconColor
Defines the standard color for the symbols in the SideBar items. The default is black.
If the entries are deactivated, the symbol is displayed with the color defined by TextColorInactive.
Image
The (asset) file name for the cover image.
ImageAlignment
Specifies the alignment of the cover picture in relation to the SideBar: left-justified, centered or right- justified. The default setting is left-justified (1).
IsOpened
Indicates whether the SideBar is opened, ie is displayed.
ItemsFromFile
The SideBar item definitions are read from the specified (asset) file. For each SideBar item a line of form <hypertext>[::[<icon name>][::[<icon color>][::<T|F>]]] must be specified (see SideBar Items).
ItemsFromString
Specifies the SideBar items using a comma-separated list. For each SideBar items, a list item of form <hypertext>[::[<icon name>][::[<icon color>][::<T|F>]]] must be specified (see SideBar Items). Multiple entries are separated by commas.
PaddingIcon
Specifies the distance between the left edge of the Sidebar and the icon. The default setting is 16 DIP.
PaddingText
Specifies the space between the icon and the text for the SideBar item. The default setting is 32 DIP.
SidebarWidthPercentage
Specifies the width of the SideBar as a percentage of the display width. Valid values ​​are 30%.. 90%. The default is 80%.
SwipeDetectorWidth
Specifies the width of the SwipeDetector strip. The specification is made in DIP. The default setting is 24 DIP (see Usage).
SwitchThumbColorActive
Specifies the Switch’s thumb color when switch is in the On state. The default is white.
SwitchThumbColorInactive
Specifies the Switch’s thumb color when switch is in the Off state. The default is light gray.
SwitchTrackColorActive
Specifies the Switch’s track color when in the On state. The dafault is green.
SwitchTrackColorInactive
Specifies the Switch’s track color when in the Off state. The default is dark gray.
TextColor
Defines the standard text color of the SideBar items. The default is black.
TextColorInactive
Specifies the text color for inactive SideBar items (text and icon). The default is gray.
UseSwitches
Specifies whether Switches should be displayed instead of CheckBoxes. The default is false.
Version
Gets the version of the extension.

Functions

GetItemChecked(ItemNo)
Get the check status of the specified SideBar item. ItemNo is the number of the entry. Counting starts with 1.
HasItemCheckBox(ItemNo)
Gets whether the specified SideBar item has a CheckBox / Switch. ItemNo is the number of the item. Counting starts with 1.
Hide()
Closes the SideBar.
LoadItemsFromFile(FileName)
Loads die SideBar from the specified file. For each SideBar item a line of form <hypertext>[::[<icon name>][::[<icon color>][::<T|F>]]] must be specified (see SideBar Items).
SetItemChecked(ItemNo, Checked)
Defines the checked state of the specified SideBar item. ItemNo is the number of the item. Counting starts with 1.
SetItemEnabled(ItemNo, Enabled)
Activates / deactivates the specified SideBar item. ItemNo is the number of the item. Counting starts with 1. Deactivated items are displayed with the color defined in TextColorInactive and do not react to being clicked.
SetItemIconColor(ItemNo, Color)
Defines the icon color for the specified SideBar item. ItemNo is the number of the item. Counting starts with 1.
SetItemIconName(ItemNo, Name)
Defines the symbol for the specified SideBar item. ItemNo is the number of the item. Counting starts with 1. Name  is the name of a character from the MaterialIcons-Font.
SetItemText(ItemNo, Text)
Defines the text for the specified SideBar item. ItemNo is the number of the item. Counting starts with 1.
SetSideBarItems(ListItems)
Defines the entries of the SideBar via a List. For each SideBar item, a list element of form <hypertext>[::[<icon name>][::[<icon color>][::<T|F>]]] mus be specified (see SideBar Items).
Show()
Opens the SideBar (displays it).

Events

AfterSelecting(ItemNo, Title)
The specified SideBar item was clicked. ItemNo is the number of the item. Counting starts with 1. Title is the text of the item.
BeforeOpening(ByCommand)
The event is triggered before the SideBar opens. ByCommand is true if the opening was triggered by the Show function. The value is false if the SideBar was opened by the user by swiping on the GUI.
AfterClosing(ByCommand)
The event is triggered after the SideBar is closed. ByCommand is true if closing was triggered by the Hide function. The value is false if the SideBar was closed by the user by swiping on the GUI.
ItemCheckedChanged(ItemNo, Title, Checked)
The check status of the SideBar entry has been changed. ItemNo is the number of the item. Counting starts with 1. Title is the text of the item. Checked is the checked state.
Item#Selected(Title)
The SideBar item # was clicked. Title is the text of the entry. This event occurs five times.

Example

SideBarTest

 

The example is quite simple. It shows different versions of the SideBar on two screens.

The first screen presents some possible SideBar configurations. Only the first two and the last items have are functional. After tapping an activated entry, the parameters of the AfterSelecting event are displayed in the yellow bar.
The second screen shows how settings can be managed using switches.

Tools

I have collected some tips for creating your own extensions: AI2 FAQ: Developing extensions. On the page you can find further informations too.