| 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):

- Bit b0 should be set for the standard operation of the editor. If this is reset, the editor will operate in "compact" mode, in which the editor is only one character high, and where the content of the editor will scroll left/right when necessary (such mode is used in request boxes in dialogs). In "compact" mode, the content of the editor buffer must not contain '\r' characters, else the editor will be fooled.
- When b1 = 1, each line of the editor will be preceded with a colon (":"), like in "Text editor" or "Program editor". When b1 = 0, there will not be a preceding colon.
- Bit 2 is used only if b1 = 1. When b2 is also 1, the first character of each line will be regarded as "command character", and it will be displayed before the colon. "Text editor" application uses such mode to store editor commands (like "P" = "PrintObj" etc.). Note that when b2 = 1, parameter cur_offset must not be zero (it is usually set to 1 in this case).
- When b3 = 1, the editor enters some strange mode in which each line is preceded with a left arrow. As I am not sure about such mode, I suggest to you to avoid this.
- Bit b7 is set for text editors opened with TE_openFixed: you don't need to use this bit!
- When b11 = 1, the editor enters read-only mode, i.e. you can not insert or delete characters, etc.

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