 |
TE_open |
Function (ROM Call 0xAC) |
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