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 contents of the editor. All text editor operations are controled using a structure of type TEXT_EDIT. TE_open will initialize such a structure pointed to by the parameter te, which later needs to be passed to all text editor operations (i.e. te must be allocated statically to maintain state between calls to the text edit routines). It returns TRUE if the edit buffer could be allocated, or FALSE if there is insufficient memory to allocate the edit buffer. This routine always returns TRUE if BufHandle is passed in with the handle to a text buffer.

Note: The window w must already be open. The handle BufHandle must not be locked.

This routine may cause heap compression.

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 the actual dimensions of the rectangular text editor area (You can pass NULL to use entire client rectangle of the window w for the edit region). Note that if you use your own window as a parent window, this window must not be "dirty" (i.e. it must not have the WF_DIRTY flag set). Windows created by WinOpen are "dirty" by default, so you need to clear the "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, the result of a HeapAlloc operation. BufHandle can also be H_NULL, in this case TE_open will allocate a new handle and initialize it with no text. Note that contrary to what I said in the documentation of TIGCCLIB releases prior to 2.2, it cannot be a handle of a text variable, because text variables contain additional system data on the begining, and the editor expect raw data (see the Frequently Asked Questions to learn how you can pass a text variable to the editor though).

The contents of the text buffer are a standard zero-terminated string, in which lines of text are separated with '\r' characters (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.

The parameter cur_offset is the initial position of the cursor (counted from the begining of the buffer). Position 0 is to the left of the first character. If the contents of the text edit buffer are too long to display entirely in the edit region, the text is scrolled to make sure the cursor is visible. Set cur_offset to TE_FAR_RIGHT to place the edit cursor after the last character in the edit buffer.

The parameter 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. The ReadOnly characters are considered to be part of a prompt (or of command characters as in the text editor) so the user cannot change the text of the ReadOnly characters nor move the edit cursor into them.

Flags is a set of binary flags which controls the editor. Each bit specifies optional features of the text editor. Some of these flags are changed automatically during the operation of the editor. The flags are defined in the ETE_FLAGS enumeration and have the following meanings:

TE_WRAPSet this flag for multiline edit regions. Reset it for single-line edit regions: the editor will operate in "compact" mode, in which the editor is only one character high, and where the contents of the editor will scroll left/right when necessary (such a mode is used in request boxes in dialogs). In "compact" mode, the contents of the editor buffer must not contain '\r' characters, else the editor will be fooled. In multiline edit regions, text can wrap around the end of the line to the beginning of the next line. The program editor is an example of a multiline edit region. The Home screen entry line is an example of a single-line edit region.
TE_COLONWhen set, each line of the editor will be preceded with a colon (":"), like in the "Text editor" or the "Program editor". When TE_COLON is reset, there will not be a preceding colon. The program editor uses this flag to mark the beginning of each line of the program.
TE_COMMANDSWhen set, the first character of each line will be regarded as "command character", and it will be displayed before the colon. The "Text editor" application uses this mode to store editor commands (like "P" = "PrintObj" etc.). Note that when this flag is set, the parameter cur_offset must not be zero (it is usually set to 1 in this case).
Note: This flag includes the TE_COLON flag (as needed by the AMS).
TE_MORE_ARROWSSet this flag to display arrows at the left and right ends of a single-line edit region to indicate when more text is to the left or right of the edit region.
TE_MORE_ELLIPSESSet this flag to display ellipses (...) at the left and right ends of a single-line edit region to indicate when more text is to the left or right of the edit region.
Note: This flag includes the TE_MORE_ARROWS flag (as needed by the AMS).
TE_SELECTThis flag is an internal flag. It is set if there currently is a selection in the text editor. It is clear if nothing is selected. Do not set this flag.
TE_CURSORThis flag is an internal flag. It represents the current blinking state of the cursor: it is set if the blinking cursor is currently visible. Do not set this flag.
TE_FIXED_LENGTHThis flag is an internal flag. It is set for text editors opened with TE_openFixed. Do not set this flag.
TE_CHANGEDThis flag is an internal flag. It is a status flag which, if 1, indicates the contents of the edit buffer have changed. Do not set this flag.
TE_FOCUSEDThis flag is an internal flag. It is set if the text editor currently has the focus, i.e. if the cursor is currently in the text editor. See TE_focus and TE_unfocus. Do not set this flag.
TE_AUTO_ANSSet this flag to 1 to cause "ans(1)" to be inserted automatically when the edit buffer is empty and an arithmetic operation is typed.
TE_READ_ONLYWhen set, the editor enters read-only mode. In this mode, the editor displays text and allows arrow keys to navigate through the edit buffer, but it does not allow changing the text, i.e. you can't insert, delete or change any characters.

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, or using the default event loop EV_eventLoop) and to pass them to TE_handleEvent which will process them. Such an 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