Functions | |
void | Enable_String_Events (const char *keyboard, HC_KEY cursor_key) |
void | Disable_String_Events (const char *keyboard, HC_KEY cursor_key) |
void Enable_String_Events | ( | const char * | keyboard, | |
HC_KEY | cursor_key | |||
) |
Tells the system to start gathering a string of characters from the user.
keyboard | - Commonly "?Keyboard". In general, a segment with an attached device driver that knows about a physical key board. | |
cursor_key | - The key returned from a previous call to KInsert_String_Cursor() . The system will use the cursor and the associated text area to echo keystrokes as they occur. To omit echoing, specify cursor_key as zero ("0L" in C). |
Use button events to attach various keystrokes to each different immediate program action. Use string events when you need the user to type in the answer to a question.
In order for string input to occur, you have to name the device you're interested in monitoring and, optionally, where you want the echoing to occur. The easiest way to do this is to let one of the high-level "Get" routines do it for you. In the case of string events, the Get routine would be Get_String() . The problems with Get_String() are that unexpected events are thrown away, so you can't gracefully allow for input from a keyboard and a locater simultaneously. For example, you have no control over the appearance of the string echoing on the screen.
If you want to do it yourself, call Enable_String_Events() directly to establish your interest in a device and start it running. Then call Await_Event() to acquire new events. Finally call Show_String() (or a related routine) to take a look at the events. When your program or subsection of your program is done with the device, it can call Disable_String_Events() to restore operations to their previous state.
See Get_String() for a description of the various special keys that are in effect during string input.
Enable_String_Events() does not flush out the text pointed to by the string cursor---it starts with whatever characters were already there and whatever position the cursor was pointing to. This includes characters and cursor positions left over from previous string events that used the same text and cursor. Depending on your application, you may want to call Flush_By_Key() to clear out old stuff or Edit_Text() to insert a new default string, or both.
In the present implementation the system has to refresh the whole surrounding window whenever a character is typed. If you use echoing and not the "quick moves" heuristic, it is a good idea to use as small a surrounding window as possible. (But be sure to allow at least a few pixels around the sides, in case there are minor variations in character clipping on different machines.) If you use center or right-aligned text, something will have to be erased to keep the display accurate.
The Enable or Disable does not take effect until the next call to Await_Event() or Check_For_Events() .
When a source of input is finally turned off, any pending events originating from it are discarded from the event queue.
void Disable_String_Events | ( | const char * | keyboard, | |
HC_KEY | cursor_key | |||
) |
Disables carriage return events.
keyboard | - Commonly "?Keyboard". In general, a segment with an attached device driver that knows about a physical key board. | |
cursor_key | - The key returned from a previous call to KInsert_String_Cursor() . The system will use the cursor and the associated text area to echo keystrokes as they occur. To omit echoing, specify cursor_key as zero ("0L" in C). |