|
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.
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.
|