Menu Component


INTRODUCTION

The Menu Component derivates from a ListView component. You will use it to create nice menus in your programs. Notice that the api92_Menu structure is a little bit saller than the api92_ListView structure.


api92::MenuComponent
  • Parameters :
    A0.l : Address of an api92_Menu 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 : 0-based index of selected item
    A0.l : Address of selected item
    No other register modified

The api92_Menu structure

The api92_Menu structure is a little bit more simple than the api92_ListView structure because this component is specially designed for creating menus. It doesn't support items with constant size, scrolling…

Format of the api92_Menu structure :

$00.w : Number of items
$02.w : X position
$04.w : Y position
$06.w : reserved (must be 0)
$08.w : Width of the Menu component (in pixels)
$0A.b : Flags ( see below )
$0B.b : Nothing
$0C.l : If not null, address of an api92CB_mnuKey function
$10.l : If not null, address of an api92CallBack_mnuDrawItem function
$14.l : Address of an api92_mnuItemsProperties buffer
$18.l : Address of an api92_mnuShortCut buffer



$00.w : Number of items
It is just the number of item that contain your menu.
$02.w ; 04.w : X Position ; Y Position
It is the (X,Y) position on the top-left corner of the Menu component, in pixels.
$06.w : reserved
This word must be set to 0.
$08.w : Width of the Menu component
It is the width of the Menu component, in pixels. It must be large enough.
$0A.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 menu component, don't wait for a key
$0C.l : Address of an api92CB_mnuKey function
If this long word is not null, it must the address of an api92CB_mnuKey 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_Menu 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.


    $10.l : Address of an api92CB_mnuDrawItem function
    If this long word is not null, it must the address of an api92CB_mnuDrawItem 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_Menu 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


    $14.l : Address of an api92_mnuItemsProperties 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
    $14.l : Address of an api92_mnuShortCut buffer
    This buffer is used to show ShowCut at the right side of the menu. Its format is :
    00.w : X offset where you want to show shortcuts
    and then a list of 0-terminated strings.


Examples

You will see in the menu_1.asm and menu2_asm examples how it is simple to use the Menu component.

Here is the code and the result of menu_1.asm

 

    
                  

;--------------------- 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 MenuHeader(PC),a0
lea MenuData(PC),a1
jsr api92::MenuComponent

rts


;------------------- Program Data -------------------
MenuHeader:

dc.w 10                    ;Number of Items
dc.w 20,12                 ;X,Y
dc.w 0                     ;reserved
dc.w 74                    ;Width of the menu
dc.b %00000110             ;flags
dc.b 0
dc.l 0                     ;api92CB_mnuKeys
dc.l 0                     ;api92CB_mnuDrawItem
dc.l 0                     ;api92_mnuItemProperties
dc.l 0                     ;api92_mnuShortCut


MenuData:

dc.b "Lock/Unlock",0
dc.b "Hide/Show",0
dc.b "-",0
dc.b "Copy",0
dc.b "Move",0
dc.b "Rename",0
dc.b "Delete",0
dc.b "New Folder",0
dc.b "-",0
dc.b "Exit",0


_comment dc.b "Menu Demo 1",0

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

end

To make an more advanced menu, with shortcuts, enabled/disabled items, CheckBox items… you just need to replace datas by the following :
(menu_2.asm)

    MenuHeader:

    dc.w 10                    ;Number of Items
    dc.w 20,12                 ;X,Y
    dc.w 0                     ;reserved
    dc.w 74                    ;Width of the menu
    dc.b %00000110 ;flags
    dc.b 0
    dc.l 0                     ;api92CB_mnuKeys
    dc.l 0                     ;api92CB_mnuDrawItem
    dc.l MenuItemProperties    ;api92_mnuItemProperties
    dc.l MenuShortCut          ;api92_mnuShortCut

    MenuData:

    dc.b "Lock/Unlock",0
    dc.b "Hide/Show",0
    dc.b "-",0
    dc.b "Copy",0
    dc.b "Move",0
    dc.b "Rename",0
    dc.b "Delete",0
    dc.b "New Folder",0
    dc.b "-",0
    dc.b "Exit",0

    MenuShortCut:

    dc.w 57 ;X offset
    dc.b 127,"L",0
    dc.b 127,"H",0
    dc.b 0
    dc.b 127,"C",0
    dc.b 127,"M",0
    dc.b 127,"R",0
    dc.b 127,"D",0
    dc.b 127,"N",0
    dc.b 0
    dc.b "ESC",0

    MenuItemProperties:

    dc.b 0,0,1,1,1,7,3,0,1,1

     

    And here is the result :