List Panel Widget

Table of Contents

• List Panel Widgets
• Configuration Options and Instantiation
  • List Creation
• Manipulating List Items
  • List Panel APIs
  • Smart Model APIs
• Navigation
  • Navigate From a List to Another List
  • Panel Navigation View APIs

List Panel Widgets

The ListPanelWidget is one of the panel cluster widgets. It is designed to provide an easy way to present a list of simple or complex widgets at the same time. The System Status List is a supplied widget which shows this behavior. Each widget in the System Status List shows a specific status such as flight mode or SD card capacity. Some of the list widgets allow changing settings directly or activating functionality by pressing a button.

List panels support a titlebar along the top edge which can display a back button, title and close button. These can be configured using the configuration object when the list panel is created.

There are two basic types of ListPanel widgets: the standard version which allows the developer to manipulate the list directly and the SmartList which uses a SmartListModel to define the contents of the list to be displayed. The SmartList allows the developer to encapsulate all the business logic for a list into a single class which can be tuned as needed. For instance, the SystemStatusList uses a SmartList to decide which items will be shown in the SystemStatusList based on the connected aircraft.

On Android, the ListPanelWidget uses a ListView to present the widgets. Each widget added to the list is placed into an individual row for display. Note that this list is not meant to be used as an infinite list, but rather for a limited number of widgets. For infinite lists, prefer to use a RecyclerView.

List panels support hierarchical displays using interfaces defined below. Most commonly, a list item widget can provide another ListPanelWidget for display which will be visually pushed into the list. Making a selection from that list or hitting the back button, will return to the parent list. This allows building complex hierarchical settings interfaces for root list items.

Several base classes have been implemented to make writing ListItemWidgets faster and more consistent. Wikis for each type of ListItemWidget can be found under List Item Base Widgets.

Configuration Options and Instantiation

When creating a ListPanelWidget, the configuration object specifies the widget type (PanelWidgetType). Titlebar configuration is also required to ensure the proper display of the back button along with the title and close button.

List Creation

Widgets can be created in two ways.

XML

    <dji.ux.beta.core.panelwidget.systemstatus.SystemStatusListPanelWidget
        android:id="@+id/widget_panel_system_status_list"
        android:layout_width="0dp"
        android:layout_height="0dp"
        app:layout_constraintBottom_toBottomOf="parent"
        app:layout_constraintStart_toStartOf="parent"
        app:layout_constraintTop_toTopOf="parent"
        app:layout_constraintWidth_percent="0.5" />

Programatically

val systemStatusList = SystemStatusListPanelWidget(context)

Manipulating List Items

Lists are manipulated by adding and removing widgets. You can retrieve the widget count, append, or insert widgets at a specific index, or remove widgets dynamically.

List Panel APIs

The ListPanelWidget supports APIs from its parent PanelWidget. The following APIs are unique to the ListPanelWidget:

Counting Widgets

fun size(): Int - Total count of Views in the current list of widgets.

Adding Widgets

Widgets can only be added when the ListPanelWidget is not using a SmartModel.

List of APIs

• fun addWidgets(items: Array<View>) - Add a new List of Views.
• fun addWidget(index: Int, view: View) - Add a View at index to the current list of widgets.

Removing Widgets

Widgets can only be removed when the ListPanelWidget is not using a SmartModel.

List of APIs

• fun removeWidget(index: Int): View? - Remove a View at index from the current list of widgets.
• fun removeAllWidgets() - Remove all Views.

Fetch Widgets

fun getWidget(index: Int): View? - Get the View at index from the current list of widgets.

Smart List Model APIs

A ListPanelWidget has the option to provide a SmartListModel to manipulate the contents of the list. The SmartListModel can be overridden by setting var smartListModel: SmartListModel? on the ListPanelWidget.

When instantiating a SmartListModel, a set of IDs can be passed to prevent certain widgets from being created and presented in the list.

List of APIs

• fun setUp() - Set up the SmartListModel by initializing all the required resources.
• fun cleanUp() - Clean up the SmartListModel by destroying all the resources used.
• fun setListPanelWidgetHolder(listPanelWidgetBaseModel: ListPanelWidgetBaseModel) - Set a reference to a ListPanelWidgetBaseModel. Must be set to communicate changes to the ListPanelWidget.
• fun getActiveWidget(@IntRange(from = 0) index: Int): View? - Get View at index from the active widget list.
• fun getActiveWidget(widgetID: WidgetID): View? - Get View with widgetID from the active widget list.
• fun getWidgetID(@IntRange(from = 0) index: Int): WidgetID? - Get the WidgetID at index from the current order list. This is the order of all active and inactive widgets.
• fun getWidget(widgetID: WidgetID): View? - Get the View for the WidgetID. Only available if the widget has become active at least once.
• fun getWidgetIndex(widgetID: WidgetID): Int - Get the index for the WidgetID from the current order list. This is the order of all active and inactive widgets.
• fun setIndex(@IntRange(from = 0) index: Int, widgetID: WidgetID) - Change the index for a WidgetID, effectively changing its order in the list of active and inactive widgets.
• fun setIndex(@IntRange(from = 0) fromIndex: Int, @IntRange(from = 0) toIndex: Int) - Change the order of a WidgetID from one index to another, effectively changing its order in the list of active and inactive widgets.

Navigation

The ListPanelWidget supports navigation when it is embedded inside a PanelNavigationView. To bind a ListPanelWidget, pass a reference of it to the PanelNavigationView or call fun push(view:View).

Navigate from a list to another list

Navigation is handled at the Widget level. The Widget must implement the Navigable interface. The widget can then push a new View to the top of the PanelNavigationView.

Panel Navigation View APIs

List of APIs

• var isAnimationEnabled: Boolean - Enables or disables all transition animations.
• var addViewToTopAnimation: Animation - Transition animation for when a view is added on top. Set to null to remove animation.
• var removeViewFromTopAnimation: Animation - Transition animation for when a view is removed from the top. Set to null to remove animation.
• var showViewAnimation: Animation - Transition animation for when a view is reappearing. Set to null to remove animation.
• var hideViewAnimation: Animation - Transition animation for when a view is being replaced. Set to null to remove animation.
• fun push(view: View) - Push a view to the top.
• fun pop() - Pop the current view. Will not pop if the current view is the root.
• fun peek(): View? - Get the top level view.
• fun viewAdded(): Flowable<View> - Flowable to observe when a view is added to the top.
• fun setAddViewToTopAnimation(@AnimRes animRes: Int) - Set the animRes for when a view is added on top.
• fun setRemoveViewFromTopAnimation(@AnimRes animRes: Int) - Set the animRes for when a view is removed from the top.
• fun setShowViewAnimation(@AnimRes animRes: Int) - Set the animRes for when a view is reappearing.
• fun setHideViewAnimation(@AnimRes animRes: Int) - Set the animRes for when a view is being replaced.