TextUI.ItemField

The ItemField is used to keep track of the current status of a potentially large number of items and visually indicate that status. Further, it provides the ability to move the cursor around in the field of items to "select" a particular item, as well as marking one or more items for performing an operation on.

This widget is useful for handling data sets that are too large to readily display with a List widget or similar functionality. Each item is represented by a single character on the screen, and these characters are displayed in the specified groups. Each item can have an associated state, which is reflected in both the character used for that item and the associated attributes:

    State           Character    Attribute
    Free (unmarked)    .         itemFreeAttr
    Marked             *         itemMarkedAttr
    Good               +         itemGoodAttr
    Bad                !         itemBadAttr
    Pending            ~         itemPendingAttr

See below for the definitions of these and other attributes that can be controlled by the user.

The widget provides a default event handler that handles the following:

• Arrow keys: move in the specified direction
• Mouse-click: move cursor to clicked item
• Space: select/deselect the item under the cursor (state->Marked or Free)
• Shift-RightArrow or Shift-LeftArrow: extend selection
• or: move 15 items backward or forward
• L: toggle Marked/Free for the current line
• G: toggle Marked/Free for the current group
• Mouse-click on a group: toggle Marked/Free for the current group
• A: toggle Marked/Free for all items
• +: change all Good items to Marked
• !: change all Bad items to Marked
• ~: change all Pending items to Marked
• s: change all Good items to Marked, everything else to Free
• f: change all Bad items to Marked, everything else to Free

Use cabal configure -fexamples to build a couple of example programs that use the ItemField and demonstrate its capabilities.

This module provides the top-level imports and the interaction with the brick UI framework.

Documentation

type GroupName = Text

type NumItems = Int

data Items

Constructors

ItemGroup GroupName Items

Items NumItems

Instances

Show Items

Methods

showsPrec :: Int -> Items -> ShowS

show :: Items -> String

showList :: [Items] -> ShowS

data ItemState

Constructors

Free

Marked

Good

Bad

Pending

Instances

Eq ItemState

Methods

(==) :: ItemState -> ItemState -> Bool

(/=) :: ItemState -> ItemState -> Bool

Show ItemState

Methods

showsPrec :: Int -> ItemState -> ShowS

show :: ItemState -> String

showList :: [ItemState] -> ShowS

type ItemIdent = Maybe (Int -> ItemState -> Text)

numItems :: Items -> NumItems

cntItems :: [Items] -> NumItems

Returns the count of the number of items

data ItemField

The ItemField is the central management of the set of items and their current states. There is simply a number of collections of items, expressing only the number of items in the collection., although there may be a group name associated with each collection.

Each item has a corresponding state, which is maintained in parallel and an item's state can be modified.

Constructors

ItemFld

Fields

• curSel :: Int

  Currently "selected" item (usually where the cursor is)

• items :: [Items]

  Actual item counts, possibly with a group name

• itemst8 :: [ItemState]

  Current state of each item (length == cntItems)

• elemIdent :: ItemIdent

  Function returning an item description given the item number

Instances

Show ItemField

Methods

showsPrec :: Int -> ItemField -> ShowS

show :: ItemField -> String

showList :: [ItemField] -> ShowS

newItemField :: [Items] -> ItemIdent -> ItemField

Standard factory to create an ItemField from a specification of Items and their potential identification function.

Types

data ItemFieldWidget n

This is the main widget for managing an ItemFieldWidget in a brick UI.

Constructors

ItemFieldWidget

Fields

• itemFieldName :: n
• itemField :: ItemField

Instances

Show (ItemFieldWidget n)

Methods

showsPrec :: Int -> ItemFieldWidget n -> ShowS

show :: ItemFieldWidget n -> String

showList :: [ItemFieldWidget n] -> ShowS

Named (ItemFieldWidget n) n

Methods

getName :: ItemFieldWidget n -> n

Rendering

itemFieldWidget :: (Show n, Ord n) => ItemFieldWidget n -> Widget n

This is the primary drawing description for the ItemField. This draws the widget in a viewport with the same name as the widget, using the Fixed horizontal and vertical growth policies.

Event handling

handleItemFieldEvent :: Ord n => Event -> ItemFieldWidget n -> EventM n (ItemFieldWidget n)

This is a handler that can be called from a higher level brick Event handler to allow the item field to handle any keys or other events that have not been handled by that higher level handler. This handler provides handling for:

• movement via arrow keys and the < and > keys
• toggling marking items: space = current item L = current line G = current group A = all items
• extending marking by holding shift while using left or right arrow keys
• marking all items with a particular status by using the corrsponding key: +, !, or ~

withItemFieldWidth :: Ord n => ItemFieldWidget n -> (Int -> EventM n (ItemFieldWidget n)) -> EventM n (ItemFieldWidget n)

Useful function for writing custom event handlers for the ItemFieldWidget. This wrapper can provide the width of the rendered ItemFieldWidget to the custom event handler.

Current item retrieval and manipulation

setItemState :: ItemState -> ItemFieldWidget n -> Int -> EventM n (ItemFieldWidget n)

Modifies the state of the specified item in the widget to the new value

getSelectedItem :: ItemFieldWidget n -> Int

Returns the index of the currently selected item in the Widget's field

Retrieving and updating marked items

getMarkedItems :: ItemFieldWidget n -> [Int]

Returns the list of the currently marked items in the Widget's field

setMarkedItemsState :: ItemState -> ItemFieldWidget n -> EventM n (ItemFieldWidget n)

Modifies the state of all currently marked items in the widget.

itemAttr :: AttrName

The itemAttr is the base attribute for the entire Widget

itemFieldAttr :: AttrName

The itemFieldAttr is the attribute for the items portion of the Widget. It does not apply to the headers or the current selection status.

itemFreeAttr :: AttrName

The itemFreeAttr applies to showing an item state that is Free, which is usually the default state for an unselected, un-evaluated item.

itemMarkedAttr :: AttrName

The itemMarkedAttr applies to showing an item that is Marked for future action.

itemGoodAttr :: AttrName

The itemGoodAttr indicates an item that is in the Good state.

itemBadAttr :: AttrName

The itemBadAttr indicates an item that is in the Bad state.

itemPendingAttr :: AttrName

The itemPendingAttr indicates an item that is in the Pending state

itemBlankAttr :: AttrName

The itemBlankAttr is an interstitial attribute marker for portions of the ItemField that are to be left blank

itemMoreMessageAttr :: AttrName

The itemMoreMessageAttr is used when the ItemField rendering would overflow the available space, so the bottom of the rendering includes a message indicating there is more to display.

itemNoneMessageAttr :: AttrName

The itemNoneMessageAttr is used for the message displayed when the ItemField contains no actual items.

itemSelectedDetailsAttr :: AttrName

The itemSelectedDetailsAttr is used for the details info for the currently selected item that is displayed at the bottom of the itemfield.

itemHeaderAttr :: AttrName

The itemHeaderAttr is used for group headers in the ItemField.

itemDefaultAttrs :: [(AttrName, Attr)]

This defines the list of default attribute values for this itemfield. To apply these to the default attrbute specifications:

App { ...
    , appAttrMap = const $ applyAttrMappings itemDefaultAttrs defaultAttrs
    ... }

and to override these defaults:

App { ...
    , appAttrMap = const
                   $ applyAttrMappings
                       [ (itemHeaderAddr, fg cyan), ... ]
                   $ applyAttrMappings itemDefaultAttrs defaultAttrs
    ... }

where defaultAttrs for Brick < 0.16 is:

import Data.Default (def)
defaultAttrs = def

and for Brick >= 0.16, defaultAttrs is:

import Graphics.Vty.Attrs (defAttrs)
defaultAttrs = attrMap defAttrs []