4glworks reference: Menu tools and timer events

mnh_compare

file imnhl.4gl
declaration
function mnh_compare(m1, p1, m2, p2)
    define m1, p1,
	   m2, p2	smallint
returns result, boolean, result of the comparison
purpose compares two messages
example none
notes none

mnh_drop

file imnhl.4gl
declaration
function mnh_drop(m, p)
    define m, p	smallint
returns n, integer, the number of dropped entries
purpose Drops any menu entries (options or quick keys) returning message m, p
example none
notes none

mnh_error

file imnhl.4gl
declaration
function mnh_error()
returns desc_mnv, char(25), menu entry description
msg, smallint, associated message body
parm, smallint, associated message parameter
purpose Used after an invocation to mnh_opt or mnh_key to gather information of the existing menu entry that caused the call to fail
example none
notes none

mnh_get

file imnhl.4gl
declaration
function mnh_get()
returns a message
purpose Displays an horizontal menu, and returns the message associated to the option chosen by the user.
example none
notes
  • Note that due to timer messages, mnh_get does not necessarely returns only the messages as set up via mnh_key or mnh_opt
  • mnh_get interprets negative message bodies associated with options to mean that an option is associated with a vertical menu. Associating vertical menu entries with non negative (or null) message bodies has no ill effect other than a less tight integration with mnv_get

mnh_getoptpos

file imnhl.4gl
declaration
function mnh_getoptpos(m, p)
    define m, p
returns id, integer, option id
purpose Returns the option id of the first option found to return message m, p
example none
notes none

mnh_help

file imnhl.4gl
declaration
function mnh_help(hn, def)
    define hn, def	smallint
returns nothing
purpose Sets the help number to be displayed when the user presses the help key. Setting def to true will tag the help message as the message to use for all horizontal menus until reset with another call to this function with def being set to true. Null or false flags that help message needs be used for the current menu only.
example none
notes none

mnh_hide

file imnhl.4gl
declaration
function mnh_hide(m, p, v)
    define m, p, v	smallint
returns n, integer, the number of (un)hidden entries
purpose Hides (disables, v true) or reenables (v false or null) any opton or key associated to message m, p
example none
notes none

mnh_key

file imnhl.4gl
declaration
function mnh_key(k, m, p)
    define k, m, p	smallint
returns result, integer, operation result.
purpose Adds a new quick key to the current horizontal menu
example none
notes Returns
  • false if there's no room for further entries
  • null if the new entry conflicts with another, or the message is disabled
  • a positive integer (the menu id), if the operation was successfull

mnh_nextoption

file imnhl.4gl
declaration
function mnh_nextoption(m, p)
    define m, p		smallint
returns nothing
purpose Sets the current option to be the one associated with message m, p
example none
notes none

mnh_opt

file imnhl.4gl
declaration
function mnh_opt(c, d, qk, o, m, p)
    define c		char(8),	#menu option
	   d		char(78),	#menu description
	   qk		char(1),	#hot key
	   o,				#option position within menu
	   m, p		smallint	#associated message
returns result, integer, operation result.
purpose Adds a new option to the current horizontal menu
example none
notes Returns
  • false if there's no room for further entries
  • null if the new entry conflicts with another, or the message is disabled
  • a positive integer (the menu id), if the operation was successfull
The position need not be unused. The option will be placed right after the one currently last if o is less than 1, null, or greater than the number of options currently defined.

mnh_start

file imnhl.4gl
declaration
function mnh_start(name)
    define name		char(5)
returns nothing
purpose Reinitializes the current horizontal menu.
example none
notes Once a menu has been formed, mnh_get can be called multiple times to display it, until such time as this function is invoked. After this invocation a blank horizontal menu is produced.

mnu_clear

file imnuc.c
declaration
function mnu_clear()
returns nothing
purpose Clears the menus message mask
example none
notes This function is only called from within the horizontal menu

mnu_enable

file imnuc.c
declaration
function mnu_enable(s, e, p, o)
    define s, e, p, o	smallint
returns nothing
purpose Enables (o true) or disables (o false) messages s to e on pane p
example none
notes none

mnu_mask

file imnuc.c
declaration
function mnu_mask(s, e, m)
    define s, e, m	smallint
returns nothing
purpose Sets the panes on which messages s to e are enabled
example none
notes The panes are specified by individual bits of m. A set bit indicates that the messages is enabled on the corresponding pane. Only the first 5 bits of the mask will be used

mnu_record

file imnuc.c
declaration
function mnu_record(s, e, r)
returns nothing
purpose Sets the record flags for messages s to e
example none
notes r denotes on of the following:
  • K_focussedpane: messages s to e are dependent on the presence of a record in the pane that has currently the focus to be enabled
  • a valid pane: messages s to e are dependent on the presence of a record in the specified pane to be enabled
  • 0: messages s to e are not dependent on the presence of any record in any pane

mnv_error

file imnvl.4gl
declaration
function mnv_error()
returns desc_mnv, char(25), menu entry description
msg, smallint, associated message body
parm, smallint, associated message parameter
purpose Used after an invocation to mnv_opt to gather information of the existing menu entry that caused the call to fail
example none
notes none

mnv_get

file imnvl.4gl
declaration
function mnv_get()
returns a message
purpose Displays a vertical menu, and returns the message associated to the option chosen by the user, or a null message if the interrupt key was pressed.
example none
notes Note that due to timer messages, mnv_get does not necessarely returns only the messages as set up via mnv_opt

mnv_help

file imnvl.4gl
declaration
function mnv_help(hn, def)
    define hn, def	smallint
returns nothing
purpose Sets the help number to be displayed when the user presses the help key. Setting def to true will tag the help message as the message to use for all vertical menus until reset with another call to this function with def being set to true. Null or false flags that help message needs be used for the current menu only.
example none
notes none

mnv_ismenu

file imnvl.4gl
declaration
function mnv_ismenu()
returns nothing
purpose Normally used by mnh_get disables the automatic return of mnv_get in case of a single option vertical menu.
example none
notes none

mnv_opt

file imnvl.4gl
declaration
function mnv_opt(dm, qk, m, p)
    define dm	char(25),	#description
	   qk	char(1),	#hot key
	   m, p	smallint	#associated message
returns result, integer, operation result.
purpose Adds a new item to the current vertical menu
example none
notes Returns
  • false if there's no room for further entries
  • null if the new entry conflicts with another, or the message is disabled
  • a positive integer (the menu id), if the operation was successfull

mnv_pos

file imnvl.4gl
declaration
function mnv_pos(col)
    define col	smallint
returns nothing
purpose Sets the position on which the menu is going to be displayed (leftmost column)
example none
notes mnh_get sets the vertical menu position to the position of the horizontal menu option chosen by the user, thus in normal operation there should be no need to call this function

mnv_standalone

file imnvl.4gl
declaration
function mnv_standalone()
returns nothing
purpose Flags that a menu is not part of a menu structure. This disables horizontal arrow movement.
example none
notes Once a menu has been formed, mnv_get can be called multiple times to display it, however it resets the standalone flag. Therefore mnv_standalone should be called prior to each mnv_get invocation.

mnv_start

file imnvl.4gl
declaration
function mnv_start()
returns nothing
purpose Reinitializes the current vertical menu.
example none
notes Once a menu has been formed, mnv_get can be called multiple times to display it, until such time as this function is invoked. After this invocation a blank vertical menu is produced.

tim_clear

file itiml.4gl
declaration
function tim_clear()
returns nothing
purpose removes viewer dependent events
example none
notes This function is only called from the horizontal menu

tim_drop

file itiml.4gl
declaration
function tim_drop(e)
    define e	integer
returns nothing
purpose removes an event
example none
notes none

tim_set

file itiml.4gl
declaration
function tim_set(d, l, a, k, m, p)
    define d		integer,	#delay in secs
	   l,				#event count, NULL = indefinite
	   a,				#true if alarm should *not* be cleared
					#when the current viewer terminates
	   k		smallint,	#alarm type:	A_mandatory
					#		A_timepriority
					#		A_contpriority
					#		A_keyboard
	   m, p		smallint	#message to send
returns tim_id, integer, event unique identifier
purpose Sets an event
example none
notes
  • returns null if the event cannot be set up
  • events are not cleared when the current viewer terminates, unless thay have been created with the a variable being false
  • alarm types are defined in itimh.4gh
  • alarm types are as follows:
    • A_keyboard: a message is sent after d seconds of keyboard inactivity
    • A_mandatory: a message is sent every d seconds, even if the delay has, for some reason, expired earliea, and the alarm has been missed
    • A_timepriority: a message is sent every d seconds, missed alarms do not generate messages, the event expires after d*l seconds, independently of how many times a message has been sent
    • A_countpriority: a message is sent every d seconds, missed alarms do not generate messages, the event expires after the associated message has been sent l times


Please address questions or comments to marco greco
(last updated Thu, 28 March 2002 16:10:12 GMT)