wTextCtrl

A text control allows text to be displayed and edited.

If the user pressed Enter key inside the control, a wEvent_TextEnter event will be generated. If this event is not processed, the default behavior of text control will be doen. However, for read-only control, wEvent_TextEnter will never be generated.

Appearance:
Superclass:wControl
Styles:
StylesDescription
wTeMultiLineThe text control allows multiple lines.
wTePasswordThe text will be echoed as asterisks.
wTeReadOnlyThe text will not be user-editable.
wTeNoHideSelShow the selection event when it doesn't have focus.
wTeLeftThe text in the control will be left-justified (default).
wTeCentreThe text in the control will be centered.
wTeCenterThe text in the control will be centered.
wTeRightThe text in the control will be right-justified.
wTeDontWrapDon't wrap at all, show horizontal scrollbar instead.
wTeRichUse rich text control, this allows to have more than 64KB of text in the control.
wTeProcessTabWith this style, press TAB key to insert a TAB character instead of switches focus to the next control. Only works with wTeMultiLine.
Events:wCommandEvent
wCommandEventDescription
wEvent_TextWhen the text changes.
wEvent_TextUpdateWhen the control is about to redraw itself.
wEvent_TextMaxlenWhen the user tries to enter more text into the control than the limit.
wEvent_TextEnterWhen pressing Enter key.

wTextLinkEvent

Types

wTabStyle = enum
  wTabStyleSpace, wTabStyleDot, wTabStyleDash, wTabStyleUnderline,
  wTabStyleThickLine, wTabStyleDoubleLine
Indicate the style of tab leader.
wTabAlign = enum
  wTabAlignLeft, wTabAlignCenter, wTabAlignRight, wTabAlignDecimal,
  wTabAlignVertical
Indicate the tab alignment.
wTextTabs {...}{.pure.} = object
  mTabs: seq[LONG]
wTextTabs is an object used to set tabs of paragraph.
wAutoCompleteProvider = proc (self: wTextCtrl): seq[string]
Callback function to provide the custom source for autocomplete

Consts

wTeMultiLine = 0x00000004
wTeReadOnly = 0x00000800
wTePassword = 0x00000020
wTeNoHideSel = 0x00000100
wTeLeft = 0x00000000
wTeCentre = 0x00000001
wTeCenter = 0x00000001
wTeRight = 0x00000002
wTeDontWrap = 1048704
wTeRich = 1152921504606846976'i64
wTeProcessTab = 0x00004000
wAcFile = 1
wAcDir = 2
wAcMru = 4
wAcUrl = 8
wTextAlignLeft = 1
wTextAlignRight = 2
wTextAlignCenter = 3
wTextAlignJustify = 4
wNumberingBullet = 1
wNumberingArabic = 2
wNumberingLowerLetter = 3
wNumberingUpperLetter = 4
wNumberingLowerRoman = 5
wNumberingUpperRoman = 6

Procs

proc isMultiLine(self: wTextCtrl): bool {...}{.inline, raises: [], tags: [].}
Returns true if this is a multi line edit control and false otherwise.
proc isEditable(self: wTextCtrl): bool {...}{.inline, raises: [], tags: [].}
Returns true if the controls contents may be edited by user.
proc isSingleLine(self: wTextCtrl): bool {...}{.inline, raises: [], tags: [].}
Returns true if this is a single line edit control and false otherwise.
proc setModified(self: wTextCtrl; modified: bool) {...}{.inline, raises: [], tags: [].}
Marks the control as being modified by the user or not.
proc discardEdits(self: wTextCtrl) {...}{.inline, raises: [], tags: [].}
Resets the internal modified flag as if the current changes had been saved.
proc markDirty(self: wTextCtrl) {...}{.inline, raises: [], tags: [].}
Mark text as modified (dirty).
proc isModified(self: wTextCtrl): bool {...}{.inline, raises: [], tags: [].}
Returns true if the text has been modified by user.
proc setEditable(self: wTextCtrl; flag: bool) {...}{.inline, raises: [], tags: [].}
Makes the text item editable or read-only.
proc setMargin(self: wTextCtrl; left: int; right: int) {...}{.inline, raises: [], tags: [].}
Set the left and right margins.
proc setMargin(self: wTextCtrl; margin: (int, int)) {...}{.inline, raises: [], tags: [].}
Set the left and right margins.
proc setMargin(self: wTextCtrl; margin: int) {...}{.inline, raises: [], tags: [].}
Set the left and right margins to the same value.
proc getMargin(self: wTextCtrl): tuple[left: int, right: int] {...}{.inline, raises: [],
    tags: [].}
Returns the margins.
proc xyToPosition(self: wTextCtrl; x: int; y: int): int {...}{.inline, raises: [], tags: [].}
Converts the given zero based column and line number to a position.
proc xyToPosition(self: wTextCtrl; pos: wPoint): int {...}{.inline, raises: [], tags: [].}
Converts the given zero based column and line number to a position.
proc getLineCount(self: wTextCtrl): int {...}{.inline, raises: [], tags: [].}
Gets the number of lines in the control.
proc getNumberOfLines(self: wTextCtrl): int {...}{.inline, raises: [], tags: [].}
Returns the number of lines in the text control buffer. The same as getLineCount().
proc getLineLength(self: wTextCtrl; line: int): int {...}{.inline, raises: [], tags: [].}
Gets the length of the specified line, not including any trailing newline character
proc getLastPosition(self: wTextCtrl): int {...}{.raises: [], tags: [].}
Returns the zero based index of the last position in the text control, which is equal to the number of characters in the control.
proc isEmpty(self: wTextCtrl): bool {...}{.inline, raises: [], tags: [].}
Returns true if the control is currently empty.
proc positionToXY(self: wTextCtrl; pos: int): wPoint {...}{.raises: [IndexDefect], tags: [].}
Converts given position to a zero-based column, line number pair.
proc showPosition(self: wTextCtrl; pos: int) {...}{.raises: [], tags: [].}
Makes the line containing the given position visible.
proc getSelection(self: wTextCtrl): Slice[int] {...}{.inline, raises: [], tags: [].}
Gets the current selection range. If result.b < result.a, there was no selection.
proc getInsertionPoint(self: wTextCtrl): int {...}{.inline, raises: [], tags: [].}
Returns the insertion point, or cursor, position.
proc setSelection(self: wTextCtrl; start: int; last: int) {...}{.inline, raises: [], tags: [].}
Selects the text starting at the first position up to (but not including) the character at the last position.
proc setSelection(self: wTextCtrl; range: Slice[int]) {...}{.inline, raises: [], tags: [].}
Selects the text in range (including).
proc selectAll(self: wTextCtrl) {...}{.inline, raises: [], tags: [].}
Selects all text.
proc setInsertionPoint(self: wTextCtrl; pos: int) {...}{.inline, raises: [], tags: [].}
Sets the insertion point at the given position.
proc setInsertionPointEnd(self: wTextCtrl) {...}{.inline, raises: [], tags: [].}
Sets the insertion point at the end of the text control.
proc selectNone(self: wTextCtrl) {...}{.inline, raises: [], tags: [].}
Deselects selected text in the control.
proc getRange(self: wTextCtrl; range: Slice[int]): string {...}{.raises: [IndexDefect],
    tags: [].}
Returns the text in range.
proc getValue(self: wTextCtrl): string {...}{.raises: [IndexDefect], tags: [].}
Gets the contents of the control.
proc copy(self: wTextCtrl) {...}{.inline, raises: [], tags: [].}
Copies the selected text to the clipboard.
proc cut(self: wTextCtrl) {...}{.inline, raises: [], tags: [].}
Copies the selected text to the clipboard and removes it from the control.
proc paste(self: wTextCtrl) {...}{.inline, raises: [], tags: [].}
Pastes text from the clipboard to the text item.
proc undo(self: wTextCtrl) {...}{.inline, raises: [], tags: [].}
If there is an undo facility and the last operation can be undone, undoes the last operation.
proc redo(self: wTextCtrl) {...}{.inline, raises: [], tags: [].}
If there is a redo facility and the last operation can be redone, redoes the last operation.
proc canRedo(self: wTextCtrl): bool {...}{.inline, raises: [], tags: [].}
Returns true if there is a redo facility available and the last operation can be redone.
proc canUndo(self: wTextCtrl): bool {...}{.inline, raises: [], tags: [].}
Returns true if there is an undo facility available and the last operation can be undone.
proc setMaxLength(self: wTextCtrl; length: int) {...}{.raises: [], tags: [].}
This function sets the maximum number of characters the user can enter into the control.
proc setValue(self: wTextCtrl; value: string) {...}{.raises: [], tags: [].}
Sets the new text control value. Note that, unlike most other functions changing the controls values, this function generates a wEvent_Text event. To avoid this you can use changeValue() instead.
proc changeValue(self: wTextCtrl; value: string) {...}{.raises: [], tags: [].}
Sets the new text control value. This functions does not generate the wEvent_Text event.
proc clear(self: wTextCtrl) {...}{.inline, raises: [], tags: [].}
Clears the text in the control.
proc getLineText(self: wTextCtrl; line: int): string {...}{.raises: [], tags: [].}
Returns the contents of a given line in the text control, not including any trailing newline character.
proc writeText(self: wTextCtrl; text: string) {...}{.inline, raises: [], tags: [].}
Writes the text into the text control at the current insertion position.
proc appendText(self: wTextCtrl; text: string) {...}{.raises: [], tags: [].}
Appends the text to the end of the text control.
proc writeRtfText(self: wTextCtrl; text: string) {...}{.inline, raises: [], tags: [].}
Writes the RTF text into the text control at the current insertion position. Only works for rich text control.
proc appendRtfText(self: wTextCtrl; text: string) {...}{.raises: [], tags: [].}
Appends the RTF text to the end of the text control. Only works for rich text control.
proc writeLink(self: wTextCtrl; link: string; alias = "") {...}{.raises: [ValueError], tags: [].}
Writes a link into the text control at the current insertion position. Only works for rich text control. A wEvent_TextLink event will be generated when mouse events occur over link.
proc appendLink(self: wTextCtrl; link: string; alias = "") {...}{.raises: [ValueError],
    tags: [].}
Appends a link to the end of the text control. Only works for rich text control. A wEvent_TextLink event will be generated when mouse events occur over link.
proc writeImage(self: wTextCtrl; image: wImage; scale = 1.0) {...}{.raises: [wNilAccess],
    tags: [RootEffect].}
Writes an image into the text control at the current insertion position. Only works for rich text control.
proc appendImage(self: wTextCtrl; image: wImage; scale = 1.0) {...}{.raises: [wNilAccess],
    tags: [RootEffect].}
Appends an image to the end of the text control. Only works for rich text control.
proc getTextSelection(self: wTextCtrl): string {...}{.raises: [IndexDefect], tags: [].}
Gets the text currently selected in the control or empty string if there is no selection.
proc replace(self: wTextCtrl; range: Slice[int]; value: string) {...}{.inline, raises: [],
    tags: [].}
Replaces the text in range.
proc remove(self: wTextCtrl; range: Slice[int]) {...}{.inline, raises: [], tags: [].}
Removes the text in range.
proc loadFile(self: wTextCtrl; filename: string) {...}{.inline, raises: [IOError],
    tags: [ReadIOEffect].}
Loads and displays the named file, if it exists.
proc saveFile(self: wTextCtrl; filename: string) {...}{.inline,
    raises: [IOError, IndexDefect], tags: [WriteIOEffect].}
Saves the contents of the control in a text file.
proc len(self: wTextCtrl): int {...}{.inline, raises: [], tags: [].}
Returns the number of characters in the control.
proc add(self: wTextCtrl; text: string) {...}{.inline, raises: [], tags: [].}
Appends the text to the end of the text control. The same as appendText()
proc TextTabs(offset: int; style: wTabStyle = wTabStyleSpace;
             align: wTabAlign = wTabAlignLeft): wTextTabs {...}{.raises: [], tags: [].}
Constructor for wTextTabs object used by setStyle. Space unit is twip (1/1440 inche).
proc set(self: var wTextTabs; index: range[0 .. (32 - 1)];
        style: wTabStyle = wTabStyleSpace; align: wTabAlign = wTabAlignLeft) {...}{.
    raises: [], tags: [].}
Sets the style and alignment of specified tab stop.
proc resetStyle(self: wTextCtrl) {...}{.inline, raises: [], tags: [].}
Reset the style to default.
proc setStyle(self: wTextCtrl; align = 0; indent = -1; subIndent = -1; rightIndent = -1;
             spaceBefore = -1; spaceAfter = -1; numbering = -1; lineSpacing = NaN;
             tabs = default(wTextTabs)) {...}{.raises: [], tags: [].}
Sets style of paragraph in the current selection or paragraph inserted at the insertion point. Space unit is twip (1/1440 inche). lineSpacing >= 0 means lines, < 0 means abs(twip).
alignDescription
wTextAlignLeftParagraphs are aligned with the left margin.
wTextAlignRightParagraphs are aligned with the right margin.
wTextAlignCenterParagraphs are centered.
wTextAlignJustifyParagraphs are justified by expanding the blanks alone.
numberingDescription
wNumberingBulletInsert a bullet at the beginning of each selected paragraph.
wNumberingArabicUse Arabic numbers (0, 1, 2, and so on).
wNumberingLowerLetterUse lowercase letters (a, b, c, and so on).
wNumberingUpperLetterUse lowercase Roman letters (i, ii, iii, and so on).
wNumberingLowerRomanUse uppercase letters (A, B, C, and so on).
wNumberingUpperRomanUse uppercase Roman letters (I, II, III, and so on).
proc setFormat(self: wTextCtrl; font: wFont = nil; fgColor: wColor = -1;
              bgColor: wColor = -1) {...}{.raises: [IndexDefect], tags: [].}
Sets the selection and new character format for this text control if wTeRich style is specified. Using nil for font or -1 for color indicate not to change.
proc setDefaultFormat(self: wTextCtrl; font: wFont = nil; fgColor: wColor = -1;
                     bgColor: wColor = -1) {...}{.raises: [IndexDefect], tags: [].}
Sets the default format for this text control if wTeRich style is specified. Using nil for font or -1 for color indicate not to change.
proc zoom(self: wTextCtrl; ratio = 1.0) {...}{.inline, raises: [], tags: [].}
Sets the zoom ratio for this text control. Ratio should be between 1/64 and 64. If ratio is zero or NaN, disable zoom if possible.
proc loadRtf(self: wTextCtrl; rtf: string) {...}{.raises: [], tags: [].}
Loads and displays Rich Text Format (RTF) string. Only works for rich text control.
proc saveRtf(self: wTextCtrl; selectionOnly = false): string {...}{.
    raises: [Defect, IOError, OSError], tags: [ReadIOEffect].}
Saves the all or selected text in Rich Text Format (RTF) string. Only works for rich text control.
proc loadRtfFile(self: wTextCtrl; filename: string) {...}{.raises: [IOError],
    tags: [ReadIOEffect].}
Loads and displays Rich Text Format (RTF) file. Only works for rich text control.
proc saveRtfFile(self: wTextCtrl; filename: string; selectionOnly = false) {...}{.
    raises: [IOError, Defect, OSError], tags: [WriteIOEffect, ReadIOEffect].}
Saves the all or selected text in Rich Text Format (RTF) file. Only works for rich text control.
proc disableAutoComplete(self: wTextCtrl) {...}{.raises: [Exception], tags: [RootEffect].}
Disable the autocompletion.
proc enableAutoComplete(self: wTextCtrl; flags = 5 or 8): bool {...}{.discardable,
    raises: [Exception], tags: [RootEffect].}
Enable the autocompletion and use system predefined sources. flags is a bitwise combination of wAcFile, wAcDir, wAcMru, wAcUrl.
FlagsDescription
wAcFileInclude the file system and directories.
wAcDirInclude the file directories only.
wAcMruInclude the URLs in the user's Recently Used list.
wAcUrlInclude the URLs in the user's History list.
proc enableAutoComplete(self: wTextCtrl; provider: wAutoCompleteProvider): bool {...}{.
    discardable, raises: [Exception], tags: [RootEffect].}
Enable the autocompletion and use custom source.
proc enableAutoUrlDetect(self: wTextCtrl; enable = true): bool {...}{.discardable,
    raises: [], tags: [].}
Enables or disables automatic detection of hyperlinks by a rich edit control. A wEvent_TextLink event will be generated when mouse events occur over url.
proc init(self: wTextCtrl; parent: wWindow; id = wDefaultID; value: string = "";
         pos = wDefaultPoint; size = wDefaultSize; style: wStyle = wTeLeft) {...}{.raises: [
    wNilAccess, wWindowError, wCursorError, wBrushError, Exception, IndexDefect,
    wFontError], tags: [RootEffect].}
Initializes a text control.
proc TextCtrl(parent: wWindow; id = wDefaultID; value: string = ""; pos = wDefaultPoint;
             size = wDefaultSize; style: wStyle = wTeLeft): wTextCtrl {...}{.inline,
    discardable, raises: [wNilAccess, wWindowError, wCursorError, wBrushError,
                        Exception, IndexDefect, wFontError], tags: [RootEffect].}
Constructor.
proc init(self: wTextCtrl; hWnd: HWND) {...}{.raises: [wError, wWindowError, wCursorError,
    IndexDefect, wFontError, Exception], tags: [RootEffect].}
Initializes a text control by subclassing a system handle. Used internally.
proc TextCtrl(hWnd: HWND): wTextCtrl {...}{.inline, discardable, raises: [wError,
    wWindowError, wCursorError, IndexDefect, wFontError, Exception],
                                   tags: [RootEffect].}
Constructor.

Methods

method setFont(self: wTextCtrl; font: wFont) {...}{.
    raises: [wNilAccess, Exception, IndexDefect], tags: [RootEffect].}
Sets the font for this text control.
method getBestSize(self: wTextCtrl): wSize {...}{.raises: [], tags: [].}
Returns the best acceptable minimal size for the control.
method getDefaultSize(self: wTextCtrl): wSize {...}{.raises: [], tags: [].}
Returns the default size for the control.
method setBackgroundColor(self: wTextCtrl; color: wColor) {...}{.raises: [Exception],
    tags: [RootEffect].}
Sets the background color of the control.
method release(self: wTextCtrl) {...}{.raises: [Exception], tags: [RootEffect].}
Release all the resources during destroying. Used internally.

Iterators

iterator lines(self: wTextCtrl): string {...}{.raises: [], tags: [].}
Iterates over each line in the control.