ListPanel Widget
- List Panel Widgets
- Configuration Options and Instantiation
- Manipulating List Items
- Support Protocols for List Panel Widgets and List Item Widgets
The ListPanel widget (DUXBetaListPanelWidget) 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 SystemStatusListWidget is a supplied widget which shows this behavior. Each widget in that list shows a single line item of status. 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 box. 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 displays list, and the SmartList, which uses a DUXBetaSmartListModel 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 SystemStatusListPanel uses a SmartList to decide which items will be shown in the DUXBetaSystemStatusList based on the connected aircraft.
On iOS, the DUXBetaListPanelWidget is built on top of the UITableView class. Each widget added to the list is placed into an individual cell for display.
List panels support hierarchical displays using protocols defined below. Most commonly, a list item widget can provide another set of widgets for display in a sublist 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 of complex hierarchical interfaces of settings for root list items.
Several base classes have been implemented to make writing list item widgets faster and more consistent. Those are documented at ListItem Base Widgets.
When creating a DUXBetaListPanelWidget, the configuration object specifies the widget type (DUXBetaPanelTypeList) and the kind of list (DUXBetaListType). Titlebar configuration is also required to ensure the proper display of the back button along with the title and close box.
| DUXBetaListType | Purpose |
|---|---|
| DUXBetaListNone | This is an unused value used to indicate a list which has not been properly configured |
| DUXBetaListSelectOne | A specialized list used to display a set of option values for selection. Only one item may be chosen |
| DUXBetaListSelectOneAndReturn | A specialized list like DUXBetaListSelectOne, however when an item is selected, the list immediately is popped and the list returns to the previous hierarchy level |
| DUXBetaListWidgets | The most common list type, it supports and array of widgets (or individually added widgets) which have been created before being added to the list for display |
| DUXBetaListWidgetName | This list type accepts an array of widget class names for use. Internally, each class name is used to create that widget with no further configuration |
// Standard List Panel Widget
let listConfigObject = DUXBetaPanelWidgetConfiguration(type: .list, listKind: .widgets)
configureTitlebar(visible: true, withCloseBox: true, title: “My List”)
let myListPanel = DUXBetaListPanel().configure(listConfigObject)
// SmartList variant
let mySmartModel = CustomSmartModel()
let mySmartListPanel = DUXBetaListPanel(smartModel: mySmartModel).configure(listConfigObject)// Standard List Panel Widget
DUXBetaPanelWidgetConfiguration *listConfigObject = [DUXBetaPanelWidgetConfiguration alloc] initWithType:DUXBetaPanelTypeList listKind:DUXBetaListTypeWidget]
.configureTileBarVisible:YES withCloseBox: YES title:@“My List”];
DUXBetaListPanel *myListPanel = [[[DUXBetaListPanel alloc] init] configure:listConfigObject];
// SmartList variant
CustomSmartModel *mySmartModel = [[CustomSmartModel alloc] init];
DUXBetaListPanel *mySmartListPanel = [[[DUXBetaListPanel alloc] initWithSmartModel:mySmartModel] configure:listConfigObject];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. There are also specialized methods for handling option strings in the specialized list types DUXBetaListSelectOne and DUXBetaSelectOneAndReturn.
func widgetCount() -> Int- (NSInteger)widgetCount;This method simply returns the number of widgets currently in the list panel.
func addWidgetArray(displayWidgets: [ DUXBetaBaseWidget ])
func insert(widget: DUXBetaBaseWidget, atIndex: Int)- (void)addWidgetArray:(NSArray<DUXBetaBaseWidget*>)displayWidgets;
- (void)insertWidget:(DUXBetaBaseWidget)widget atIndex:(NSInteger)index;The add methods are used to append a list of widgets to the end of the current widget list in the list panel. To add a single widget, pass the widget wrapped in an array.
Inserting widgets into the middle of a list is done one at a time. The list index is 0 based, and you pass the index you want the new widget to appear at, moving all the other widgets down in the list. Pass an index of 0 to insert into the top of the list panel.
func removeWidget(atIndex: Int)
func removeAllWidgets()- (void)removeWidgetAtIndex:(NSInteger)index;
- (void)removeAllWidgets()These methods are pretty self-explanatory. Remove one widget at an index, or remove all the widgets in the list.
The following methods are similar to the add and remove methods except they are specialized for strings being added/removed from the SelectOne variant lists. They allow the developer to build a list of options to pick from without needing to build and entire set of new widgets.
func addOptionStrings([String])
func insert(optionString: String, atIndex: Int)
func removeOptionString(atIndex: Int)
func removeAllOptionStrings()- (void)addOptionStrings:(NSArray*)stringArray;
- (void)insert:(NSString)optionString atIndex:(NSInteger)index;
- (void)removeOptionStringAtIndex:(NSInteger)index;
- (void)removeAllOptionStrings;The DUXBetaListPanelSupportProtocol is a set of optional methods which are adopted by widgets to be displayed in a DUXBetaListPanelWidget. These widget items are generally known as list item widgets.
The protocol methods can be broken into three categories: Sublist Definition, Sublist Content, and Sublist Action.
The first items define if an individual list item supports a sublist of items. These three protocol methods are:
- (BOOL)hasDetailList;
- (NSString*)detailsTitle;
- (DUXBetaListType)detailListType;If hasDetailList returns YES/true, the cell displaying the list item widget will add the DisclosureIndicator accessory to the cell. When the cell it tapped, the other protocol methods will be used to build the detail list.
The string returned by detailsTitle will be put into the titlebar for the details view.
The method detailListType returns the type of list which will be created for the detail list.
The content items define what will be shown in the sublist. There are separate methods to define SelectOne style lists, instantiated widget lists, or widget class name lists.
- (NSDictionary<NSString*, id>*)oneOfListOptions;
- (NSArray<NSString*> *)listOfSubwidgetNames;
- (NSArray<DUXBetaBaseWidget*> *)listOfSubwidgets;The method oneOfListOptions returns an NSDictionary defining the set of options for the sublist, as well as the current selected option if one exists.
| Key | Value |
|---|---|
| current | The current/default item to select in the array of options. If there is no current selection, do not add the key to the dictionary |
| list | An NSArray of NSString of the options to be displayed |
The method listOfSubwidgetNames returns an NSArray of the classnames to be used to create the new sublist.
Method listOfSubwidgets takes an NSArray of already created widgets for display in the new sublist.
When a SelectOne style list is tapped, an update block can be called for processing. Implementing the selectionUpdate method will cause the block returned by selectionUpdate to be executed when an item is tapped.
- (void (NSInteger))selectionUpdate;This method returns a block which takes the selection update as the only parameter and has no return value.