HC_Show_String
-
void
HC_Show_String(char *text) - void HC_Show_String(char text)
Returns the text string that caused the current string-input event.
Once a “string” event has reached the front of the event queue and become the current event - either by enabling string events and then calling Await_Event() , or by calling Get_String() to do all the work - your program can ask for details about it. The simplest detail of a string event is the string that was typed in itself.
Show_String() is appropriate to use if the string cursor referenced by Enable_String_Events() was originally attached to a simple Insert_Text() text primitive. Show_String_With_Encoding() is appropriate if the original text was from Insert_Text_With_Encoding() . You will get an error if you try to use the simple Show_String() when there is nonstandard encoding present. a
To aid in the allocation of a buffer large enough to receive any arbitrary text, you can call Show_String_Length() first to find out how much room you’re going to need. In C remember to allow room for the terminating null. If you are using the “C return string length” System Option then Show_String_Length() will return the full size, but the string returned by Show_String() will be truncated to the return-string length (or one less, if truncating would interrupt a 16-bit character.)
Get_String() and Show_String() both return the same type of information to your program. Get_String() is a high-level routine that does a series of actions. Show_String() is a low-level routine whose only function is to extract one piece of information from the database. Show_String() is generally called after Await_Event() .
The Show routines can be called repeatedly on the same current event without harm, if that’s convenient to your program.
If the current event is not actually a string-type event, or if there is no current event, the system will complain. If the string event is still in progress - if the user has not typed a carriage-return yet - you can peek at the current characters by calling Show_Text() .
Keyword values are normally treated as all lowercase within HOOPS: this will cause an original *encoding * of “JIS”, for example, to come back as “jis”, not “JIS”.
Encoded-text input is at present highly device and driver dependent. Kanji input, for example, is not generally available yet.
HC_Await_Event, HC_Get_String, HC_Enable_String_Events, HC_Show_String_Source, HC_Show_Text, HC_Define_System_Options, HC_Compute_Text16_From_Text.Parameters
text: The character string the user has just finished typing in. Passed by reference always. Returned to user.