Canvas List
1 Example
2 Class
canvas-list%
new
count-items
sort-items
filter-items
reset-primary-key
get-item
set-items
insert-items
append-items
get-selected-index
get-selected-item
get-hover-index
get-hover-item
scroll-to-selection
open-selected-item
select-index
clear-selection
select-first
select-last
select-next
select-previous
call-with-selected-item
8.12

Canvas List🔗ℹ

Jeffrey Massung <massung@gmail.com>

 (require canvas-list) package: canvas-list

A canvas-list is a fast-rendering, single-selection, list control, which allows for complete custom drawing of each item.

1 Example🔗ℹ

(require racket/gui canvas-list)
 
(define frame
  (new frame%
       [label "List Canvas"]
       [width 260]
       [height 400]))
 
(define canvas
  (new canvas-list%
       [parent frame]
       [items (range 1000)]
       [action-callback (λ (canvas item event)
                          (displayln item))]))
 
(send frame show #t)

2 Class🔗ℹ

class

canvas-list% : class?

  superclass: canvas%

A canvas-list% is similar in nature to a list-box%, but instead derives from canvas%. This allows for extremely fast, custom rendering of very large lists. It supports single selection, keyboard and mouse navigation, context menus, mouse hovering, alternate row colors, primary key indexing, sorting, filtering, and more.

constructor

(new canvas-list% 
    [[items items] 
    [item-height item-height] 
    [item-color item-color] 
    [alt-color alt-color] 
    [selection-color selection-color] 
    [hover-color hover-color] 
    [force-selection force-selection] 
    [paint-item-callback paint-item-callback] 
    [selection-callback selection-callback] 
    [action-callback action-callback] 
    [context-action-callback context-action-callback]]) 
  (is-a?/c canvas-list%)
  items : sequence? = #()
  item-height : exact-nonnegative-integer? = 20
  item-color : (or/c (is-a?/c color%) #f) = #f
  alt-color : (or/c (is-a?/c color%) #f) = #f
  selection-color : (or/c (is-a?/c color%) #f) = #f
  hover-color : (or/c (is-a?/c color%) #f) = #f
  force-selection : boolean? = #f
  paint-item-callback : 
(or/c ((is-a?/c canvas-list%)
       any/c
       (or/c 'selected 'hover 'alt #f)
       (is-a?/c dc<%>)
       exact-nonnegative-integer?
       exact-nonnegative-integer?
       ->
       any/c)
      #f)
   = #f
  selection-callback : 
(or/c ((is-a?/c canvas-list%)
       any/c
       (or/c (is-a?/c mouse-event%) #f)
       ->
       any/c)
      #f)
   = #f
  action-callback : 
(or/c ((is-a?/c canvas-list%)
       any/c
       (or/c (is-a?/c mouse-event%) #f)
       ->
       any/c)
      #f)
 = #f
  context-action-callback : 
(or/c ((is-a?/c canvas-list%)
       any/c
       (or/c (is-a?/c mouse-event%) #f)
       ->
       any/c)
      #f)
   = #f
Creates a new canvas-list% with an initial set of items.

The items are the initial sequence of items that should be displayed.

The item-height is the height - in pixels - afforded for each item to be drawn. This must be the same for every item and (currently) items can not have different heights.

There are 4 different, basic, background colors that are used to draw items by default. item-color is the basic background color used to draw each item and defaults to white. The alt-color - if provided - is the background color used for every-other item and defaults to a very light gray. The selection-color and hover-color are both used to highlight the currently selected item and the item the mouse is currently hovering over.

The force-selection parameter - when #t - makes it so that once an item in the list has been selected it cannot be unselected (typically by pressing ESC).

The paint-item-callback is called to render each item in the list. Before being called, the dc<%> clipping rect is set and translated to the correct location on screen; drawing at <0,0> will be the upper-left corner of the item’s cell. The arguments passed are the canvas-list% control, then item to render, the state of the item (whether it’s selected, being hovered, or an alternate index), the dc<%>, and the width and height of the cell.

The selection-callback is called every time the currently selected item changes to a different item in the list. It is passed the canvas-list%, the item selected, and - if selected with the mouse - the mouse-event%. If selection happens using the keyboard (e.g. arrow keys), then #f is passed for the event.

The action-callback is called whenever the user double-clicks an item or presses RETURN/ENTER while an item is selected. It is passed the same arguments as the selection-callback.

The context-action-callback is called when the user right-clicks an item. Typically this is used to bring up a popup-menu%. It is passed the same arguments as the selection-callback.

method

(send a-canvas-list count-items)  exact-nonnegative-integer?

Returns the number of items in the primary key. This may be less than the number of items in the list if there is a filter applied.

method

(send a-canvas-list sort-items less-than?    
  [#:key key])  void?
  less-than? : (any/c any/c -> boolean?)
  key : (or/c (any/c -> any/c) #f) = #f
Sorts the items in the list.

method

(send a-canvas-list filter-items pred    
  [#:key key])  void?
  pred : (any/c -> boolean?)
  key : (or/c (any/c -> any/c) #f) = #f
Applies a filter to the items in the list, hiding any that do not match the predicate.

method

(send a-canvas-list reset-primary-key)  void?

Removes any applied sorting or filters to the list.

method

(send a-canvas-list get-item index)  any/c

  index : exact-nonnegative-integer?
Returns the item at the given index or #f if the index is out of range.

method

(send a-canvas-list set-items items)  void?

  items : sequence?
Clears the current set of items being displayed and replaces it with a new set.

method

(send a-canvas-list insert-items items    
  [index])  void?
  items : sequence?
  index : (or/c exact-nonnegative-integer? #f) = #f
Inserts items into the list at the given index. If no index is provided it is inserted before the currently selected index. If there is no selection it is inserted at the beginning.

method

(send a-canvas-list append-items items    
  [index])  void?
  items : sequence?
  index : (or/c exact-nonnegative-integer? #f) = #f
Appends items onto the list at the given index. If no index is provided it is added after the currently selected index. If there is no selection it is inserted at the beginning.

method

(send a-canvas-list get-selected-index)

  (or/c exact-nonnegative-integer? #f)
Returns the index of the currently selected item or #f if there is no selection.

method

(send a-canvas-list get-selected-item)  any/c

Returns the currently selected item or #f if there is no selection.

method

(send a-canvas-list get-hover-index)

  (or/c exact-nonnegative-integer? #f)
Returns the index of the currently hovered item or #f if there is no item being hovered over.

method

(send a-canvas-list get-hover-item)  any/c

Returns the currently hovered item or #f if there is no item being hovered over.

method

(send a-canvas-list scroll-to-selection)  void?

Ensures that the currently selected item is visible.

method

(send a-canvas-list open-selected-item)  void?

If an action-callback was set and there is a selected item, apply the callback.

method

(send a-canvas-list select-index [index])  void?

  index : (or/c exact-nonnegative-integer? #f) = hover-index
Changes the current selection to the index. If not provided, the index of the currently hovered over item is used. If #f, then the current selection is cleared.

method

(send a-canvas-list clear-selection)  void?

Clears the current selection.

method

(send a-canvas-list select-first)  void?

Selects the first item in the list.

method

(send a-canvas-list select-last)  void?

Selects the last item in the list.

method

(send a-canvas-list select-next [#:advance n])  void?

  n : exact-nonnegative-integer? = 1
Moves to the next item in the list after the current selection. The advance parameter is useful when wanting to skip items (e.g. when using page-up/page-down).

method

(send a-canvas-list select-previous [#:advance n])  void?

  n : exact-nonnegative-integer? = 1
Moves to the previous item in the list before the current selection. The advance parameter is useful when wanting to skip items (e.g. when using page-up/page-down).

method

(send a-canvas-list call-with-selected-item proc)  void?

  proc : (any/c -> any/c)
If there is a selected item, call proc with the selected item.