ListView Component


INTRODUCTION

The ListView component is a very powerful component that will enable you to add nice features in your programs. It is used to show a list of strings, supporting scrolling if needed.



api92::ListViewComponent

The api92::ListViewComponent is the only function to call to use the ListView Component.
  • Parameters :
    A0.l : Address of an api92_ListView structure
    A1.l : Address of data
  • Return Values :
    D0.w :
      by default : #13 if enter was pressed, #264 if esc was pressed
      Else it is the value given in the api92CB_lvKey.

    D1.w : Value given in the api92CB_lvKey function
    A0.l : Address of selected item
    No other register modified


The
api92_ListView structure

Don't be afraid by the size of that structure ! It is so long because that component offers thousands of possibilities, but I don't think you will use all of them at the same time. Look now at the example.
Notice that the Menu component or the SelectFile component are programmed using the api92::ListViewComponent call.
What is sure is that it is NOT difficult to use the ListView component. Just look at the exemples !

Format of the api92_ListView structure :

$00.w : Number of items
$02.w : Number of items per page
$04.w : X position
$06.w : Y position
$08.w : reserved (must be 0)
$0A.w : reserved (must be 0)
$0C.w : Width of the Listview component (in pixels)
$0E.W : If null, all items must be zero terminated (like a string list)
Else all items must have that constant size
$10.w : If null, use default item size (according to current font)
Else all items will have that height
$12.b : Flags ( see below )
$13.b : Nothing
$14.l : If not null, address of an api92CB_lvKeyDown function
$18.l : If not null, address of an api92CB_lvKey function
$1C.l : If not null, address of an api92CB_lvOnSelect function
$20.l : If not null, address of an api92CallBack_lvDrawItem function
$24.l : Address of an api92_lvItemsProperties buffer


$00.w : Number of items
It is just the number of item that contain your list.
$02.w : Number of items per page
It is the maximum number of items that will be shown simultaneously. Else a scrolling will be needed.
$04.w ; 06.w : X Position ; Y Position
It is the (X,Y) position on the top-left corner of the ListView component, in pixels.
$08.w ; 0A.w : reserved
This long word must be set to 0.
$0C.w : Width of the ListView component
It is the width of the ListView component, in pixels. It must be large enough.
$0E.w : Constant size of each item
It is a very interesting side of the component. The data of your list can have two different format :
- First Format : If that word is null, each items of your list must be zero terminated. It can be useful for strings lists.
- Second format : else each items will have a constant size. For example, to show the constant of a VAT, you should set this word to the size of each item of the VAT.
$10.w : Constant height of each item
If you set it to 0, the height of item will be calculated according to the current font.
Else you can define a constant height for each item.
$12.b : Flags
Flags enables you to use or not some caracteristics of the component. Each bit of that byte have a consequence :
xxxxxxx1 : If bit set don't draw the rectangle of the list
xxxxxx1x : If set allow the user to jump from the first item to the last, or from the last to the first using the pad.
xxxxx1xx : If set, keep the previous selected item
x1xxxxxx : If set, draw a very nice vertical scroll bar =)
1xxxxxxx : If set, only draw listview component, don't wait for a key
$14.l : Address of an api92CB_lvKeyDown function
If this long word is not null, it must the address of an api92CB_lvKeyDown callback function that will be called before the internal key handler of the component.
  • Parameters :
    D0.w : Scancode of key pressed
    D6.w : 0-based index of selected item
    A1.l : Address of current selected item string
    A6.l : Address of current api92_ListView structure used

$18.l : Address of an api92CB_lvKey function
If this long word is not null, it must the address of an api92CB_lvKey callback function that will be called each time a key is pressed.
  • Parameters :
    D0.w : Scancode of key pressed
    D6.w : 0-based index of selected item
    A1.l : Address of current selected item string
    A6.l : Address of current api92_ListView structure used
  • Return Values
    D0.w : If d0.w = 0, continue
    If d0.w = $FFFF, redraw component and continue
    Else exit component
    D1.w : Value to return in d1.w after the component call.

$1C.l : Address of an api92CB_lvOnSelect function
If this long word is not null, it must the address of an api92CB_lvOnSelect callback function that will be called each time the user select a new item
$20.l : Address of an api92CB_lvDrawItem function
If this long word is not null, it must the address of an api92CB_lvDrawItem callback function that will be called each time an item must be drawn.
  • Parameters
    D0.w : X position
    D1.w : Y position
    D6.w : 0-based index of current selected item
    A1.l : Address of current selected item string
    A6.l : Address of current api92_ListView structure used
  • Return Values
    D0.w : If d0.w = 0, skip internal drawing of the component. Else use internal drawing used by default by the component

$24.l : Address of an api92_lvItemsProperties buffer
This buffer is a buffer of a byte for each item. Each byte describes the format of the item. It has the following format :
xxxxxxxO : 1 = Item Enabled / 0 = Item Disabled
xxxxxxOx : 1 = Use Checkbox for item
xxxxxOxx : 1 = Item Checked / 0 = Item Unchecked

 

Examples

You are going to see how simple you can use the ListView Component.

Just look at the lv_1 example :

;--------------------- Includes ---------------------
include "tios.h"
include "api92.h"
include "api92cst.h"

;------------ Start of assembly program -------------
xdef _main
xdef _comment

_main:

moveq.w #0,d0
jsr api92::SetFont

lea ListViewHeader(PC),a0
lea ListViewData(PC),a1
jsr api92::ListViewComponent

rts

;------------------- Program Data -------------------
ListViewHeader:

dc.w 12          ;Number of items
dc.w 5            ;Number of items per page
dc.w 10,10     ;X,Y
dc.l 0              ;reserved
dc.w 120        ;Width of the component
dc.w 0            ;Constant item size
dc.w 0            ;Constant item height
dc.b %01000000,0 ;Flag
dc.l 0             ;api92CB_lvKeyDown
dc.l 0             ;api92CB_lvKey
dc.l 0             ;api92CB_lvOnSelect
dc.l 0             ;api92CB_lvDrawItem
dc.l 0             ;api92CB_lvItemsProperties

ListViewData:

dc.b "Here is an example",0
dc.b "that shows how",0
dc.b "you can very",0
dc.b "easly program",0
dc.b "a list with a",0
dc.b "scrolling (quite nice, isn't it?)",0
dc.b "",0
dc.b "Here it use variable",0
dc.b "item size",0
dc.b "what it quite",0
dc.b "good to avoid",0
dc.b "wasting memory",0


_comment dc.b "ListView Demo 1",0

;-------------------- End of program ------------------

end

Here is the result :


You have a quite advanced use of the ListView component in Misc\FileCmp.asm : it gets the address of the two files to compare, and creates an array of 4 bytes for each entry where it puts the offset of all different bytes. Thus the data given in the ListView component is not a string list, but an array of long word. Then the only thing to do is to use the api92CB_lvDrawItem callback function, and to print the item, printing the offset.
This type of use is A LOT used in PCTOOLS, because it requires very few memory compared to saving the whole string.