Brief Index      Full Index      I.M. Reference

Get_String


Functions

void Get_String (const char *context, char *text)
void Get_String_With_Encoding (const char *context, const char *encoding, void *text)

Function Documentation

void Get_String ( const char *  context,
char *  text 
)

Performs all the work needed to have the user type in a string of characters.

Parameters:
context - The name of a segment in which the string will be accumulated.
text - The character string the user typed in. Passed by reference always. Returned to user.

DETAILS

Get_String() is a utility routine that combines a common sequence of input routines. The sequence does the work necessary to create a text primitive and string cursor primitive in the database. The sequence enables that text and cursor for typing into, waits for the typing to finish, and puts everything back the way it was, then returns the result.

In pseudo- C, Get_String() corresponds to the following:


	Open_Segment (context) 
		tkey = KInsert_Text (0.0, 0.0, 0.0, "") 
		ckey = KInsert_String_Cursor (tkey, 0, 0) 
		Enable_String_Events ("?Keyboard", ckey) 
		do Await_Event (&type) 
		until (strcmp (type, "string") == 0) 
		Disable_String_Events ("?Keyboard", ckey) 
		Delete_By_Key (tkey) 
	Close_Segment () 
	Show_String (&text) 

The "text" is then returned to the original caller. The appearance of the text on the screen is controlled by the attributes of context, the system makes no check of these attributes for reasonableness. Guard against context not actually being visible on any display.

Get_String_With_Encoding() is the same as the above, except that the Insert_Text() line becomes

	tkey = KInsert_Text_With_Encoding(0.0, 0.0, 0.0, encoding, "")

 

and the Show_String() becomes

	Show_String_With_Encoding (&dummy, &text)

 

where the value in "dummy" is discarded (it is presumed to be the same as the value in encoding.)

During string input the following keys, if your keyboard has them, will have special meaning:

control-U---deletes characters back to the beginning of the line.

rubout, delete, backspace, or control-H---deletes the character immediately before the cursor.

left arrow---moves the cursor one character left non-destructively.

right arrow---moves the cursor back to the right.

up arrow---moves up to the line that was entered in response to the previous string request. Repeated "up arrows" will continue moving up to older and older entries.

down arrow---moves back down after an "up arrow" has been typed.

return---ends string input, and queues a string event to the program.

More special keys and more synonyms for the existing keys may be added in future releases.

NOTES

In the present implementation, the system has to refresh the whole surrounding window whenever a character is typed (unless context has the "quick moves" heuristic turned on). So use as small a surrounding window as possible. (But be sure to allow 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. This will remain true in future implementations.

Given the "0.0, 0.0, 0.0" text position, a small surrounding window plus a "centered" text alignment usually works out well.

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

Get_String() does not verify the string event received exactly matches the string event enabled.

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

It's possible to let the user edit a text string that already has characters in it --- but Get_String() can't do it; you need to call Enable_String_Events() directly, and give it a non-empty-text key.

RESTRICTIONS

See also:
Enable_String_Events, Await_Event, Show_String, Show_String_Source, Set_Heuristics, Set_Text_Alignment, Set_Window, Insert_Text, Compute_Text16_From_Text.

void Get_String_With_Encoding ( const char *  context,
const char *  encoding,
void *  text 
)

Similar to Get_String(), but operates on encoded text rather than Latin1 text.

Parameters:
context - The name of a segment in which the string will be accumulated.
encoding - The encodingto be used for text.
text - The character string the user typed in. Passed by reference always. Returned to user.

DETAILS

No additional details. See Get_String()

Main Index
Brief Index      Full Index      I.M. Functions