Brief Index      Full Index      Events Index      I.M. Reference

Enable_String_Events

Functions

void Enable_String_Events (const char *keyboard, HC_KEY cursor_key)
void Disable_String_Events (const char *keyboard, HC_KEY cursor_key)

Function Documentation

void Enable_String_Events ( const char *  keyboard,
HC_KEY  cursor_key 
)

Tells the system to start gathering a string of characters from the user.

Parameters:
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 Insert_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).

DETAILS

String events are similar to "button" events, both gather input from a keyboard device. String events occur only when the user presses a carriage return. They return a whole sequence of keystrokes at a time. The system echoes string input if you provide a place in the segment tree for the echoing to occur. Special keys, which are available as buttons, are not available within strings, or may have special effects during string input.

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.

NOTES

Button events and String events can be enabled on the same keyboard at the same time. If a key is a printing key and has a button attached, it will be included in both places.

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.

RESTRICTIONS

Flagging enabled events causes confusion when a window with events enabled becomes invisible. The work around is to disable events before setting the visibility to off.

See also:
Get_String, Show_String, Show_String_Source, Edit_Text, Flush_By_Key, Set_Heuristics, Insert_String_Cursor, Move_String_Cursor, Enable_Button_Events.
void Disable_String_Events ( const char *  keyboard,
HC_KEY  cursor_key 
)

Disables carriage return events.

Parameters:
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 Insert_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).

DETAILS

No additional details. See Enable_String_Events()

Brief Index      Full Index      Events Index      I.M. Reference