TE_open Function (ROM Call 0xAC)

textedit.h

short TE_open (TEXT_EDIT *te, WINDOW *w, WIN_RECT *rect, HANDLE BufHandle, unsigned short cur_offset, unsigned short ReadOnly, unsigned short Flags);

Initializes the text editor.

TE_open initializes the text editor and displays the initial content of the editor. All text editor operations are controled using a structure of type TEXT_EDIT. TE_open will initialize such structure pointed to by parameter te, which later need to be passed to all text editor operations. It returns TRUE if the initialization was successful, else returns FALSE.

w is a pointer to the parent window of the editor: you can create a new window to be the parent using WinOpen, or you can pass DeskTop as the parameter, if you are happy with its settings (which is usually the case). rect is a pointer to the WIN_RECT structure which describes actual dimensions of the rectangular text editor area. Note that if you use your own window as a parent window, this window must not be "dirty" (i.e. it must not have WF_DIRTY flag set). Windows created by WinOpen are "dirty" by default, so you need to clear "dirty" flag manually before calling TE_open. For example, you can do

w->Flags &= ~WF_DIRTY;
BufHandle is the handle of the text editor buffer, which may be pre-filled with the text (if you want to edit existing text), or filled with zeros (if you want to create a new text). BufHandle may be, for example, a result of HeapAlloc operation. Note that in contrary what I said in the documentation of TIGCCLIB releases prior to 2.2, it can not be a handle of a text variable, because text variables contain additional system data on the begining, and the editor expect a raw data (see Frequently Asked Questions to learn how you can pass a text variable to the editor however).

The content of text buffer is a standard zero-terminated string, in which lines of text are separated with '\r' character (0xD). The size of the buffer is managed automatically by the editor: it will be expanded if necessary to add more text, so you need not to worry about the allocated size. Parameter cur_offset is the initial position of the cursor (counted from the begining of the buffer), and ReadOnly is the count of characters at the begining of the buffer which can't be modified (i.e. which are read-only). ReadOnly is usually set to zero, except in some special applications.

Flags is a set of binary flags which controls the editor. Some of these flags are changed automatically during the operation of the editor. As I currently know, the following bits have sense for usage in parameter Flags of this function (maybe there are more of them, but I am not sure; keep all other bits to zero): Note: TE_open just initializes the editor, displays the intial content of it and exits. It does not enter the editor loop in which keypresses are processed. In fact, there is no such loop: you need to get keypresses manually (using ngetchx or, even better, using EV_getc) and to pass them to TE_handleEvent which will process them. Such approach gives much more flexibility. See TE_handleEvent for an example of usage.


Uses: TE_checkSlack, HeapAlloc, strlen, sf_width, WinAttr, WinBegin, WinChar, WinFill, _du16u16, _mu16u16, ROM Call 0x412
Used by: cmd_input, cmd_inputstr, cmd_prompt, Dialog


See also: TE_openFixed