Panel Widget

Panels Overview

The panel architecture is designed as a cluster of classes used to group a set of widgets in a specific way for presentation to the user. These panels can be used to create Bar Panels, Toolbar Panels, and List Panels.

A Bar Panel is for presenting a row or column of icons which are self contained, such as the status widgets in the top bar or side bar of an application.

The Toolbar Panel widget is a widget for displaying a single sub-widget at a time based on the selection of widgets shown as a strip of icons along the edge of the panel. Toolbars may be vertically or horizontally oriented. Release Date TBD.

List Panels are for displaying widgets which are primarily lists of items such as settings or status information. They are only oriented vertically.

Details about each of the individual types may be found on its own page.

Panel Configuration Overview

Panels have certain abstractions which apply to all panels in the panels cluster and are implemented in the PanelWidget base class. When combined with the configuration object, the resulting panel is ready to have widgets added and be installed in a view.

All panels are configured with a PanelWidgetType passed to the PanelWidgetConfiguration constructor. The configuration can additionally change whether a title bar should be shown or not.

The PanelWidgetConfiguration also has the following properties:

Property	Description
`var panelWidgetType: PanelWidgetType`	The type of panel widget
`var showTitleBar: Boolean`	Boolean to hide or show the whole title bar, false by default
`var hasCloseButton: Boolean`	Boolean to hide or show the close button of the title bar, false by default
`var panelTitle: String`	Default panel title text, empty string by default
`titleBarHeightDimensionResID: Int`	Dimension resource for the height of the title bar, 32dp by default

Panels are defined using a PanelWidgetType. The variant specifies positioning and orientation for the panel. Panel Types are:

Type	Description
BAR_VERTICAL	A vertical bar of widgets, useful for a status bar along one edge of a screen or inside another container. Vertical BarPanels have a top/bottom section
BAR_HORIZONTAL	A horizontal bar of widgets, useful for a status bar along one edge of a screen or inside another container. Horizontal BarPanels have a left/right section
LIST	A ListPanel for displaying a list of widgets, vertically oriented

Base Panel APIs

These are the methods common to all Panel widgets. Specialized panels have additional methods relating to their function. Those methods are discussed on the individual panel pages.

Adding Widgets to Panels

The following methods are used to add widgets to the panel containers. Specific panel types have additional methods related to their specialization. Note that generic S is the type of objects the panel holds.

List of APIs

abstract fun getWidget(@IntRange(from = 0) index: Int): S? - Get the widget of type S at index from to the current list of widgets.
abstract fun addWidgets(items: Array<S>) - Add a new List of widgets of type S.
abstract fun size(): Int - Total size of widgets of type S in the current list of widgets.
abstract fun addWidget(@IntRange(from = 0) index: Int, item: S) - Add a widget of type S at index to the current list of widgets.
abstract fun removeWidget(@IntRange(from = 0) index: Int): S? - Add a widget of type S at index to the current list of widgets.
abstract fun removeAllWidgets() - Remove all widgets from the current list.

Button Events

The following methods provide a way to observe when back or close buttons are pressed.

List of APIs

fun backButtonPressed(): Flowable<Boolean> - Flowable to observe when the back button is pressed.
fun closeButtonPressed(): Flowable<Boolean> - Flowable to observe when the close button is pressed.

Title Bar Customization

These are the default colors for the title bar:

Parameter	Default Color
background	clear
title	white
selection	dark gray
close button	x icon white
back button	left arrow white

The following methods and variables are used to customize all base attributes for the title bar of any panel.

List of APIs

var titleBarBackgroundColor: Int = 0 - Background color for the title bar.
fun setTitleBarBackgroundColorRes(@ColorRes colorRes: Int) - Set the resource ID for the title background color.
var backButtonIcon: Drawable? - The drawable for the back button icon.
var backButtonIconColor: Int? = null - The color for the back button icon.
var backButtonIconColors: ColorStateList? = null - The color state list for the back button icon.
var backButtonIconBackground: Drawable? = null - The drawable for the back button icon's background.
fun setBackButtonIcon(@DrawableRes resourceId: Int) - Set the resource ID for the back button icon.
fun setBackButtonIconBackground(@DrawableRes resourceId: Int) - Set the resource ID for the back button icon's background.
fun setBackButtonIconColorRes(@ColorRes colorRes: Int) - Set the resource ID for the back button icon's color.
var closeButtonIcon: Drawable? = null - The drawable for the close button icon.
var closeButtonIconBackground: Drawable? = null - The drawable for the close button icon's background.
var closeButtonIconColor: Int? = null - The color for the close button icon.
var closeButtonIconColors: ColorStateList? = null - The color state list for the close button icon.
fun setCloseButtonIcon(@DrawableRes resourceId: Int) - Set the resource ID for the close button icon.
fun setCloseButtonIconBackground(@DrawableRes resourceId: Int) - Set the resource ID for the back button icon's background.
fun setCloseButtonVisible(visible: Boolean) - Change the visibility of the title bar's close button.
var titleText: CharSequence? - Text for the title.
var titleTextSize: Float? - Text size for the title.
var titleTextColor: Int? = null - The color for the title.
fun setTitleTextAppearance(@StyleRes textAppearanceResId: Int) - Set text appearance of the title text view.