win.editWindow - WIN

Class editWindow
Inherits from window.

The editWindow class provides a multi-line input control window of the given size. Selection editing, clipboard operations and undo/redo are supported, select all (Ctrl+A), cut (Ctrl+X), copy (Ctrl+C), paste (Ctrl+V), system paste (Ctrl+ALT+V), undo (Ctrl+Z), redo (Ctrl+Y) and (Shift+Click) select. Its colors are initialized from the theme but may be customized after creation. Edit controls automatically display the keyboard overlay on monitors.

The following events are sent to the parent window with a first parameter of this edit window:
selection_change When the selection range changes.
modified When the modified state changes.

To create an editWindow use it's new method:
local edt = win.editWindow:new (parent, id, x, y, width, height, text, banner)


Properties

edit__banner string Stores banner text.
edit__colors table Color table.
edit__colors.back number Blurred background color.
edit__colors.banner number Banner text color.
edit__colors.error number Error state background color.
edit__colors.focus number Focused background color.
edit__colors.text number Text color.
edit__cursor_col number Record of last cursor x position.
edit__data table Holds line data.
edit__end number Selection end position.
edit__error boolean Error state flag.
edit__fire_events boolean Flag to suppress events during creation.
edit__modified boolean Modified flag.
edit__read_only boolean Read only flag.
edit__start number Selection start position.
edit__tab number Tab character width.
edit__undo editUndo Undo action recording object.

Methods

See also API Reference, WIN.

local edit_count_chars

count edit_count_chars (tab_text, long_eol)

Returns the count of characters in the given table of strings or string.

Parameters
tab_text table
Table of strings or string.
long_eol boolean
If true adds 2 characters of a hard line break, otherwise 1.

Returns
count
number
The count of characters.

Remarks
Used internally.


top


local edit_find_eol

pos edit_find_eol (str, from)

Returns the 1 based position of the first found hard break in the given string, or nil if none found.

Parameters
str
string
The string to search.
from
number
The position in the string to start the search.

Returns
pos
number/nil
The position of the hard break or nil.

Remarks
Used internally.


top


local edit_table_to_text

text edit_table_to_text (tab_text, eol)

Convert the table of text components to a single string.

Parameters
tab_text table
Table of text components.
eol string
The hard break line ending to use.

Returns
text string


Remarks
Used internally.


top


local edit_text_to_table

tab edit_text_to_table (text)

Convert a single string into a table of text components.

Parameters
text
string
The string to convert.

Returns
tab
table
The table of text components.

Remarks
Used internally.


top


win.editWindow:can_redo

result editWindow:can_redo ()

Returns if a redo action can be performed.

Parameters
none


Returns
result boolean True if a redo action can be performed, false if not.

Remarks
See editWindow:can_undo.


top


win.editWindow:can_undo

result editWindow:can_undo ()

Returns if an undo action can be performed.

Parameters
none


Returns
result boolean True if an undo action can be performed, false if not.

Remarks
See editWindow:can_redo.


top


win.editWindow:char_from_point

char editWindow:char_from_point (x, y)

Returns the character position at the given coordinates. If the coordinates are beyond the extremes of the contents the character closest to that extreme is returned.

Parameters
x number Scroll relative x position.
y number Scroll relative y position.

Returns
char number The character at the given point.

Remarks
The coordinates are relative to the contents (scroll relative). Character 0 is at 0, 0.


top


win.editWindow:constructor

edit editWindow:constructor (parent, id, x, y, width, height, text, banner)

Constructs and returns the instantiated edit window.

Parameters
parent window Parent window, typically a frame.
id number Numeric id value for edit window.
x number Parent relative x position.
y number Parent relative y position.
width number Edit window width.
height number Edit window height.
text string/nil Initial edit text. Initially empty if omitted or nil.
banner string/nil Banner text, none if omitted or nil.

Returns
edit editWindow The instantiated edit window.

Remarks
The banner text displays in the control when it is empty.


top


win.editWindow:copy

editWindow:copy ()

Copies the currently selected text to the clipboard. Ignored if the control currently has no selection.

Parameters
none


Returns
none


Remarks
See editWindow:cut, editWindow:paste, window:set_clipboard.


top


win.editWindow:cut

editWindow:cut ()

Removes the currently selected text from the control and places it on the clipboard. Ignored if the control currently has no selection.

Parameters
none


Returns
none


Remarks
Invalidation is handled.

See editWindow:copy, editWindow:paste, window:set_clipboard.


top


win.editWindow:draw

editWindow:draw (gdi, bounds)

Draws the edit control in its current state.

Parameters
gdi GDI GDI object to use for drawing.
bounds rect Invalidated area of the window.

Returns
none


Remarks
See window:draw.


top


win.editWindow:get_banner

banner editWindow:get_banner ()

Returns the edit control's banner text. "" is returned if none set.

Parameters
none


Returns
banner string The banner text.

Remarks
See editWindow:set_banner.


top


win.editWindow:get_error

state editWindow:get_error ()

Returns the error state of the control.

Parameters
none


Returns
state boolean True if the control is in error state, false if not.

Remarks
See editWindow:set_error.


top


win.editWindow:get_modified

modified editWindow:get_modified ()

Returns the edit control's modified flag.

Parameters
none


Returns
modified boolean True indicates the control's contents has been modified, false otherwise.

Remarks
See editWindow:set_modified.


top


win.editWindow:get_read_only

read_only editWindow:get_read_only ()

Returns the control's read only state.

Parameters
none


Returns
read_only boolean True indicates the control is in read only mode, false for edit mode.

Remarks
In read only mode the control will not respond to user input that would alter the contents of the control.

See editWindow:set_read_only.


top


win.editWindow:get_sel

start, end editWindow:get_sel (normalize)

Returns the current selection range.

Parameters
normalize boolean If true the returned values are ensured selStart before selEnd, otherwise they are returned as is.

Returns
start number The start selection position.
end number The end selection position.

Remarks
If normalize is true the returned values are assured lowest first (within the control, selection points may be high to low).

The selected range is from, and including, the lowest value up to, but not including the highest value. If the returned values are equal there is currently no selected range, and the returned position is the insertion point.

The selection points are character positions, and are zero based.

End of line markers (hard breaks) in the control are counted as a single character.

See editWindow:set_sel.


top


win.editWindow:get_selected_text

selection editWindow:get_selected_text (eol)

Returns a string of the currently selected text, using the given end of line character/s as the new line encoding. If none is selected an empty string is returned.

Parameters
eol string End of line character/s to use, if nil or omitted "\n" is used.

Returns
selection string The selected range as a single string.

Remarks
See editWindow:get_selection.


top


win.editWindow:get_selection

selection editWindow:get_selection ()

Returns an indexed table of the currently selected text, one string entry for each line. If none is selected a table with a single empty string is returned.

Parameters
none


Returns
selection table Selected range data.

Remarks
See editWindow:get_selected_text.


top


win.editWindow:get_tab_width

chars editWindow:get_tab_width ()

Returns the control's tab character width.

Parameters
none


Returns
chars number Tab width in characters. If zero the tab key has not effect.

Remarks
See editWindow:set_tab_width.


top


win.editWindow:get_text

text editWindow:get_text (eol)

Returns the entire contents of the edit control as a single string using the end of line character/s for new line encoding.

Parameters
eol string End of line character/s. If nil or omitted "\n" is used.

Returns
text string The entire contents of the control as a single string.

Remarks
See editWindow:set_text.


top


win.editWindow:get_text_len

length editWindow:get_text_len (long_eol)

Returns the number of characters in the edit control's contents.

Parameters
long_eol boolean If true 2 characters are counted for each end of line marker, otherwise 1.

Returns
length number The character length of the edit control's contents.

Remarks


top


win.editWindow:line_from_char

line, offset editWindow:line_from_char (char)

Returns the line the given character position is on and the offset of the character from the beginning of the line (both zero based). If char is beyond the text length of the control the last line and offset to the end of that line are returned.

Parameters
char number Character position to find.

Returns
line number Line of the sort character.
offset number Characters offset from the beginning of the line.

Remarks


top


win.editWindow:line_index

char editWindow:line_index (line)

Returns the character's position of the first character of the given line (zero based).

Parameters
line number The line to find the first character of.

Returns
char number Character position of the first character of the line. If the line is greater than the number of lines in the control the length of the text is returned.

Remarks


top


win.editWindow:lines

lines editWindow:lines ()

Returns the number of lines in the edit control.

Parameters
none


Returns
lines number Lines in the edit control's contents.

Remarks
The control always has at least one line.


top


win.editWindow:on_blur

result editWindow:on_blur (focused)

Hides the cursor and sets the appropriate background color.

Parameters
focused window The window gaining focus, it may be nil.

Returns
result boolean Always false.

Remarks
See window:on_blur.


top


win.editWindow:on_char

result editWindow:on_char (char, ascii)

Implements character input.

Parameters
char string Single character string; the character input by user.
ascii number
The character code of the input character.

Returns
result boolean Always true.

Remarks
See window:on_char.


top


win.editWindow:on_clipboard

result editWindow:on_clipboard (text)

Implements the system's paste event, replacing any selected text. Ignored if the text value is an empty string.

Parameters
text string The text data to paste.

Returns
result boolean Always true.

Remarks
Invalidation is handled.

See window:on_clipboard.


top


win.editWindow:on_focus

result editWindow:on_focus (blurred)

Sets the appropriate background colour and sets the cursor position.

Parameters
blurred window The window losing focus, it may be nil.

Returns
result boolean Always false.

Remarks
See window:on_focus.


top


win.editWindow:on_key

result editWindow:on_key (key, ctrl, alt, shift)

Implements editing keys.

Parameters
key number Key code.
ctrl boolean True if control key is depressed.
alt boolean True if alternate key is depressed.
shift boolean True if shift key is depressed.

Returns
result boolean True if a key was actioned, false if not.

Remarks
See window:on_key.


top


win.editWindow:on_left_click

result editWindow:on_left_click (x, y, count)

Calls base implementation and sets selection to click point.

Parameters
x number Window relative x position.
y number Window relative y position.
count number The number of times this same position was repeatedly clicked, with each successive click within the double_click_time.

Returns
result boolean Always true.

Remarks
See window:on_left_click.


top


win.editWindow:on_left_drag

result editWindow:on_left_drag (x, y)

Performs drag selection.

Parameters
x number Window relative x position.
y number Window relative y position.

Returns
result boolean Always true.

Remarks
See window:on_left_drag.


top


win.editWindow:on_move

result editWindow:on_move ()

Moves the cursor if needed.

Parameters
none


Returns
result boolean Always false.

Remarks
See window:on_move.


top


win.editWindow:on_scroll

editWindow:on_scroll ()

Moves the cursor if needed.

Parameters
none


Returns
none


Remarks
See window:on_scroll.


top


win.editWindow:on_touch

result editWindow:on_touch (x, y)

Calls base implementation and sets selection to touch point.

Parameters
x number Window relative x position.
y number Window relative y position.

Returns
result boolean Always true.

Remarks
See window:on_touch.


top


win.editWindow:paste

editWindow:paste ()

Pastes the contents of the clipboard into the control, replacing any selected text. Ignored if the clipboard's data is not type win.CB_TEXT.

Parameters
none


Returns
none


Remarks
Invalidation is handled.

See editWindow:cut, editWindow:copy, window:get_clipboard.


top


win.editWindow:redo

editWindow:redo ()

Performs the next redo action if available.

Parameters
none


Returns
none


Remarks
See editWindow:undo.


top


win.editWindow:replace_sel

editWindow:replace_sel (replace_text, auto_scroll)

Replaces the current selection with the text given. If the current selection is empty the text is inserted at the current position.

Parameters
replace_text string The replacement text. If "" or nil the currently selected range is deleted.
auto_scroll boolean If not false the selection end position is scrolled into the window's view if needed after the operation.

Returns
none


Remarks
Invalidation is handled.

See editWindow:replace_sel_tabled, editWindow:set_sel.


top


win.editWindow:replace_sel_tabled

editWindow:replace_sel_tabled (insert, auto_scroll, undo_action)

Replaces the current selection with the table of text lines given. If the current selection is empty the text is inserted at the current position.

Parameters
insert table Replacement line data. If a table of a single empty string, {""}, any selection is deleted.
auto_scroll boolean If not false the selection end position is scrolled into the window's view if needed after the operation.
undo_action number The type of action for undo recording. If nil the action is not recorded.

Returns
none


Remarks
Invalidation is handled.

Undo actions recognized are:
win.EU_REPLACE     = 0
win.EU_TYPE        = 1
win.EU_DELETE      = 2
win.EU_BACKSPACE   = 3

See editWindow:replace_sel.


top


win.editWindow:set_banner

editWindow:set_banner (banner)

Sets the edit control's banner text.

Parameters
banner string/nil Banner text, nil or "" for none.

Returns
none


Remarks
Invalidates the window.

See editWindow:get_banner.


top


win.editWindow:set_colors

editWindow:set_colors (text, background, focus, banner, error_color)

Sets the colors for the edit window object.

Parameters
text number Text color.
background number Blurred background color.
focus number Focused background color.
banner number Banner text color.
error_color number Error state background color.

Returns
none





Remarks
The window is invalidated.


top


win.editWindow:set_error

editWindow:set_error (state)

Sets whether the edit control should display an error state.

Parameters
state boolean True for error state, false for not.

Returns
none


Remarks
Invalidation is handled.

See editWindow:get_error.


top


win.editWindow:set_modified

editWindow:set_modified (modified, fire_event)

Sets the edit control's modified flag.

Parameters
modified boolean True or nil indicates the control's contents are modified, false for not.
fire_event boolean If false the modified event is not fired.

Returns
none


Remarks
If fire_event is not false and the modified flag is changed a modified event is sent to the parent window with a first parameter of this edit window.

See editWindow:get_modified.


top


win.editWindow:set_read_only

editWindow:set_read_only (read_only)

Sets the control's read only state.

Parameters
read_only boolean True to set the control to read only mode, false for edit mode.

Returns
none


Remarks
In read only mode the control will not respond to user input that would alter the contents of the control.

See editWindow:get_read_only.


top


win.editWindow:set_sel

editWindow:set_sel (sel_start, sel_end, auto_scroll)

Sets the edit control's selection range.

Parameters
sel_start number The selection start character. If -1 the end of the text in the control is used.
sel_end number The selection end character. If nil sel_start is used. If -1 the end of the text in the control is used.
auto_scroll boolean If not false the selection end position is scrolled into the window's view if needed.

Returns
none


Remarks
The selection points are character positions, and are zero based. sel_start and sel_end are trimmed to within range if needed.

The selected range is from, and including, the lowest value up to, but not including the highest value. sel_start may be higher than sel_end. If the sel_start and sel_end values are equal there is no selected range, and this position is the insertion point.

A selection_change event is sent to the parent window with this edit control window as the first parameter.

End of line markers in the control are counted as a single character.

Invalidation is handled.

See editWindow:get_sel.


top


win.editWindow:set_tab_width

editWindow:set_tab_width (chars)

Sets the character width for a tab key input.

Parameters
chars number Tab width in characters. If zero the tab key has not effect.

Returns
none


Remarks
Spaces that align to this character width boundary from the current position are inserted. If set to zero the tab key has not effect. The default is zero.

Note that the frame level object traps tab key input for control navigation. For the edit control to receive them the on_child_key handler for the frame must be overridden and avoid calling the base implementation on a tab key for the control.

See editWindow:get_tab_width.


top


win.editWindow:set_text

editWindow:set_text (text)

Sets the entire contents of the edit control. The selection point is set to the end and the modified flag is set to false.

Parameters
text string Text to replace entire contents of control.

Returns
none


Remarks
A modified and selection_change event are sent to the parent window with a first parameter of this edit window if the respective state changes.

Invalidation is handled.

See editWindow:get_text.


top


win.editWindow:undo

editWindow:undo ()

Performs the next undo action if available.

Parameters
none


Returns
none


Remarks
See editWindow:redo.


top


win.editWindow:update_scroll_size

editWindow:update_scroll_size ()

Sets the edit control's scroll size to fit its contents.

Parameters
none


Returns
none


Remarks


top


See also API Reference, WIN.