itemfield- A brick Widget for selectable summary of many elements on a terminal

Copyright(c) Kevin Quick 2016
Safe HaskellNone




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.



cntItems :: [Items] -> NumItems Source #

Returns the count of the number of items

data ItemField Source #

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.




  • 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

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

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


data ItemFieldWidget n Source #

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




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

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) Source #

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) Source #

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) Source #

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

getSelectedItem :: ItemFieldWidget n -> Int Source #

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

Retrieving and updating marked items

getMarkedItems :: ItemFieldWidget n -> [Int] Source #

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

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

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

itemAttr :: AttrName Source #

The itemAttr is the base attribute for the entire Widget

itemFieldAttr :: AttrName Source #

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 Source #

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 Source #

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

itemGoodAttr :: AttrName Source #

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

itemBadAttr :: AttrName Source #

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

itemPendingAttr :: AttrName Source #

The itemPendingAttr indicates an item that is in the Pending state

itemBlankAttr :: AttrName Source #

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

itemMoreMessageAttr :: AttrName Source #

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 Source #

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

itemSelectedDetailsAttr :: AttrName Source #

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

itemHeaderAttr :: AttrName Source #

The itemHeaderAttr is used for group headers in the ItemField.

itemDefaultAttrs :: [(AttrName, Attr)] Source #

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 []