PERGOLA LOGO

pergola.Input

System events: YES.

User events and functions: YES.

This class replaces and extends the valueInputBox class of previous versions. It now takes keyboard input. It also implements a flexible mechanism allowing the callback function to be invoked as a method of this owner object, or of this.

Examples: Input; Mapping Window (status bar fields); Datagrid (columns using different types of input).

Listed: class properties/methods; prototype properties and methods; instance properties. Prototype properties and methods inherited by the Class superclass are not listed.

class

None

prototype

PROPERTIES

parent

pergola.user.

type

String – it can be one of "string" "number" "date" "boolean". In practice only "number" and "date" are processed to invoke the appropriate formatting methods (format_number() or format_date()) if this format is true. Those methods use the JavaScript Intl built-in object, where available.

hasButtons

false – boolean; determines whether this should have inc and dec buttons; if true this is a spinner control.

realTime

false – boolean; if this hasButtons, determines whether the value should be applied in real time, or upon button release. You shouldn't use real time if the input has formatting options.

format

false – boolean; if true, the text node of this element is formatted with the method relative to this type. This type and the value of this value are not changed.

locale

String; the value of pergola.locale.

allowEmpty

true – boolean; allows ending input with empty string. If false, the previous value is restored.

empty

false – boolean. If true, input activation empties the field.

cursor

true – boolean; determines the use of the input cursor.

keypressCallback

pergola.Key.keypress class method – you can override with one of the filtering methods provided by the Key class, or with your own keypress callback. Learn more in the SVG magazine Keyboard Class article.

width

Defined in pergola.presentationAttributes – number (user space units).

height

Defined in pergola.presentationAttributes – number (user space units).

fill

Defined in pergola.presentationAttributes – string.

stroke

Defined in pergola.presentationAttributes – string.

strokeInside

true – boolean; the x and y attributes of this rect are set to 0.5 and therefore the left and top borders are not clipped by this container (svg). If this property is overridden, the x and y attributes of this rect are set to -0.5, and this can be sought in a lineup of input boxes (like a datagrid for example) to prevent double strokes.

"font-family"

0 – number (user space units). Unless overridden, the "font-family" attribute is not set and is inherited from the parent container, or the document. This allows to save some valuable DOM populating time when dealing with a great number of input instances in a read/write datagrid, for example.

"font-size"

0 – number (user space units). Overrides the value inherited by pergola.Class superclass. Unless overridden, the "font-size" attribute is not set and is inherited from the parent container, or the document. This allows to save some valuable DOM populating time when dealing with a great number of input instances in a read/write datagrid, for example.

fontSize

Numeric value of this "font-size". When this "font-size" is not specified, the value of this property is derived from this owner's "font-size" or this.constructor.superClass["font-size"], and is used to compute InputCursor size and position.

tX

5 – number (user space units); the value of this element x attribute.

tY

0 – number (user space units); the value of this element y attribute.

METHODS

setValue()

Checks if this value length exceeds this inc.maxLength; updates this element data; sets input cursor position; if this realTime is true, invokes this fn as a method of this owner. You don't normally need to invoke this method explicitly.

increment()

Callback for this inc.button timer. You don't normally need to invoke this method explicitly.

decrement()

Callback for this dec.button timer. You don't normally need to invoke this method explicitly.

reset()

Resets this value to this baseValue; updates this element data. You don't normally need to invoke this method explicitly.

overflow()

Checks overflow on input end. You don't normally need to invoke this method explicitly.

format_number()

If this type is "number" and this format is true, the text node of this element is formatted using the JavaScript Intl built-in object. This type and the value of this value are not changed.

format_date()

If this type is "date" and this format is true, formats this element data using the JavaScript Intl built-in object. This type and the value of this value are not changed.

endInput()

Manages end of input; invokes this fn as a method of this owner; restores undo (register) for active window. You don't normally need to invoke this method explicitly.

handleEvent(evt)

build(object)

this inherits the properties specified in object. Prototype properties specified in object are overridden. Creates elements. Returns this.

instance

name

String. If not passed to the constructor, gets a generated XML name (Class).

id

String. The return value of this name.toXML(). This container ID. Used as prefix where other elements' IDs are attributed.

owner

If specified, designates the owner object. Note that for instances of this class, if not specified, this owner resolves to this.

container

<svg> element.

rect

<rect> element.

element

<text> element.

inc

If this hasButtons, new pergola.UpDownButton instance.

dec

If this hasButtons, new pergola.UpDownButton instance.

value

String or number. The initial value.

baseValue

String or number. Backup of this value.

target

Object. The target object controlled by this.

propName

String. The name of a property of this target to which this value is applied.

inputCursor

Assigned dynamically by pergola.Key (instantiated in handleEvent) unless cursor is specifically set to false in the initialization object. This means that the input cursor is assigned by default, and for the odd case where you don't need it you must specify

cursor : false
in the initialization object.

caption

If specified, an object defining the required textNode string property, optional x, y number (user space units) properties, and optional position string property. These are pergola.Caption properties. This property is reassigned during processing, and references a new pergola.Caption instance.

appendix

If specified, object defining the required textNode string property, and the optional x, and y number (user space units) properties. New pergola.Caption instance positioned to the right of the input box (for showing unit types for example). The pergola.Caption position instance property is then set to "right" and cannot be overridden.

max

If specified, a number representing the upper threshold for numeric values.

min

If specified, number representing the lower threshold for numeric values.

maxLength

If specified, number representing the maximum string length allowed for this value.

printShortcut

This boolean is set to false if this keypressCallback references one of the methods pergola.Key.keypressPos, pergola.Key.keypressPosInt, pergola.Key.keypressHex; it's only intent is to provide a workaround for Opera using the - and + keys to zoom the page, by preventing the browser's default while not emitting those characters on keydown when using the keypress filtering methods above. This property will be removed in due time. Learn more in the SVG magazine Keyboard Class article.

options

If specified, an object as specified by Intl.NumberFormat options (see Mozilla's Intl.NumberFormat for a more friendly language) for formatting fields of type "number", or Intl.DateTimeFormat options (see Mozilla's Intl.DateTimeFormat for a more friendly language) for formatting fields of type "date".

fn

String specifying a method name. Note that for this class (exception), fn must be a string specifying the name of a method; this allows it to be invoked as a method of this owner, if owner is specified, or of this.

callback

If specified, it is a function or an object specifying keydown and/or keypress and/or keyup function properties, for the purpose of overriding any or all the default pergola.Key class methods.