# txtctl

> [HTML Version](txtctl.htm)

_Updated April 2022_

This is a structure containing various extended parameters and options. If omitted, suitable defaults will be supplied, although that will severely limit the capabilities of the tree control. For those parameters which are essentially Boolean options, 0=false and 1=true. Most of the fields in _txtctl_ are input-only, but a few, such as SAVEOFFSET are updated as well, and some are output-only; these are indicated with "\[in/out\]" or "\[out\]" in the following table, which lists the structure members alphabetically for easy reference. To use the _txtctl_ structure in your program, include the [xtext.sdf](https://bitbucket.org/microsabio/soslib/src/master/907016/xtext.sdf) and [xtext.def](https://bitbucket.org/microsabio/soslib/src/master/907016/xtext.def) files and then map an instance of the structure for each XText in the program, e.g.:

MAP1 TXC, TXTCTL                \! define instance of TXTCTL structure named TXC

...

TXC.DOCFFMT'SRC = TXFF\_TEXT

TXC.CTLNO = -1

etc.



Or include the [xtext.map](https://bitbucket.org/microsabio/soslib/src/master/907016/xtext.map) file which includes actual map statements for _txtctl_, rather than a structure definition; in that case, members would be assigned as follows:

TXC'DOCFFMT'SRC = TXFF\_TEXT

TXC'CTLNO = -1

etc.



Note that the first method (declaring an instance of the defined structure _txtctl_ and using the structure dot member notation) has the advantage of making it easy to define and maintain separate copies of the structure for multiple XTEXTs.

By convention in this document, we refer to the members of the _txtctl_ structure using structure.member notation, as if you had declared an instance of the structure _txtctl_ named TXC, as in the example above.

| **Member** | **Type** | **I/O** | **Description** |
|------|------|------|------|
| BCOLOR | B,4 | in | Background (window) color. See [FCOLOR](txc_fcolor.md). |
| BPROTCLR | B,4 | in | Background protected color. See [PROTROWS](txc_protrows.md). |
| CTLID | B,2 | out | Control ID (overall A-Shell AUI control list). |
| [CTLNO](txtctl2.md#txc.ctlno) | B,1 | in/out | Specifies control to use.  |
| DELCTLID | B,4 | in | ID of control to delete on entrance (life sign). This functions exactly like the analogous [XTR.DELCTLID](xtr_delctlid.md) parameter in XTREE, which see for important notes. |
| [DOCFMT'DST](txc_docfmt-dst.md) | B,2 | in | Format of output ([dst](dstxtext.md)). |
| [DOCFMT'SRC](txc_docfmt-src.md) | B,2 | in | Format of input ([src](srcxtext.md)).  |
| [FCOLOR](txc_fcolor.md) | B,4 | in | Foreground (text) color. |
| [FLAGMASK](txc_flagmask.md) | B,2 | in | 1's indicate which flags to update |
| FLAGS# | B,4 | in | Various low-level flags; see TXF#\_xxx in [ASHINC:XTEXT.DEF](https://bitbucket.org/microsabio/soslib/src/master/907016/xtext.def). |
| [FMAPAPP](txtctl2.md#txc.fmapapp) | B,4 | in | 1's enable FKEY to be send to app (exitcode). |
| [FMAPCTL](txc_fmapctl.md) | B,4 | in | 1's enable FKEY to be sent to control. |
| FONTATTR | B,4 | in | Expresses font attributes in the same way as does [fontattr in AUI\_CONTROL](fontattr.md). |
| [FONTFACE](txtctl2.md#txc.fontface) | S,32 | in | Font typeface.  |
| [FONTSIZE](txtctl2.md#txc.fontsize) | B,2 | in | Font point size. |
| [FPROTCLR](txtctl2.md#txc.fprotclr) | B,4 | in | Foreground protected text color. |
| HFLAGMASK | B,2 | in | Bitmap controlling interpretation of the TXC.flags# fields; ; same concept as for _TXC.flagmask_. |
| HFLAGS# | B,4 | in | HTML flags. See TXFH1\_xxx and TXFH2\_xxx in [ASHINC:XTEXT.DEF](https://bitbucket.org/microsabio/soslib/src/master/907016/xtext.def) for bit flag definitions. Note that most options require that the source document format as well as the destination (see [TXC.DOCFMT'SRC](txc_docfmt-src.md) and [TXC.DOCFMT'DST](txc_docfmt-dst.md)) have the TXFF\_HTML flag set —i.e. they may not work when converting from one document type to another. Also, see the Comments under [TXC.DOCFMT'DST](txc_docfmt-dst.md) for important notes relating to the TXF\_PRINTFIEW and TXF\_FITVIEW flags. |
| [IDNAME](txc_idname.md) | S,40 | in | ctlname or parentname>ctlname |
| [KBDSTR](txtctl2.md#txc.kbdstr) | S,11 | in | Click code. |
| [MAXBYTES](txc_maxbytes.md) | B,2 | in | Maximum bytes allowed (0 = unlimited). |
| MAXROWS | B,2 | in | Optional row count limit. If specified, a warning dialog will display when the limit is exceeded (as soon as it happens, periodically, and on exit). Text of dialog can be customized via SBRMSG.xxx 023,002 and 023,003. |
| MENUMASK1,<br>MENUMASK2 | B,4 | in | TXC.menumask1 and TXC.menumask2 allow individual items and groups of menus to be removed when the TXF\_MENU and TXF\_POPUP flags are used. See TXMF1\_xxx and TXMF2\_xxx in [ASHINC:XTEXT.DEF](https://bitbucket.org/microsabio/soslib/src/master/907016/xtext.def) for the bit flag definitions. |
| MGNBOTTOM\* | B,2 | in | Bottom margin (twips). Mainly of interest in TXF\_PRINTVIEW mode. |
| MGNFOOTER\* | B,2 | in | Footer margin (twips). Mainly of interest in TXF\_PRINTVIEW mode. |
| MGNHEADER\* | B,2 | in | Header margin (twips). Mainly of interest in TXF\_PRINTVIEW mode. |
| MGNLEFT\* | B,2 | in | Left margin (twips). Mainly of interest in TXF\_PRINTVIEW mode. |
| MGNRIGHT\* | B,2 | in | Right margin (twips). Mainly of interest in TXF\_PRINTVIEW mode. |
| MGNTOP\* | B,2 | in | Top margin (twips). Mainly of interest in TXF\_PRINTVIEW mode. |
| MODIFIED\* | B,1 | out | Non-zero if text buffer modified. |
| ORIENT | B,2 | in | Orientation (0=dflt, 1=port, 2=land). Mainly of interest in TXF\_PRINTVIEW mode. |
| [OUTBYTES](txc_outbytes.md) | B,4 | out | Number of bytes output. |
| [OUTINES](txtctl2.md#txc.outlines) | B,4 | out | Number of lines output (or to be output).  |
| OVERFLOW | B,1 | out | Non-zero if text too big for _dst_ param. |
| PAPERSIZE | B,2 | in | Paper size (see DMPAPER\_xxx). Mainly of interest in TXF\_PRINTVIEW mode. |
| PARENTID | B,2 | in | ID of parent of control (e.g. a dialog): 0 for a normal child control on the main window. |
| [PROTROWS](txc_protrows.md) | B,4 | in | Rows to protect (-1 = all, -2 all but last). |
| [SAVEOFFSET](txc_saveoffset.md) | B,4 | in/out | Position in buffer to start next save (or -1 to restart a previously incomplete save operation from the beginning). |
| [SFLAGS](txc_sflags.md) | B,2 | in | Search flags |
| SRCHKEY | S,30 | in | String to search for |
| TIMEOUT | B,4 | in | Milliseconds until timeout. The timer gets reset on keystrokes and on mouse activity within the control. If the timer expires, XTEXT will return EXITCODE=11 (like INFLD and XTREE) and any editing changes will be saved. |
| [TOOLBARMASK](txc_toolbarmask.md) | B,4 | in | 1's remove object from toolbar (see TXTB\_xxx). |
| [WRAPWIDTH](txc_wrapwidth.md) | B,2 | in | Width in characters for word wrap.  |
| XCOL | B,2 | in/out | Cursor column on exit and optionally on entrance (base 1). See [TXF\_POSCUR](xtext-flags.md#txf_poscur).  |
| XCUROFFSET | B,4 | in/out | Absolute cursor position on exit and optionally on entrance. (base 0) |
| XROW | B,4 | in/out | Cursor row on exit and optionally on entrance (base 1). See [TXF\_POSCUR](xtext-flags.md#txf_poscur).  |
|  |  |  | **Definition file: **[xtext.sdf](https://bitbucket.org/microsabio/soslib/src/master/907016/xtext.sdf) |




\* **Warning:** setting any of the margin fields has the probably-undesirable side effect of triggering the text-modified flag. This results in the "text has changed - do you want to save" message box appearing even when no changes have been made. You can eliminate the spurious message/question by setting the TXF8\_ESC\_SAVE bit in TXC.flags8, and you could use another exitcode to distinguish abort/discard from save, but it might be preferable to just eliminate the margins.