behavior: masked-edit

Single line input element behavior with mask.

Example, telephone number input element:

<input type="masked" mask="( ### ) ### - ####" />

that have this behavior applied by default (see master_style_sheet):

• <input type=“mask” /> - inline single line
• <widget type=“mask”></widget>

this behavior knows about:

• value=“text” - initial value of the input element.
• mask=“text” - input mask string. Characters with the special meaning in the string:
  • # - decimal digit position.
  • 0 - decimal digit position, the whole group is represented as a number with leading zeroes.
  • _ - alphabetic character or digit position.
  • @ - alphabetic only character position.
• placeholder=“character” - placeholder character used to mark input position in the editor. By default it is U2022 "Bullet" character.

Together with the standard set of events (mouse, keyboard, focus) behavior: button generates:

• EDIT_VALUE_CHANGED event - value of the element was changed due to user actions. Posted (asynchronous) event.
• EDIT_VALUE_CHANGING event - sent when value of the element is about to change. Synchronous event.

Value of element with this behavior assigned is either one:

• type json::value::V_STRING (string in TIScript).
• type json::value::V_ARRAY (array in TIScript) when mask is set by the mask() method.

• LEFT, RIGHT - previous/next field.
• HOME, END - min/max values of numeric fields;
• UP,DOWN - previous/next item in enumerable field;
• BACKSPACE - clears content of current field;
• DELETE - clears content of all fields;
• CTRL+A
• CTRL+C
• CTRL+V

Edit supports following xcall() methods (see dom::element::xcall() function):

• xcall(“copy”, false): bool - returns true - if copy is available and false if not;
• xcall(“copy”, true) - executes copy operation - copy selection into the clipboard;
• xcall(“paste”, false): bool - returns true - if paste is available and false if not;
• xcall(“paste”, true) - executes paste operation - pastes content of the the clipboard;
• xcall(“selectAll”): bool - returns true if current selection spans the whole document and false otherwise.
• xcall(“selectAll”, true) - selects whole content of the editor;
• xcall(“mask”, maskDefinition) - sets extended mask. mask definition here is an array of the following:
  • ”…” - literal string, defines non-editable text;
  • [“item1”,”item2”, …] - vector of strings, editable enumeration field. By using UP/DOWN keys user is able to select needed value. On character key the behavior will try to find item that starts from that character.
  • numeric field definition is an object(map) having following fields:
    • type=“integer” - type of the editor for the field;
    • width=n - integer, number of characters in the field;
    • min=n - integer, optional, min value of the field;
    • max=n - integer, optional, max value of the field;
    • leading-zero=true - boolean, optional, true will prepend the value by zeroes;
  • textual field definition is an object(map) having following fields:
    • type=“text” - type of the editor for the field;
    • width=n - integer, number of characters in the field;
    • filter=… - optional, string, defines characters allowed in the field, e.g. filter “0~9” will allow only numeric characters in the field.

Here is an example of defining extended mask in Sciter:

  var edit = self.select("input#ip-address");
  const ipmask = [
            { type:"integer", width:3, min:0, max:255, #leading-zero:true }, ".",
            { type:"integer", width:3, min:0, max:255, #leading-zero:true }, ".",
            { type:"integer", width:3, min:0, max:255, #leading-zero:true }, ".",
            { type:"integer", width:3, min:0, max:255, #leading-zero:true } ];
  edit.mask(ipmask);