View source for 83PCE:Hooks:D02608

[[Category:83PCE:Hooks:By_Name|Menu Hook]] [[Category:83PCE:Hooks:By_Address|D02608 - Menu Hook]]
== Synopsis ==
'''Name:''' Menu Hook

'''Hook Pointer Block Address:''' D02608

'''Hook Enable BCALL:''' 021518

'''Hook Disable BCALL:''' 02151C

'''Hook Call BCALL:''' ''(none known)''

'''Hook Active Flag:''' [[83Plus:Flags:36#Bit_6|6, (iy + 36h)]]

The menu hook allows for modification of any of the system menus that are presented through the system monitor.

== Using the Hook ==
This hook, like most, is called for several events, each identified by A. In general, it appears that returning with the zero flag set will cause the OS to execute its normal behavior.

I've ordered the events in the order that they are called by the OS.


'''Before the menu is displayed'''
* '''A=4''': this is the first event called. '''B''' contains the value of the menu about to be displayed. [[84PCE:RAM:D00824|MenuCurrent]] contains the value of the previous menu that was displayed. Return ''nz'' to cancel the displaying. Edit '''B''' to the menu you want to be displayed.
* '''A=0''': this is called BEFORE the header will be drawn. This is the moment to provide your own table. Point '''hl''' to it, and return ''nz''. You can also change menuCurrent and return z, to display another OS menu. An example of how a table would look like, can be found at the bottom of this page. If you still want to display an OS menu, return ''z'', as normal. It is called twice:
** First time: '''B''' = the value of the menu.
** Second time: '''B''' = 0.
* '''A=2''': This event is called before the OS draws (one of the) header(s). '''C''' is the header index, starting with 0. Return ''nz'' to ignore the drawing. Note: the OS will still display the padding space, so it looks a bit weird.
* '''A=0''': the hook is again called when all the headers are drawn. '''A''' is equal to 0, and '''C''' is the number of headers (basically, last index + 1). Return ''nz'' to mess up your calc. I can't guarentee what will happen. Returning ''z'' will display the right menu.
* '''A=1''': The OS is about to draw one of the options. The number prefix has already been drawn. Return ''nz'' to ignore the drawing, it will only 'draw' an empty line. Otherwise, it will just display the right option.


'''Now it waits until the user selects an option'''
* '''A=5''': the hook is also called with '''A''' equal to 5, if the user pressed [UP] or [DOWN]. If necessary, such as the case where it needs to scroll, it starts again with '''A''' = 0, before it draws again all the options.
* '''A=6''': the hook is also called when the user pressed [LEFT] or [RIGHT]. This time, it will jump back to '''A''' = 0, before the headers will be drawn again.


'''The user has selected an item'''
* '''A=0''': '''C''' contains the selected item, starting with 0. It seems that B is equal to C.
* '''A=3''': Return ''nz'' to cancel this, and leave the menu open.

== Examples ==
Here are 2 examples of a menu table would look like.
 <nowiki>ZoomMenu:
	db 1		;how many headers?
	db 3 	;how many choices under 1st header?
	db 5Eh	;string table entry for "ZOOM"
	db 0,kZIn
	db 0,kZOut	;these are 2-byte keypresses of each entry
	db 0,kStd</nowiki>

Another example with more headers:
 <nowiki>ZoomMenu:
	db 2		;how many headers?
	db 3 	;how many choices under 1st header?
	db 2 	;how many choices under 2nd header?
	db 5Eh	;string table entry for "ZOOM"
	db 5Fh  ;just for fun
	db 0,kZIn	;first header
	db 0,kZOut	;these are 2-byte keypresses of each entry
	db 0,kStd
	db 0,kZIn	;second header
	db 0,kZOut	;these are 2-byte keypresses of each entry</nowiki>

'''Notes:'''

You can find the string table entry for strings here: http://wikiti.brandonw.net/index.php?title=83Plus:Hooks:9BCC#Condition_7

The keypress for each token can be found at https://github.com/debrouxl/tilibs/blob/master/libticalcs/trunk/src/keys83p.h