Element class (Surface) | Exontrol Docs

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:

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:

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:

EnsureVisible

GetAutoSize() → {boolean}

The GetAutoSize() method specifies whether the element is automatically resized to fit its content

Since:

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:

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:

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:

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:

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:

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:

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:

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:

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