SelectFile Component


INTRODUCTION

The SelectFile component is a component that will be used to select a file in one of the directory of the calculator. What is quite good is that it supports nested folders ! What is more, I am sure you will like its graphical interface, with icons…



api92::SelectFileComponent
  • Parameters :
    A0.l : Address of an api92_SelectFile structure
  • 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 : Handle of selected file
    No other register modified


The api92_SelectFile structure

Format of the api92_SelectFile structure :

$00.w : X position
$02.w : Y position
$04.w : Number of items per page
$06.w : Width of the Listview component (in pixels)
$08.w : Handle of current folder
$0A.b : Flags ( see below )
$0B.b : Nothing
$0C.l : If not null, address of an api92CB_Filter function
$10.l : If not null, address of an api92CB_lvKeyDown function
$14.l : If not null, address of an api92CB_lvKey function
$18.l : If not null, address of an api92CB_lvOnSelect
$1C.l : If not null, address of an api92CallBack_lvDrawItem function

 


$00.w ; 02.w : X Position ; Y Position
It is the (X,Y) position on the top-left corner of the SelectFile component, in pixels.
$04.w : Number of items per page
It is the maximum number of items that will be shown simultaneously. Else a scrolling will be needed.
$06.w : Width of the ListView component
It is the width of the SelectFile component, in pixels. It must be large enough.
$08.w : Handle of current folder
It is the handle of the last folder selected. Notice that if it is null, or if it is an invalid folder handle, the component will show the root of the calculator.
$OA.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.
xxxx1xxx : If set, draw icons for a great graphic result
xxx1xxxx : If set, the user will be able to naviguate between folders using pad left / pad right
x1xxxxxx : If set, draw a very nice vertical scroll bar =)
1xxxxxxx : If set, only draw listview component, don't wait for a key

$0C.l : Address of an api92CB_Filter
If this long word is not null, it must the address of an api92CB_Filter callback function that
Will be called to filter files to show. It is a very powerful way to make the component universal.
(See for instance the slctfil2 or the slctfil3 which uses filter.)

  • Parameters :
    D7.w : Handle of created array buffer
    A0.l : Address of current VAT entry to filter
  • Return Values : D0.w : If d0.w = 0, don't add item. Else add item

$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

 

Examples

All examples about the SelectFile component are in the Examples\SlctFile directory.

The more simple example is slctfil1.asm. The graphical result is amazing compared to the size of the program. See yourself :

;--------------------- Includes ---------------------

        include "tios.h"
        include "api92.h"
        include "api92cst.h"

;------------ Start of assembly program -------------

        xdef _main
        xdef _comment

_main:  lea winOpenDialog(PC),a0
        jsr api92::draw_sWindow2

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

        lea SelectFileHeader(PC),a0
        jsr api92::SelectFileComponent

        rts


;------------------- Program Data -------------------

SelectFileHeader:
        dc.w 70+OX,42+OY ;X,Y
        dc.w 5 ;Nb Item per page
        dc.w 100 ;Width of the component
        dc.w 0 ;Current Folder
        dc.b %00011001,0 ;Flags
        dc.l 0 ;api92CB_Filter
        dc.l 0 ;api92CB_lvKeyDown
        dc.l 0 ;api92CB_lvKey
        dc.l 0 ;api92CB_lvOnSelect
        dc.l 0 ;api92CB_lvDrawItem


winOpenDialog
        dc.b 40+OX,30+OY,199+OX,95+OY,"Open Dialog",0


_comment dc.b "Select File - Ex1",0


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

end

Here is the result

 

The slctfil2.asm shows the use of the api92CB_Filter callback function. The example shows only TEXT files.
The only thing to add is the following function :

api92CB_Filter:
        moveq.w #1,d0 ;d0=1 : Add

        btst.b #7,VAT_ENTRYFLAG(a0) ;if a folder
        bne.s \exit ;add it

        move.w VAT_ENTRYHDL(a0),d0
        jsr api92::DEREFd0a0
        jsr api92::vat_GetFileExt
        cmp.w #EXT_TEXT,d2
        beq.s \exit
        clr.w d0 ;d0=0 : Don't Add
\exit   rts


The slctfil3.asm examples looks like the previous example, butprint the complete name of the selected file when the user press ENTER. (it uses nested folders, like in PCTOOLS)