Class: ComboBox

ComboBox(client, oOptionsopt)

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

Requires

  • module:exontrol.commmon.min.js

Classes

Options

Members

(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)
Type:
  • string
Since:
  • 1.8

(static) version :string

The version field defines the version of the control
Type:
  • string

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);
});

where oComboBox is an object of ComboBox type

oCV :CV

The oCV field defines the base combobox-view of control. Use the AddComboView() method to add a new view to the control. Use the RemoveComboView() method removes a combobox-view already created by AddComboView() method.
Type:

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

Methods

AddComboView(name, attributesopt) → {CV}

The AddComboView() method creates a new view to display the items. Use the RemoveComboView() method removes a combobox-view already created by AddComboView() method.
Parameters:
Name Type Attributes Description
name string defines the name of the combobox-view to be created. It must be an unique name. The "combobox" defines the control's default-combobox view, and it is reserved. If missing, the "combobox.split" is used instead
attributes exontrol.W.Options <optional>
 A exontrol.W.Options that defines the attributes of the window
Properties
Name Type Description
Visible boolean The Visible field indicates whether the window is visible or hidden.
VisibleExtends string The VisibleExtends field specifies the list of windows the current window depends to be visible or hidden. A string expression that specifies the list of windows the current window's visibility depends on as explained:
  • if the VisibleExtends property includes the window itself, the window is visible if any window in VisibleExtends is visible, else
  • if the VisibleExtends property does NOT includes the window itself, the window is hidden if any window in VisibleExtends is hidden (or the window is visible if all VisibleExtends windows are visible)
AllowKeys boolean The AllowKeys field specifies whether the window can receive the Keys items. By default, only the canvas window receives all the keys.
Enabled boolean The Enabled field specifies whether the window is enabled or disabled (the window is protected and shown in gray).
Resizable boolean The Resizable field indicates whether the window is resizable or fixed.
Locked boolean The Locked field specifies that the window is locked (the window is protected).
Dock exontrol.WDT The Dock field specifies how the control borders are docked to its parent control and determines how a control is resized with its parent. The exontrol.WDT type supports the following values:
  • N(0), the window is not docked (none)
  • T(1), the window's top edge is docked to the top of its containing window (top)
  • B(2), the window's bottom edge is docked to the bottom of its containing window (bottom)
  • L(3), the window's left edge is docked to the left edge of its containing window (left)
  • R(4), the window's right edge is docked to the right edge of its containing window (right)
  • F(5), all the window's edges are docked to all edges of its containing window and sized appropriately (fill)
Size number The Size field defines the width/height of the window when it is docked.
SizeExtends string The SizeExtends field specifies the list of windows that shares the same size. Once a window is resized, all its SizeExtends windows are sized the same as the current one.
Client Array.<number> The Client field specifies position of the window relative to the parent window, as an array of [x,y,width,heigh] type.
Background string The Background field defines the window's background color ( CSS Color ) or null/undefined if not provided.
Foreground string The Foreground field defines the window's foreground color ( CSS Color ) or null/undefined if not provided.
Opacity number The Opacity field indicates the window's opacity, as a number between 0 and 1 (1 is not transparent at all, 0.5 is 50% see-through, and 0 is completely transparent)
HoverBackground string The HoverBackground field, defines the window's background color while the cursor hovers it ( CSS Color ) or null/undefined if not provided
HoverForeground string The HoverForeground field defines the window's foreground color while the cursor hovers it( CSS Color ) or null/undefined if not provided
HoverOpacity number The HoverOpacity field indicates the window's opacity, as a number between 0 and 1 (1 is not transparent at all, 0.5 is 50% see-through, and 0 is completely transparent), when the cursor hovers it
DrawWindowFrame boolean The DrawWindowFrame field indicates whether the window draws its frame.
Extends string The Extends field indicates a list of windows separated by comma character to extend the current's client area to. The windows(child windows) must have the z-order greater than the z-order of the current window, else they will be ignored. The Extends field changes the z-order of the windows as well.
HoverExtends string The HoverExtends field specifies the list of windows separated by comma character that receives the hover-items once the cursor hovers the current window.
AllowXChg boolean The AllowXChg field specifies whether the window can exchange its UI position with another window. Only windows with AllowXChg field set can be exchanged.
XChgID string The XChgID field specifies the general expression, whose evaluated result defines the caption to be displayed on the window's anchor-exchange part. The expression supports keywords like index, name and shortname, that indicates the window's index, a value starting from 0, the window's name and short-name. The evaluated result can include exontrol's HTML tags that will be applied on the window's anchor-exchange element. If the expression is not valid, the XChgID value is used as it is.
Control object The Control field defines the control associated with the window (for internal use only).
HScroll string The HScroll field defines window's horizontal scroll bar. A string expression that indicates the name of the window that hosts an exontrol.SB control or an object of exontrol.SB type that defines the window's horizontal scroll bar (for internal use only).
VScroll string The VScroll field defines window's vertical scroll bar. A string expression that indicates the name of the window that hosts an exontrol.SB control or an object of exontrol.SB type that defines the window's vertical scroll bar (for internal use only).
Layout string The Layout field defines the properties (separated by comma) the GetLayout/SetLayout methods of CW saves/restores (for internal use only).
Returns:
Returns the newly created view as an object of CV type. Returns null, in case there is already a window with specified name.
Type
CV
Example
oComboBox.AddComboView("2nd",{Background: "black", Foreground: "white", Dock: 3}), adds a new combobox-view panel, docked to the left-size, with a black-background and a white-foreground

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.

ComboView(name) → {CV}

The ComboView() method gets the combobox-view by name (which was previously created by the AddComboView() method)
Parameters:
Name Type Description
name string defines the name of the combobox-view to request ("combobox" defines the control's default-combobox view)
Returns:
Returns null or the an object of CV type associated with the name
Type
CV

EndUpdate()

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

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

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

Refresh()

The Refresh() method refreshes the control

RemoveComboView(name)

The RemoveComboView() method removes the view already created by the AddComboView() method
Parameters:
Name Type Description
name string defines the name of the combobox-view to be removed. The "combobox" defines the control's default-combobox view, and it can not be removed.

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

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