Element class (Surface)

Element(oElements, oElementOptsopt)

new Element(oElements, oElementOptsopt)

The Element object holds information(options) about an element within the control.

Every option of the Surface.ElementOptions type has associated a property of the control. For instance, the option:

caption {string}, defines the element's caption
is associated with the property:
Caption {string}, defines the element's caption
which means that the following statements are equivalent:
oElement.Options = {caption: "name"}
oElement.SetOptions({caption: "name"})
oElement.Caption = "name"
oElement.SetCaption("name")
where oElement is an object of Element type
Parameters:
Name Type Attributes Description
oElements Elements Indicates an object of Elements type that's the owner collection of this element
oElementOpts Surface.ElementOptions <optional>
 defines the element's caption or options as an object of Surface.ElementOptions type
Element

Methods

Add(oElementOpts) → {Element}

The Add() method inserts a new child-element
Parameters:
Name Type Description
oElementOpts Surface.ElementOptions Specifies the options to create the new element as an object of Surface.ElementOptions type
Since:
  • 1.1
Returns:
Returns the newly created child-element, as an object of Element type
Type
Element
Example
oSurface.Elements.Add("Parent").Add("Child").Add("Sub-Child")
Add

BringForward() → {number}

The BringForward() method moves the element up one level, so that it is closer to top of the stacking order.
Returns:
Returns the element's previously position
Type
number
BringForward

BringToFront() → {number}

The BringToFront() method moves the element to the top of the stacking order, so that it is in front of other elements.
Returns:
Returns the element's previously position
Type
number
BringToFront

EndUpdateElement(startUpdateElement)

The EndUpdateElement() method adds programmatically updated properties of the element to undo/redo queue. You can use the StartBlockUndoRedo / EndBlockUndoRedo methods to group multiple Undo/Redo operations into a single-block. The AllowUndoRedo property specifies whether the control supports undo/redo operations for objects (elements, links, ...). No entry is added to the Undo/Redo queue if no property is changed for the current element.
Parameters:
Name Type Description
startUpdateElement any Holds the result of a StartUpdateElement() method
Since:
  • 2.0
EndUpdateElement

EnsureVisible()

The EnsureVisible() method expands the parent-elements and scrolls the control's content so the element fits the control's client area
Since:
  • 2.0
EnsureVisible

GetAutoSize() → {boolean}

The GetAutoSize() method specifies whether the element is automatically resized to fit its content
Since:
  • 2.2
Returns:
Returns true if the element is automatically resized to fit its content
Type
boolean
GetAutoSize

GetCaption() → {string}

The GetCaption() method returns the element's caption
Returns:
Returns element's exHTML caption
Type
string
GetCaption

GetClient() → {Array.<number>}

The GetClient() method returns the element's client area
Returns:
Returns element's client area
Type
Array.<number>
GetClient

GetCursor() → {string}

The GetCursor() method defines the mouse cursor for the element itself.
Returns:
Returns the mouse-cursor for the element itself.
Type
string
GetCursor

GetEnabled() → {boolean}

The GetEnabled() method returns whether the element is enabled or disabled
Returns:
Returns true if the element is enabled, or false if the element is disabled
Type
boolean
GetEnabled

GetExpand() → {boolean}

The GetExpand() method specifies whether the element is expanded or collapsed.
Returns:
Returns true if the element is expanded.
Type
boolean
GetExpand

GetFormatText() → {exontrol.DrawTextFormatEnum}

The GetFormatText() method specifies the format to display the element's caption.
Returns:
Returns a value of exontrol.DrawTextFormatEnum type, that defines the format to display the element's caption. The exontrol.DrawTextFormatEnum type support the following flags:
  • exTextAlignTop (0x00), justifies the text to the top of the rectangle
  • exTextAlignLeft (0x00), aligns text to the left
  • exTextAlignCenter (0x01), centers text horizontally in the rectangle
  • exTextAlignRight (0x02), aligns text to the right
  • exTextAlignVCenter (0x04), centers text vertically
  • exTextAlignBottom (0x08), justifies the text to the bottom of the rectangle.
  • exTextAlignMask (0x0F), specifies the mask for text's alignment.
  • exTextWordBreak (0x10), breaks words. Lines are automatically broken between words if a word would extend past the edge of the rectangle specified by the lpRect parameter. A carriage return-line feed sequence also breaks the line. If this is not specified, output is on one line.
  • exTextSingleLine (0x20), displays text on a single line only. Carriage returns and line feeds do not break the line.
  • exTextExpandTabs (0x40), expands tab characters. The default number of characters per tab is eight.
  • exPlainText (0x80), treats the text as plain text.
  • exTextNoClip (0x0100), draws without clipping.
  • exHTMLTextNoColors (0x0200), ignores the and tags.
  • exTextCalcRect (0x0400), determines the width and height of the text.
  • exHTMLTextNoTags (0x0800), ignores all HTML tags.
  • exTextPathEllipsis (0x4000), for displayed text, replaces characters in the middle of the string with ellipses so that the result fits in the specified rectangle. If the string contains backslash (\) characters, exTextPathEllipsis preserves as much as possible of the text after the last backslash.
  • exTextEndEllipsis (0x8000), for displayed text, if the end of a string does not fit in the rectangle, it is truncated and ellipses are added. If a word that is not at the end of the string goes beyond the limits of the rectangle, it is truncated without ellipses.
  • exTextWordEllipsis (0x040000), truncates any word that does not fit in the rectangle and adds ellipses.
Type
exontrol.DrawTextFormatEnum
GetFormatText

GetImage() → {string}

The GetImage() method returns the element's image.
Returns:
Returns the name of the image the current element displays.
Type
string
GetImage

GetImageAlign() → {number}

The GetImageAlign() method specifies the alignment of the element's image relative to its caption.
Returns:
Returns the alignment of the element's image relative to its caption, as explained:
  • 0, the image is on the left of the node's caption (default)
  • 1, the image is on the right of the node's caption
  • 2, the image is on the top of the node's caption
  • 3, the image is on the bottom of the node's caption
Type
number
GetImageAlign

GetImageSize() → {undefined|null|number|Array.<number>}

The GetImageSize() method defines the size of the element's image.
Returns:
Returns the size, range of limits the element's image is displayed as expalined:
  • {undefined}, Indicates that the control's imageSize option is considered, so the element's image is measured according to the control's imageSize option.
  • {null}, Indicates that the node's image is displayed as it is (full-sized).
  • {number}, Specifies that the node's image is displayed into a square of giving size (same width and height). If 0 the node displays no image, if negative the node's image is stretched to giving square, else the node's picture is scaled to fit the giving rectangle.
  • {number[]}, Specifies an array of [aspect-width,aspect-height] type that defines the limits for width or/and height. The aspect-width and aspect-height define the width/height of the node's picture to scale or stretch to.
Type
undefined | null | number | Array.<number>
GetImageSize

GetIndex() → {number}

The GetIndex() method retrieves the element's index.
Returns:
Returns the element's index (0-based)
Type
number
GetIndex

GetKey() → {string}

The GetKey() method returns the element's key.
Returns:
Returns the element's exHTML key it displays
Type
string
GetKey

GetMovable() → {boolean}

The GetMovable() method specifies whether the user can move the element by drag and drop
Since:
  • 2.2
Returns:
Returns true if the user can move the element by drag and drop
Type
boolean
GetMovable

GetOptions() → {Surface.ElementOptions}

The GetOptions() method returns the element's options at once
Returns:
Returns an object of Surface.ElementOptions type
Type
Surface.ElementOptions
GetOptions

GetPad() → {number|Array.<number>|string}

The GetPad() method specifies the space between element's content and its borders.
Returns:
Returns a value that could be:
  • {number} a numeric value, to pad horizontal and vertical size with the same value
  • {(number[]|string)} a "x,y" or [x,y] type to specify the padding on h/v size
Type
number | Array.<number> | string
GetPad

GetParent() → {Element}

The GetParent() method gets the element's parent.
Returns:
Returns the element's parent as an object of Element type
Type
Element
GetParent

GetPosition() → {number}

The GetPosition() method retrieves the element's position.
Returns:
Returns the element's position
Type
number
GetPosition

GetResizable() → {boolean}

The GetResizable() method specifies whether the user can resize the element by drag and drop
Since:
  • 2.2
Returns:
Returns true if the user can resize the element by drag and drop
Type
boolean
GetResizable

GetSelectable() → {boolean}

The GetSelectable() method indicates whether the user can select, move or resize the element
Since:
  • 1.7
Returns:
Returns true if the element is selectable, or false if the element is not selectable
Type
boolean
GetSelectable

GetShape() → {any}

The GetShape() method defines the shape for the element itself.
Returns:
Returns the shape for the element itself.
Type
any
GetShape

GetVisible() → {boolean}

The GetVisible() method returns whether the element is visible or hidden
Returns:
Returns true if the element is visible, or false if the element is not visible
Type
boolean
GetVisible

Remove()

The Remove() method removes the element itself from its collection
Remove

SendBackward() → {number}

The SendBackward() method moves the element down one level, so that it is closer to the bottom of the stacking order.
Returns:
Returns the element's previously position
Type
number
SendBackward

SendToBack() → {number}

The SendToBack() method moves the element to the bottom of the stacking order, so that it is behind the other elements.
Returns:
Returns the element's previously position
Type
number
SendToBack

SetAutoSize(value)

The SetAutoSize() method automatically resizes the element to fit its content
Parameters:
Name Type Description
value boolean Specifies whether the element is resized to to fit its content
Since:
  • 2.2
SetAutoSize

SetCaption(value)

The SetCaption() method changes the element's caption
Parameters:
Name Type Description
value string Specifies a new ex-HTML caption to be assigned to the element
Example
null {null}, indicates no caption
 "caption" {string}, declares a plain-caption
 "&lt;b>text&lt;/b>" {string}, displays the text in bold
 "&lt;img>logo&lt;/img>" {string}, displays the "logo" image. The image can be added using the exontrol.HTMLPicture.Add() method
SetCaption

SetClient(value)

The SetClient() method changes the element's client area
Parameters:
Name Type Description
value Array.<number> Specifies the new element's client area
Example
null {null}, defines an element quivalent with [0,0,32,32]
 [0,0,128,128] {number[]}, defines the element at the center of the control of 128 x 128 pixels size
SetClient

SetCursor(value)

The SetCursor() method changes the mouse cursor for the element itself.
Parameters:
Name Type Description
value any A string expression that defines the mouse cursor for the element itself.
SetCursor

SetEnabled(value)

The SetEnabled() method enables or disables the element
Parameters:
Name Type Description
value boolean Indicates a boolean expression that specifies whether the element is enabled or disabled
Example
false {boolean}, disables the element
 true {boolean}, enables the element
SetEnabled

SetExpand(value)

The SetExpand() method expands or collapses the element.
Parameters:
Name Type Description
value boolean Specifies whether the element are expanded or collapsed
SetExpand

SetFormatText(value)

The SetFormatText() method changes the format to display the element's caption.
Parameters:
Name Type Description
value exontrol.DrawTextFormatEnum Specifies a value of exontrol.DrawTextFormatEnum value that defines the format to show the element's caption. The exontrol.DrawTextFormatEnum type support the following flags:
  • exTextAlignTop (0x00), justifies the text to the top of the rectangle
  • exTextAlignLeft (0x00), aligns text to the left
  • exTextAlignCenter (0x01), centers text horizontally in the rectangle
  • exTextAlignRight (0x02), aligns text to the right
  • exTextAlignVCenter (0x04), centers text vertically
  • exTextAlignBottom (0x08), justifies the text to the bottom of the rectangle.
  • exTextAlignMask (0x0F), specifies the mask for text's alignment.
  • exTextWordBreak (0x10), breaks words. Lines are automatically broken between words if a word would extend past the edge of the rectangle specified by the lpRect parameter. A carriage return-line feed sequence also breaks the line. If this is not specified, output is on one line.
  • exTextSingleLine (0x20), displays text on a single line only. Carriage returns and line feeds do not break the line.
  • exTextExpandTabs (0x40), expands tab characters. The default number of characters per tab is eight.
  • exPlainText (0x80), treats the text as plain text.
  • exTextNoClip (0x0100), draws without clipping.
  • exHTMLTextNoColors (0x0200), ignores the and tags.
  • exTextCalcRect (0x0400), determines the width and height of the text.
  • exHTMLTextNoTags (0x0800), ignores all HTML tags.
  • exTextPathEllipsis (0x4000), for displayed text, replaces characters in the middle of the string with ellipses so that the result fits in the specified rectangle. If the string contains backslash (\) characters, exTextPathEllipsis preserves as much as possible of the text after the last backslash.
  • exTextEndEllipsis (0x8000), for displayed text, if the end of a string does not fit in the rectangle, it is truncated and ellipses are added. If a word that is not at the end of the string goes beyond the limits of the rectangle, it is truncated without ellipses.
  • exTextWordEllipsis (0x040000), truncates any word that does not fit in the rectangle and adds ellipses.
SetFormatText

SetImage(value)

The SetImage() method changes the element's image. The image can be added using the exontrol.HTMLPicture.Add() method
Parameters:
Name Type Description
value string Indicates the name of the image the element displays.
SetImage

SetImageAlign(value)

The SetImageAlign() method changes the alignment of the element's image relative to its caption.
Parameters:
Name Type Description
value number Indicates the alignment of the element's image relative to element's caption as explained:
  • 0, the image is on the left of the node's caption (default)
  • 1, the image is on the right of the node's caption
  • 2, the image is on the top of the node's caption
  • 3, the image is on the bottom of the node's caption
Example
null {null}, the image is on top of the node's cation (default value)
 1 {number}, the image is displayed to the left of the node's caption
SetImageAlign

SetImageSize(value)

The SetImageSize() method changes the size of the element's image.
Parameters:
Name Type Description
value undefined | null | number | Array.<number> Indicates the size of the element's image as explained:
  • {undefined}, Indicates that the control's imageSize option is considered, so the element's image is measured according to the control's imageSize option.
  • {null}, Indicates that the node's image is displayed as it is (full-sized).
  • {number}, Specifies that the node's image is displayed into a square of giving size (same width and height). If 0 the node displays no image, if negative the node's image is stretched to giving square, else the node's picture is scaled to fit the giving rectangle.
  • {number[]}, Specifies an array of [aspect-width,aspect-height] type that defines the limits for width or/and height. The aspect-width and aspect-height define the width/height of the node's picture to scale or stretch to.
Example
null {null}, Indicates that the node's image is displayed as it is (full-sized).
 0 {number}, no image is displayed
 64 {number}, the image is scaled to fit a 64 x 64 rectangle
 -64 {number}, the image is strected to a 64 x 64 rectangle
 [32,64] {array}, scales the image to the largest ratio-rectangle (32 x 64) that fits the client
 [-32,-64] {array}, stretches the image to a 32 x 64 rectangle
SetImageSize

SetKey(value)

The SetKey() method assigns a new key to the element
Parameters:
Name Type Description
value string Specifies a new key to be assigned to the element
Example
"logo" {string}, defines the element with the giving key (logo). You can use the Root.Item("logo") method to request the element giving its key.
SetKey

SetMovable(value)

The SetMovable() method specifies whether the user can move the element by drag and drop
Parameters:
Name Type Description
value boolean Specifies whether the user can move the element by drag and drop
Since:
  • 2.2
SetMovable

SetOptions(oOpts)

The SetOptions() method changes the element's options (visibility, caption, ...) at once
Parameters:
Name Type Description
oOpts Surface.ElementOptions Specifies an object of Surface.ElementOptions type that holds information about the element, such as caption, image and so on. If the oOpts parameter is not-of object type it indicates the element's caption instead
SetOptions

SetPad(value)

The SetPad() method changes the element's padding or the space between element's content and its borders.
Parameters:
Name Type Description
value number | Array.<number> | string Specifies a value that could be:
  • {number} a numeric value, to pad horizontal and vertical size with the same value
  • {(number[]|string)} a "x,y" or [x,y] type to specify the padding on h/v size
Example
null {null}, indicates that the default-padding field is used ([4,4])
  0 {number}, indicates no padding
  "8,4" {string}, increases the node's width with 2 * 8-pixels and node's height with 2 * 4-pixels
  [8,4] {array}, increases the node's width with 2 * 8-pixels and node's height with 2 * 4-pixels
SetPad

SetParent(value) → {boolean}

The SetParent() method sets the element's parent
Parameters:
Name Type Description
value any The value parameter can be any of the following:
  • value {number}, indicates a numeric value that defines the index of the parent's element
  • value {string}, specifies a string expression that defines the identifier/key/plain-caption of the parent's element
  • value {Element}, specifies the object reference to the parent's element
Returns:
Returns true, if the element's parent has been changed
Type
boolean
Example
0 {number}, indicates that the element with the index 0 is the parent of the current element
 "key" {string}, specifies that the parent of the current element is the element with the giving key
SetParent

SetPosition(value)

The SetPosition() method changes the element's position.
Parameters:
Name Type Description
value number Specifies the element's new position
SetPosition

SetResizable(value)

The SetResizable() method specifies whether the user can resize the element by drag and drop
Parameters:
Name Type Description
value boolean Specifies whether the user can resize the element by drag and drop
Since:
  • 2.2
SetResizable

SetSelectable(value)

The SetSelectable() method makes the element selectable or not selectable
Parameters:
Name Type Description
value boolean Indicates a boolean expression that specifies whether the element is selectable or not selectable
Since:
  • 1.7
Example
false {boolean}, the user can't select, resize or move the element
 true {boolean}, the user can select, resize or move the element
SetSelectable

SetShape(value)

The SetShape() method changes the shape for the element itself.
Parameters:
Name Type Description
value any The value could be any of the following:
  • {null}, no custom-shape is applied
  • {string}, defines a CSS color to fill the object with (applied only for known colors), else it indicates the name of the custom-shape to apply on the object
  • {exontrol.Def.Shape}, indicates a reference to a shape of exontrol.Def.Shape type
  • {object}, holds a reference to an object of {normal,hover,click,disabled} type, where normal, hover, click and disabled are objects of exontrol.Def.Shape type.
SetShape

SetVisible(value)

The SetVisible() method shows or hides the element
Parameters:
Name Type Description
value boolean Indicates a boolean expression that specifies whether the element is visible or hidden
Example
false {boolean}, hides the element
 true {boolean}, shows the element
SetVisible

StartUpdateElement() → {object}

The StartUpdateElement() method starts changing properties of the element, so EndUpdateElement method adds programmatically updated properties to undo/redo queue. You can use the StartBlockUndoRedo / EndBlockUndoRedo methods to group multiple Undo/Redo operations into a single-block. The AllowUndoRedo property specifies whether the control supports undo/redo operations for objects (elements, links, ...). No entry is added to the Undo/Redo queue if no property is changed for the current element.
Since:
  • 2.0
Returns:
Returns undefined (no undo/redo is allowed) or an object to be passed to EndUpdateElement method.
Type
object
StartUpdateElement

ToggleExpand()

The ToggleExpand() method toggles the element's expand state. For instance, if the element is expanded, the ToggleExpand() method collapses the element.
ToggleExpand

UpdateElement(callback, thisArg)

The UpdateElement() method records the changes of element's properties into control's Undo/Redo queue. The UpdateElement() method calls StartUpdateElement / EndUpdateElement methods.
Parameters:
Name Type Description
callback callback Specifies a function of callback() type
thisArg any Indicates the value of "this" keyword during the callback, or the object itself if missing
UpdateElement