Brief Index      Full Index      Events Index      I.M. Reference

Get_Button


Functions

void Get_Button (char *button)

Function Documentation

void Get_Button ( char *  button  ) 

Performs all the work needed to have the user push a button. Returns the result to your program.

Parameters:
button - The button name (see below for details.) Passed by reference always. Returned to user.

DETAILS

Get_Button() is a utility routine that combines a common sequence of input routines. The sequence does all the work necessary to start the system listening to an input device. The sequence waits for the user to push a button, puts the system back to the way it was, and returns the name of the button.

Use Get_Button() when you're interested in individual keystrokes, and Get_String() when you want a whole string. Use Get_Location() or Get_Selection() when you're interested in position information as well.

In pseudo-C, Get_Button() corresponds to


		Enable_Button_Events ("?Keyboard", "anything") 
		do Await_Event (&type) 
		until (strcmp (type, "button") == 0) 
		Disable_Button_Events ("?Keyboard", "anything")
		Show_Button (&button) 

"Button" is returned to your program. Show_Button_Source() can then be called to gain extra information about the button event. Events other than button events are ignored. To avoid this you can call Enable_Button_Events() and Await_Event() directly.

The possible values for button include the following:

A to Z, a to z, 0 to 9, etc.

Any single printing ASCII character, except comma.

comma

The comma key, spelled out. (This is necessary because commas are used as separators in other button routines.)

control a, control b, etc.

The control keys, if the specified device has them and if the operating system allows HOOPS to read them. The interrupt key, the end-of-file key, and the flow-control control keys are not available for button events. On some systems the control keys might not be available at all.

left arrow, right arrow, up arrow, down arrow

The "arrow" keys, if the specified device has them and the driver is able to decode them.

f0, f1, f2,...

The "function" keys, if the specified device has them and the driver is able to decode them.

kp0, kp1, kp2,...

The "keypad" keys, if the specified device has them and the driver is able to decode them.

The uppercase and lowercase letters are specified above exactly as the system returns them.

NOTES

Get_Button() updates the display, courtesy of Await_Event() .

Get_Button() does not verify the button event received came from the enabled keyboard device.

Get_Button() and Show_Button() both return the same information to your program. Get_Button() is a high-level routine that does a variety of work. Show_Button() is a low-level routine whose only function is to extract one existing piece of information from the database.

The "disable event" at the end of Get_Button() gets propagated to the device during the next update.

RESTRICTIONS

See also:
Get_String, Await_Event, Enable_Button_Events, Show_Button, Show_Button_Source, Requeue_Event.

Brief Index      Full Index      Events Index      I.M. Reference