Functions | |
void | Show_String (char *text) |
Returns the text string that caused the current string-input event. More... | |
void | Show_String_Count (int *count) |
Finds the number of characters in the string the user has just finished typing in. More... | |
void | Show_String_Length (int *length) |
Finds the number of bytes in the string the user has just finished typing in. More... | |
void | Show_String_With_Encoding (char *encoding, void *text) |
Similar to Show_String(), but operates on encoded text rather than Latin1 text. More... | |
Detailed Description
Function Documentation
◆ Show_String()
void Show_String | ( | char * | text | ) |
Returns the text string that caused the current string-input event.
- Parameters
-
text - The character string the user has just finished typing in. Passed by reference always. Returned to user.
DETAILS
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.)
NOTES
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.
RESTRICTIONS
◆ Show_String_Count()
void Show_String_Count | ( | int * | count | ) |
Finds the number of characters in the string the user has just finished typing in.
- Parameters
-
count - Number of characters in the entered string. 16-bit character values countas 1 character. In C this value does not include the terminating null character. Returned to user. Passed by reference always.
DETAILS
No additional details. See Show_String()
◆ Show_String_Length()
void Show_String_Length | ( | int * | length | ) |
Finds the number of bytes in the string the user has just finished typing in.
- Parameters
-
length - Number of bytes in the entered string. 16-bit character values count as 2 bytes. In C this value does not include the terminating null character. Returned to user. Passed by reference always.
DETAILS
No additional details. See Show_String()
◆ Show_String_With_Encoding()
void Show_String_With_Encoding | ( | char * | encoding, |
void * | text | ||
) |
Similar to Show_String(), but operates on encoded text rather than Latin1 text.
- Parameters
-
encoding - The encodingused in the Insert_Text_With_Encoding() indirectly referenced by Enable_String_Events() , or the constant "iso latin one" if there was no special encoding. Passed by reference always. Returned to user. text - The character string the user has just finished typing in. Passed by reference always. Returned to user.
DETAILS
No additional details. See Show_String()