Class: Elements

Elements(oSurfaceView)

new Elements(oSurfaceView)

The Elements object holds a collection of Element type (element of the control)
Parameters:
Name Type Description
oSurfaceView SV Indicates an object of exontrol.Surface.SV type

Methods

Add(oElementOpts) → {Element}

The Add() method creates and adds a new element into the control
Parameters:
Name Type Description
oElementOpts Surface.ElementOptions Specifies the options to create the new element as an object of Surface.ElementOptions type
Returns:
Returns the newly created element, as an object of Element type
Type
Element

Clear()

The Clear() method removes all elements of the control and initializes the control's scroll-bars

GetCount() → {number}

The GetCount() method returns the number of elements within the collection
Returns:
Returns the number of elements within the collection
Type
number

Item(id) → {Element}

The Item() method gets the element giving its index, identifier/key or reference
Parameters:
Name Type Description
id any The id parameter could be any of the following:
  • id {number}, indicates a numeric value that defines the index of the element to request
  • id {string}, specifies a string expression that defines the identifier/key/plain-caption of the element to request
  • id {Element}, specifies the object reference to the element to request for
Returns:
Returns null if the element is not found, or an object of Element type, if the elements collection contains the giving id.
Type
Element

Load(value)

The Load() method loads the control's elements from a string representation.
Parameters:
Name Type Description
value string Indicates a string to load elements from. The format of the elements'string representation is (everything between () refers to children, and everything between [] refers to flags):
"element1[flag=value]...[flag=value](sub-element1[flag=value]...[flag=value],...,sub-elementn[flag=value]...[flag=value]),...,elementn[flag=value]...[flag=value](sub-element1[flag=value]...[flag=value],...,sub-elementn[flag=value]...[flag=value])"
The element1, sub-element1 ... elementn defines the caption for each element. The string representation supports the following flags:
  • [key] {string}, specifies the element's key (Key/GetKey()/SetKey(value) methods of exontrol.Surface.Element). For instance, [key=root], specifies that the element's key is "root"
  • [vis]/[hid] {number}, shows or hides the element (Visible/GetVisible()/SetVisible(value) methods of exontrol.Surface.Element). For instance, [hid] or [vis=0], hides the element, while [vis=1] shows the element
  • [dis] {number}, enables or disables the element (Enabled/GetEnabled()/SetEnabled(value) methods of exontrol.Surface.Element). For instance, [dis] or [dis=0], disables the element, while [dis=1] enables the element
  • [nsel] {number}, indicates whether the user can select, resize or move the element (Selectable/GetSelectable()/SetSelectable(value) methods of exontrol.Surface.Element). For instance, [nsel] or [nsel=0], forces the element to be unselectable, while [nsel=1] makes the element selectable
  • [pos] {number}, changes the element's position (0-based) (Position/GetPosition()/SetPosition(value) methods of exontrol.Surface.Element). For instance, [pos=0] indicates that the element should be displayed first
  • [img] {string}, assigns a image/picture to the element (Image/GetImage()/SetImage(value) methods of exontrol.Surface.Element). For instance, [img=logo] assigns the "logo" picture to the element. The image can be added using the exontrol.HTMLPicture.Add() method. You can use the [simg] flag to define the element's image to be displayed on the "sub-items" portion of the control.
  • [imgs] {string}, defines the size of the element's image as a string of "aspect-width,aspect-height" type (without quotes) (ImageSize/GetImageSize()/SetImageSize(value) methods of exontrol.Surface.Element). For instance, [imgs=-32] stretches the element's image into a square of 32x32 size, while [imgs=32,32] fits the element's image into a square of 32x32 size.
  • [imga] {number}, specifies the alignment of the image within the element relative to its caption. The value of "imga" flag can be 0(left), 1(right), 2(top) or 3(bottom). (ImageAlign/GetImageAlign()/SetImageAlign(value) methods of exontrol.Surface.Element). For instance, [imga=3] aligns the element's image at the bottom of its box
  • [client] {string}, specifies the element's client-rectangle as a string of "x,y,width,height" type (without quotes) (Client/GetClient()/SetClient(value) methods of exontrol.Surface.Element). For instance, [client=0,0,128,128] specifies the element's client are to [0,0,128,128]
  • [coll] {string}, indicates a collapsed-element (Expand/GetExpand()/SetExpand(value) methods of exontrol.Surface.Element). For instance, [coll] or [coll=0], collapses the element, while [c=1] expands the element
  • [ft] {number}, specifies the format to display the element's caption. The value of "ft" flag can be a combination of one or more values of exontrol.DrawTextFormatEnum type (FormatText/GetFormatText()/SetFormatText(value) methods of exontrol.Surface.Element). For instance, [ft=32] displays the element's caption on a single line only. Carriage returns and line feeds do not break the line (32 indicates the value of exontrol.DrawTextFormatEnum.exTextSingleLine)
  • [pad] {string}, defines the element's padding (space between the element's content and its border) (Pad/GetPad()/SetPad(value) methods of exontrol.Surface.Element). For instance, [pad=4] defines a 4-pixels padding for all edges
  • [shape] {string}, defines the shape for individual element (Shape/GetShape()/SetShape(value) methods of exontrol.Surface.Element). For instance, [shape=Button] specifies that the element is shown as a "button".
  • [cursor] {string}, defines the mouse-cursor for individual element (Cursor/GetCursor()/SetCursor(value) methods of exontrol.Surface.Element). For instance, [cursor=wait] indicates that the "wait" mouse-cursor is displayed while the cursor hovers the element
  • [auto] {number}, resizes the element to fit its content (AutoSize/GetAutoSize()/SetAutoSize(value) methods of Surface.Element). For instance, [auto] resizes the element to fit its content
  • [nres] {number}, defines a non-resizable element (Resizable/GetResizable()/SetResizable(value) methods of Surface.Element). For instance, [nres] indicates that the user can not resize the element by drag and drop
  • [nmov] {number}, defines a non-movable element (Movable/GetMovable()/SetMovable(value) methods of Surface.Element). For instance, [nmov] indicates that the user can not move the element by drag and drop

OnCreate(oCreateOpts) → {boolean}

The OnCreate() method customizes the options for the newly created element by drag.
Parameters:
Name Type Description
oCreateOpts Surface.ElementOptions Specifies the options to create the new element as an object of Surface.ElementOptions type. The oCreateOpts contains 'client' field, that defines the element's client area as an array of [x,y,width,height] type.
Returns:
Returns false to create the element, or true to prevent creating a new element
Type
boolean

Remove(id)

The Remove() method removes an element from the collection.
Parameters:
Name Type Description
id any The id parameter could be any of the following:
  • id {number}, indicates a numeric value that defines the index of the element to request
  • id {string}, specifies a string expression that defines the identifier/key/plain-caption of the element to request
  • id {Element}, specifies the object reference to the element to request for

RemoveRange(range)

The RemoveRange() method removes multiple-elements at once
Parameters:
Name Type Description
range Surface.Element | Array.<Surface.Element> Indicates an element of Element type, an array [{Element}], or exontrol.Arr.

Save() → {string}

The Save() method saves the control's elements to a string representation.
Returns:
Returns the control's element into a string representation. The format of the elements'string representation is (everything between () refers to children, and everything between [] refers to flags):
"element1[flag=value]...[flag=value](sub-element1[flag=value]...[flag=value],...,sub-elementn[flag=value]...[flag=value]),...,elementn[flag=value]...[flag=value](sub-element1[flag=value]...[flag=value],...,sub-elementn[flag=value]...[flag=value])"
The element1, sub-element1 ... elementn defines the caption for each element. The string representation supports the following flags:
  • [key] {string}, specifies the element's key (Key/GetKey()/SetKey(value) methods of exontrol.Surface.Element). For instance, [key=root], specifies that the element's key is "root"
  • [vis]/[hid] {number}, shows or hides the element (Visible/GetVisible()/SetVisible(value) methods of exontrol.Surface.Element). For instance, [hid] or [vis=0], hides the element, while [vis=1] shows the element
  • [dis] {number}, enables or disables the element (Enabled/GetEnabled()/SetEnabled(value) methods of exontrol.Surface.Element). For instance, [dis] or [dis=0], disables the element, while [dis=1] enables the element
  • [nsel] {number}, indicates whether the user can select, resize or move the element (Selectable/GetSelectable()/SetSelectable(value) methods of exontrol.Surface.Element). For instance, [nsel] or [nsel=0], forces the element to be unselectable, while [nsel=1] makes the element selectable
  • [pos] {number}, changes the element's position (0-based) (Position/GetPosition()/SetPosition(value) methods of exontrol.Surface.Element). For instance, [pos=0] indicates that the element should be displayed first
  • [img] {string}, assigns a image/picture to the element (Image/GetImage()/SetImage(value) methods of exontrol.Surface.Element). For instance, [img=logo] assigns the "logo" picture to the element. The image can be added using the exontrol.HTMLPicture.Add() method. You can use the [simg] flag to define the element's image to be displayed on the "sub-items" portion of the control.
  • [imgs] {string}, defines the size of the element's image as a string of "aspect-width,aspect-height" type (without quotes) (ImageSize/GetImageSize()/SetImageSize(value) methods of exontrol.Surface.Element). For instance, [imgs=-32] stretches the element's image into a square of 32x32 size, while [imgs=32,32] fits the element's image into a square of 32x32 size.
  • [imga] {number}, specifies the alignment of the image within the element relative to its caption. The value of "imga" flag can be 0(left), 1(right), 2(top) or 3(bottom). (ImageAlign/GetImageAlign()/SetImageAlign(value) methods of exontrol.Surface.Element). For instance, [imga=3] aligns the element's image at the bottom of its box
  • [client] {string}, specifies the element's client-rectangle as a string of "x,y,width,height" type (without quotes) (Client/GetClient()/SetClient(value) methods of exontrol.Surface.Element). For instance, [client=0,0,128,128] specifies the element's client are to [0,0,128,128]
  • [coll] {string}, indicates a collapsed-element (Expand/GetExpand()/SetExpand(value) methods of exontrol.Surface.Element). For instance, [coll] or [coll=0], collapses the element, while [c=1] expands the element
  • [ft] {number}, specifies the format to display the element's caption. The value of "ft" flag can be a combination of one or more values of exontrol.DrawTextFormatEnum type (FormatText/GetFormatText()/SetFormatText(value) methods of exontrol.Surface.Element). For instance, [ft=32] displays the element's caption on a single line only. Carriage returns and line feeds do not break the line (32 indicates the value of exontrol.DrawTextFormatEnum.exTextSingleLine)
  • [pad] {string}, defines the element's padding (space between the element's content and its border) (Pad/GetPad()/SetPad(value) methods of exontrol.Surface.Element). For instance, [pad=4] defines a 4-pixels padding for all edges
  • [shape] {string}, defines the shape for individual element (Shape/GetShape()/SetShape(value) methods of exontrol.Surface.Element). For instance, [shape=Button] specifies that the element is shown as a "button".
  • [cursor] {string}, defines the mouse-cursor for individual element (Cursor/GetCursor()/SetCursor(value) methods of exontrol.Surface.Element). For instance, [cursor=wait] indicates that the "wait" mouse-cursor is displayed while the cursor hovers the element
  • [auto] {number}, resizes the element to fit its content (AutoSize/GetAutoSize()/SetAutoSize(value) methods of Surface.Element). For instance, [auto] resizes the element to fit its content
  • [nres] {number}, defines a non-resizable element (Resizable/GetResizable()/SetResizable(value) methods of Surface.Element). For instance, [nres] indicates that the user can not resize the element by drag and drop
  • [nmov] {number}, defines a non-movable element (Movable/GetMovable()/SetMovable(value) methods of Surface.Element). For instance, [nmov] indicates that the user can not move the element by drag and drop
Type
string