ComboBox class | Exontrol Docs

new ComboBox(client, oOptionsopt)

The ExComboBox/JS tool allows you to display a drop-down panel (Bezier, Calendar, Gantt, Gauge, Menu, OrgChart, Pivot, RadialMenu, Schedule, ScrollBar, Surface, SwimLane Tree or any other HTML element) once the user clicks a button. For instance, you can select a different item from a drop-down tree or list control, or you can select a different date from a drop-down calendar control. The ExComboBox/JS is a HTML standalone-component, written in JavaScript, that uses no third-party libraries.

Every option of the ComboBox.Options type has associated a property of the control. For instance, the option:

allowActions {string}, customizes the actions the user can perform once the user clicks or touches the control

is associated with the property:

AllowActions {string}, customizes the actions the user can perform once the user clicks or touches the control

which means that the following statements are equivalent:

oComboBox.Options = {allowActions: "d2"}
oComboBox.SetOptions({allowActions: "d2"})
oComboBox.AllowActions = "d2"
oComboBox.SetAllowActions("d2")

where oComboBox is an object of ComboBox type

Parameters:

Name	Type	Attributes	Description
`client`	any		The client parameter indicates the control's client area as: array of [x,y,width,height] type that specifies the control's client area string, that specifies the identifier of the canvas within the document, so the canvas's client area becomes the control's client area HTMLCanvasElement, that specifies the identifier of the canvas within the document, so the canvas's client area becomes the control's client area
`oOptions`	object	<optional>	An object of ComboBox.Options type that defines different options to display the control.

Requires:

module:exontrol.commmon.min.js

ComboBox

Requires

module:exontrol.commmon.min.js

Classes

Options

Members

Listeners :exontrol.Lts

The Listeners field defines the items of the control, as an object of exontrol.Lts type. The exontrol.Lts type supports forEach(callback, thisArg) method that helps you to enumerate the items the control supports. The Items section lists the items the component supports.

Type:

exontrol.Lts

Example

The following sample shows how you can get all items the component currently supports:

oComboBox.Listeners.forEach(function(name)
{
 console.log(name);
});

The following sample displays information about the item being clicked:

oComboBox.Listeners.Add("onclick", function (oEvent)
{
 console.log(oEvent);
});

or

oComboBox.on("click", function (oEvent)
{
 console.log(oEvent);
});

where oComboBox is an object of ComboBox type

Listeners

Shortcuts :exontrol.Sts

The Shortcuts field defines the shortcuts of the control, as an object of exontrol.Sts type. In order to provide keyboard support for the component, the owner <canvas> element must include the tabIndex attribute, as <canvas ... tabIndex="0">. You can associated a function or a callback to any shortcut.

Type:

exontrol.Sts

Shortcuts

oCV :CV

The oCV field defines the base combobox-view of control.

Type:

oCV

(static) type :string

The type field defines the full-name of the object (the constructor.name does not give the same name for minimized forms). The ComboBox.type member always returns "ComboBox"

Type:

string

Since:

(static) version :string

The version field defines the version of the control. The current version is 3.0

Type:

string

Methods

BeginUpdate()

The BeginUpdate() method suspends the control's render until the EndUpdate() method is called. It maintains performance, while multiple changes occurs within the control. You can use the Update() method to perform multiple changes at once.

BeginUpdate

EndUpdate()

The EndUpdate() method resumes the control's render, after it is suspended by the BeginUpdate() method.

EndUpdate

GetCanvas() → {HTMLCanvasElement}

The GetCanvas() method returns the HTMLCanvasElement object where the control is currently running on.

Since:

Returns:

Returns the HTMLCanvasElement object where the control is currently running on.

Type: HTMLCanvasElement

GetCanvas

GetLayout(oOptsopt) → {string}

The GetLayout() method saves the UI layout of the object to an encoded string. The layout can be restored using the SetLayout() method. Currently, the control's Layout property serializes the following:

layout of windows (size, dock, parent)
size of the drop-down panel
properties of the control being hosted by the drop-down panel

Parameters:

Name	Type	Attributes	Description
`oOpts`	object	<optional>	An object of {iMask,eMask,base64,equal,eol} type that defines options to serialize the properties of the container as explained bellow: iMask {string}, specifies the mask (can include ? or * wild-characters) of properties to save eMask {string}, specifies the mask (can include ? or * wild-characters) of properties to exclude from save base64 {boolean}, Encodes the result to BASE 64 equal {string}, Indicates the separator between the name and the value. If missing, the = character is used eol {string}, A character that separates the properties. By default it is "\n"

Returns:

Returns a string that encodes the current UI layout for the entire object

Type: string

Example

The following statements are equivalents:

 oComboBox.GetLayout(), gets the control's layout
 oComboBox.Layout, gets the control's layout

where oComboBox is an object of ComboBox type

GetLayout

GetStatistics() → {string}

The GetStatistics() method gives statistics data of objects being hold by the control

Returns:

Returns statistics data of objects being hold by the control such as:

Size: 1,536x754
Zoom: 100%

Type: string

Example

The following statements are equivalents:

 oComboBox.GetStatistics(), gives statistics data of objects being hold by the control
 oComboBox.Statistics, gives statistics data of objects being hold by the control

where oComboBox is an object of ComboBox type

GetStatistics

Refresh()

The Refresh() method refreshes the control

Refresh

SetLayout(layout, oOptsopt)

The SetLayout() method restores the UI layout of the object from an encoded string, previously returned by the GetLayout() method. Currently, the control's Layout property serializes the following:

layout of windows (size, dock, parent)
size of the drop-down panel
properties of the control being hosted by the drop-down panel

Parameters:

Name	Type	Attributes	Description
`layout`	string		A string expression that defines the UI layout to apply
`oOpts`	object	<optional>	An object of {iMask,eMask,base64,equal,eol} type that defines options to serialize the UI layout as explained bellow: iMask {string}, specifies the mask (can include ? or * wild-characters) of properties to load eMask {string}, specifies the mask (can include ? or * wild-characters) of properties to exclude from load base64 {boolean}, Decodes the layout from BASE 64 equal {string}, Indicates the separator between the name and the value. If missing, the = character is used eol {string}, A sequence of characters that can separate the properties. By default, any of \n, \r or ; separates the properties

SetLayout

Update(callback, thisArgopt)

The Update() method locks the control's paint during the callback, and invalidates the control once the method ends.

Parameters:

Name	Type	Attributes	Description
`callback`	callback		Indicates a callback to perform changes within the control
`thisArg`	any	<optional>	Specifies the value of "this" keyword during the callback. If missing/empty/undefined the thisArg points to the control itself, as an object of ComboBox type

Update

off(event, listener, methodopt)

The off() method removes an event handler that was previously bound to an event, effectively stopping the listener from responding to that event.

Parameters:

Name	Type	Attributes	Description
`event`	string		Specifies the name of the event to unbind. The event name is case-insensitive and may or may not include the 'on' prefix. For example, 'click' is equivalent to 'onclick' and vice versa.
`listener`	object \| callback		Defines the listener to remove, which can either be: listener {object}, an object that implements a notification method (e.g., listener[method](oEvent) or listener[type](oEvent)) that was previously used to handle the event listener {callback}, a JavaScript callback function that was previously bound to the event (the method parameter has no effect)
`method`	string	<optional>	Defines an optional case-sensitive string specifying the method on the listener to remove. If not provided, the listener[type]() function is used. This parameter is ignored when the listener is a JavaScript callback function.

Since:

Example

The following example removes the click event handler from the control:

oComboBox.off("click");

where oComboBox is an object of ComboBox type.

This sample is equivalent to:

oComboBox.Listeners.Remove("onclick");

The following example removes all event handlers from the control:

oComboBox.off();

where oComboBox is an object of ComboBox type.

This sample is equivalent to:

oComboBox.Listeners.Clear();

or

oComboBox.Listeners.Remove();

off

on(event, listener, methodopt) → {object}

The on() method binds a handler to a specified event, enabling you to listen for specific events and define corresponding actions.

Parameters:

Name	Type	Attributes	Description
`event`	string		Specifies the name of the event to listen for. The event name is case-insensitive and may or may not include the 'on' prefix. For example, 'click' is equivalent to 'onclick' and vice versa.
`listener`	object \| callback		Defines the listener, which can either be: listener {object}, an object that implements a notification method (e.g., listener[method](oEvent) or listener[type](oEvent)) to handle the event when it occurs listener {callback}, a JavaScript callback function to handle the event directly (the method parameter has not effect)
`method`	string	<optional>	Defines an optional case-sensitive string specifying the method on the listener to handle the event. If not provided, the listener[type]() function is used. This parameter is ignored when the listener is a JavaScript callback function.

Since:

Returns:

Returns the listeners of the specified type, as an exontrol.Arr({callback, thisArg, lock, name, equal}) type, which includes the following new members:

type {string}, specifies a case-sensitive string that specifies the type of event to listen for
do(event) {callback}, indicates a function that can be invoked to trigger the specified event for all listeners registered for that event type

where:

callback {callback}, defines the listener's callback function
thisArg {any}, defines the value of this during the listener's callback execution
lock {number}, locks or unlocks the invocation of the listener's callback
name {string}, defines the name of the callback, mostly used for debugging purposes
equal(oCompareListenerCallback) {callback}, indicates a function of callback(oCompareListenerCallback) {boolean} type compares the current object with the provided object. It returns true if the objects contain the same data

Type: object

Example

The following example logs event details when the control is clicked:

oComboBox.on("click", function(oEvent)
{
  console.log(oEvent);
});

where oComboBox is an object of ComboBox type.

This sample is quivalent of 

oComboBox.Listeners.Add("onclick", function (oEvent)
{
  console.log(oEvent);
});