win.inputWindow - WIN

Class inputWindow
Inherits from window.

The inputWindow class provides a single line input control with a height of 1. Selection editing and clipboard operations are supported, cut (Ctrl+X), copy (Ctrl+C), paste (Ctrl+V), system paste (Ctrl+ALT+V) and (Shift+Click) select. Its colors are initialized from the theme but may be customized after creation. An input_change event is sent to the parent with a parameter of this input window object when its contents change (once, not at every character). Input controls automatically display the keyboard overlay on monitors.

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


Properties

input__banner string Stores banner text.
input__colors table Color table.
input__colors.text number Text color.
input__colors.back number Blurred background color.
input__colors.focus number Focused background color.
input__colors.error number Error state background color.
input__colors.banner number Banner text color.
input__end number Selection end position.
input__error boolean Error state flag.
input__hOrg number Horizontal scroll position.
input__mask_char string Stores mask character.
input__maxLen number Stores maximum character length.
input__old_text string Used to test for changes.
input__start number Selection start position.

Methods

See also API Reference, WIN.

win.inputWindow:constructor

input inputWindow:constructor (parent, id, x, y, width, text, banner)

Constructs and returns the instantiated input window.

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

Returns
input inputWindow The instantiated input window.

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


top


win.inputWindow:copy

inputWindow:copy ()

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

Parameters
none


Returns
none


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


top


win.inputWindow:cut

inputWindow: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 inputWindow:copy, inputWindow:paste, window:set_clipboard.


top


win.inputWindow:draw

inputWindow:draw (gdi, bounds)

Draws the input 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.inputWindow:get_banner

banner inputWindow:get_banner ()

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

Parameters
none


Returns
banner string The banner text.

Remarks
See inputWindow:set_banner.


top


win.inputWindow:get_error

state inputWindow: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 inputWindow:set_error.


top


win.inputWindow:get_mask_char

char inputWindow:get_mask_char ()

Returns the input control's mask character.

Parameters
none


Returns
char string The mask character. "" if none set.

Remarks
See inputWindow:set_mask_char.


top


win.inputWindow:get_max_len

len inputWindow:get_max_len ()

Returns the maximum length of input accepted from the user.

Parameters
none


Returns
len
number Maximum character length. Zero if no limit.

Remarks
See inputWindow:set_max_len.


top


win.inputWindow:get_sel

start, end inputWindow:get_sel (normalize)

Returns the current selection range.

Parameters
normalize boolean If true the returned values are ensured start before end, 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.

See inputWindow:set_sel.


top


win.inputWindow:get_selection

text inputWindow:get_selection ()

Returns a string of the currently selected text.

Parameters
none


Returns
text
string The currently selected text. "" if no selection.

Remarks


top


win.inputWindow:on_blur

result inputWindow:on_blur (focused)

Hides the cursor, sets appropriate background colour and sends "input_change" event to parent if the text has changed.

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

Returns
result boolean Always false.

Remarks
See window:on_blur.


top


win.inputWindow:on_char

result inputWindow: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.inputWindow:on_clipboard

result inputWindow: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.inputWindow:on_focus

result inputWindow:on_focus (blurred)

Sets the appropriate background color and 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.inputWindow:on_key

result inputWindow: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.inputWindow:on_left_click

result inputWindow: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.inputWindow:on_left_drag

result inputWindow: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.inputWindow:on_move

result inputWindow:on_move ()

Moves the cursor if necessary.

Parameters
none


Returns
result boolean Always false.

Remarks
See window:on_move.


top


win.inputWindow:on_touch

result inputWindow: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.inputWindow:paste

inputWindow: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 inputWindow:cut, inputWindow:copy, window:get_clipboard.


top


win.inputWindow:replace_sel

inputWindow: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 inputWindow:set_sel.


top


win.inputWindow:set_banner

inputWindow:set_banner (banner)

Sets the input control's banner text.

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

Returns
none


Remarks
Invalidates the window.

See inputWindow:get_banner.


top


win.inputWindow:set_colors

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

Sets the colors for the input 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.inputWindow:set_error

inputWindow:set_error (state)

Sets whether the input control should display an error state.

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

Returns
none


Remarks
Invalidation is handled.

See inputWindow:get_error.


top


win.inputWindow:set_mask_char

inputWindow:set_mask_char (char)

Sets the input control's mask character, which is display instead of the literal input (such as for passwords). Only the first character is used.

Parameters
char string/nil Mask character, nil or "" for none.

Returns
none


Remarks
If no mask character is set the literal input is displayed.

Invalidates the window.

See inputWindow:get_mask_char.


top


win.inputWindow:set_max_len

inputWindow:set_max_len (len)

Sets the maximum length of input accepted from the user.

Parameters
len
number Maximum character length, less than 1 or nil for no limit.

Returns
none


Remarks
See inputWindow:get_max_len.


top


win.inputWindow:set_sel

inputWindow:set_sel (sel_start, sel_end, auto_scroll)

Sets the input control's selection range.

Parameters
sel_start number The selection start character.
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.

Invalidation is handled.

See inputWindow:get_sel.


top


win.inputWindow:set_text

inputWindow:set_text (text)

Calls the base implementation to set the window's text value and adjusts the selection if needed.

Parameters
text string The text to replace the control's entire contents.

Returns
none


Remarks
Invalidation is handled.

See window:set_text.


top


See also API Reference, WIN.