This is documentation for Caché & Ensemble.

For information on converting to InterSystems IRIS, see the InterSystems IRIS Adoption Guide and the InterSystems IRIS In-Place Conversion Guide, both available on the WRC Distributions page (login required).

Home > Class Reference > %SYS namespace > %ZEN.Component.abstractComboBox


abstract class %ZEN.Component.abstractComboBox extends %ZEN.Component.text

This is an abstract base class that provides common functionality to the various combobox controls (such as combobox and dataCombo).
A combobox consists of text control that displays the current (display) value of the control, and a dropdown list (that appears when activated by the user) that displays a set of options. The contents of the dropdown list are provided by subclasses of this base class.
A combobox is itself a subclass of the text control. You can use the various methods defined by the text control to manipulate the text box portion of the combobox.

Note that unlike other controls, a combobox is not a simple wrapper around an HTML select control but is implemented using HTML primitives. This is in order to provide additional functionality than provided by the HTML select control (e.g., ability to edit values and, via subclassing, more control over the contents of the drop down list.) In addition it solves many of the problems found in the Internet Explorer version of the HTML select control (such as problems interoperating with CSS).
Activating the dropdown list
The dropdown list can be displayed in several manners. This behavior is defined by the comboType property.

Property Inventory (Including Private)

Method Inventory (Including Private)


parameter DEFAULTBUTTONIMAGE = images/combobox.png;
Default image for button in normal state.
parameter DEFAULTBUTTONIMAGEDOWN = images/comboboxpress.png;
Default image for button in down state.
parameter DEFAULTCONTROLCLASS = comboboxInput;
Inherited description: The default css class used for the main element within this control. This is overridden by subclasses.
parameter USECACHEDIV = 0;
Indicates that this combobox should cache its dropdown contents.

Properties (Including Private)

property buttonCaption as %ZEN.Datatype.caption;
Caption used for the dropdown button when comboType is "button".
Property methods: buttonCaptionDisplayToLogical(), buttonCaptionGet(), buttonCaptionIsValid(), buttonCaptionLogicalToDisplay(), buttonCaptionLogicalToOdbc(), buttonCaptionNormalize(), buttonCaptionSet()
property buttonImage as %ZEN.Datatype.uri [ InitialExpression = ..#DEFAULTBUTTONIMAGE ];
URI of image to display for the combo button in its normal state.
Property methods: buttonImageDisplayToLogical(), buttonImageDownDisplayToLogical(), buttonImageDownGet(), buttonImageDownIsValid(), buttonImageDownLogicalToDisplay(), buttonImageDownLogicalToOdbc(), buttonImageDownNormalize(), buttonImageDownSet(), buttonImageGet(), buttonImageIsValid(), buttonImageLogicalToDisplay(), buttonImageLogicalToOdbc(), buttonImageNormalize(), buttonImageSet()
property buttonImageDown as %ZEN.Datatype.uri [ InitialExpression = ..#DEFAULTBUTTONIMAGEDOWN ];
URI of image to display for the combo button in its down (pressed) state.
Property methods: buttonImageDownDisplayToLogical(), buttonImageDownGet(), buttonImageDownIsValid(), buttonImageDownLogicalToDisplay(), buttonImageDownLogicalToOdbc(), buttonImageDownNormalize(), buttonImageDownSet()
property buttonTitle as %ZEN.Datatype.caption;
Popup title used for the dropdown button when comboType is "button" or "image".
Property methods: buttonTitleDisplayToLogical(), buttonTitleGet(), buttonTitleIsValid(), buttonTitleLogicalToDisplay(), buttonTitleLogicalToOdbc(), buttonTitleNormalize(), buttonTitleSet()
property comboType as %ZEN.Datatype.string (VALUELIST = ",image,button,timer") [ InitialExpression = "image" ];
Specifies how the dropdown box is activated for the combobox.
  • "image" indicates that a user-clickable image should be displayed next to the combobox text box.
  • "button" indicates that a button should be displayed next to the combobox text box.
  • "timer" indicates the dropdown should appear shortly after the user enters a value within the combobox text box.
Property methods: comboTypeDisplayToLogical(), comboTypeGet(), comboTypeIsValid(), comboTypeLogicalToDisplay(), comboTypeLogicalToOdbc(), comboTypeNormalize(), comboTypeSet()
property delay as %ZEN.Datatype.integer [ InitialExpression = 250 ];
Specifies how long to wait, in milliseconds, after user finishes typing before showing the dropdown when comboType is "timer".
Property methods: delayDisplayToLogical(), delayGet(), delayIsValid(), delayLogicalToDisplay(), delayLogicalToOdbc(), delayNormalize(), delaySet()
If defined, override default height of dropdown window.
This is a CSS length value, e.g., "400px"
Property methods: dropdownHeightDisplayToLogical(), dropdownHeightGet(), dropdownHeightIsValid(), dropdownHeightLogicalToDisplay(), dropdownHeightLogicalToOdbc(), dropdownHeightNormalize(), dropdownHeightSet()
If defined, override default width of dropdown window.
This is a CSS length value, e.g., "400px"
Property methods: dropdownWidthDisplayToLogical(), dropdownWidthGet(), dropdownWidthIsValid(), dropdownWidthLogicalToDisplay(), dropdownWidthLogicalToOdbc(), dropdownWidthNormalize(), dropdownWidthSet()
property editable as %ZEN.Datatype.boolean [ InitialExpression = 0 ];
If true, then this is an editable combobox (a user can directly edit the value within the input box).
Property methods: editableDisplayToLogical(), editableGet(), editableIsValid(), editableLogicalToDisplay(), editableLogicalToOdbc(), editableLogicalToXSD(), editableNormalize(), editableSet(), editableXSDToLogical()
property hzScroll as %ZEN.Datatype.boolean [ InitialExpression = 0 ];
If true, allow the dropdown window to display horizontal scroll bars if they are needed (and its current CSS style specifies them).
Property methods: hzScrollDisplayToLogical(), hzScrollGet(), hzScrollIsValid(), hzScrollLogicalToDisplay(), hzScrollLogicalToOdbc(), hzScrollLogicalToXSD(), hzScrollNormalize(), hzScrollSet(), hzScrollXSDToLogical()
property isDropdownVisible as %ZEN.Datatype.boolean (XMLPROJECTION = "none") [ InitialExpression = 0 ];
Internal use only; client flag used to track if the dropdown is visible.
Property methods: isDropdownVisibleDisplayToLogical(), isDropdownVisibleGet(), isDropdownVisibleIsValid(), isDropdownVisibleLogicalToDisplay(), isDropdownVisibleLogicalToOdbc(), isDropdownVisibleLogicalToXSD(), isDropdownVisibleNormalize(), isDropdownVisibleSet(), isDropdownVisibleXSDToLogical()
property scrollIntoView as %ZEN.Datatype.boolean [ InitialExpression = 1 ];
If true, try and make the current item within the dropdown visible.
Property methods: scrollIntoViewDisplayToLogical(), scrollIntoViewGet(), scrollIntoViewIsValid(), scrollIntoViewLogicalToDisplay(), scrollIntoViewLogicalToOdbc(), scrollIntoViewLogicalToXSD(), scrollIntoViewNormalize(), scrollIntoViewSet(), scrollIntoViewXSDToLogical()
property selectedIndex as %ZEN.Datatype.integer [ InitialExpression = -1 ];
Index (0-based) of current selected option.
This is the ordinal position of the current item within the dropdown list.
Property methods: selectedIndexDisplayToLogical(), selectedIndexGet(), selectedIndexIsValid(), selectedIndexLogicalToDisplay(), selectedIndexLogicalToOdbc(), selectedIndexNormalize(), selectedIndexSet()
property text as %ZEN.Datatype.string (XMLPROJECTION = "none");
Text (display) value of current item. Do not access this directly; use getProperty('text') instead.
Property methods: textDisplayToLogical(), textGet(), textIsValid(), textLogicalToDisplay(), textLogicalToOdbc(), textNormalize(), textSet()
property unrestricted as %ZEN.Datatype.boolean [ InitialExpression = 0 ];
If true, and if this is an editable combobox, then values entered by the user are used as the value of the control, otherwise the value is restricted to one of the choices within the dropdown list.
Property methods: unrestrictedDisplayToLogical(), unrestrictedGet(), unrestrictedIsValid(), unrestrictedLogicalToDisplay(), unrestrictedLogicalToOdbc(), unrestrictedLogicalToXSD(), unrestrictedNormalize(), unrestrictedSet(), unrestrictedXSDToLogical()

Methods (Including Private)

method %DrawHTML()
Draw the input box and button for this combobox.
Note that the actual value is placed in a hidden control as the contents of the input box may not be the actual value.
method %GetDisplayValue(pValue As %String) as %String
Lookup up the display value for the combobox given a logical value.
This is called when the control is initially drawn.
Note: this is implemented as an expression method; subclasses are free to implement this as a regular method.
clientmethod adjustDropdownPosition() [ Language = javascript ]
Adjust the placement and size of the dropdown box based on current screen geometry and scrolling conditions.
clientmethod comboboxButtonDown(evt) [ Language = javascript ]
Mouse down on combobox button
clientmethod comboboxButtonUp() [ Language = javascript ]
Mouse up on combobox button
clientmethod comboboxMouseOut() [ Language = javascript ]
Mouse leaves combobox button
clientmethod comboboxMouseOver() [ Language = javascript ]
Mouse over combobox button
clientmethod dragStartHandler(dragData) [ Language = javascript ]
Default drag handler for comboBox.
clientmethod findDisplayValue(value) [ Language = javascript ]
Given a logical value, lookup the display value within the current set of options. Returns null if no match is found.
Subclasses may override this to add additional lookup behavior.
clientmethod findSelectedItem(force) [ Language = javascript ]
Find and select item within the dropdown that matches current control value. This is called when the dropdown appears to make sure that the current item is highlighted.
clientmethod focus() [ Language = javascript ]
Client-side method to input focus to this control.
clientmethod getCacheDiv() [ Language = javascript ]
Find the local div element used to cache the dropdown list.
clientmethod getDropDownDiv() [ Language = javascript ]
Find the div element used to display the dropdown list.
clientmethod getItemEl(idx) [ Language = javascript ]
Return HTML element for given list item number.
clientmethod getOptionCount() [ Language = javascript ]
Return number of items in the dropdown list.
This must be overridden in subclasses.
clientmethod getOptionText(idx) [ Language = javascript ]
Return the display text for the given item (0-based) in the dropdown list.
This must be overridden in subclasses.
clientmethod getOptionValue(idx) [ Language = javascript ]
Return the logical value of the given item (0-based) in the dropdown list.
This must be overridden in subclasses.
clientmethod inputKeyHandler(evt) [ Language = javascript ]
Keydown within input control.
clientmethod onDelete() [ Language = javascript ]
This client method, if present, is called when this component is removed from the page.
clientmethod onEndModalHandler(zindex) [ Language = javascript ]
Notification that this component is about to stop being modal.
clientmethod onStartModalHandler(zindex) [ Language = javascript ]
Notification that this component is about to become modal.
clientmethod onloadHandler() [ Language = javascript ]
This client event, if present, is fired when the page is loaded.
clientmethod onresizeHandler() [ Language = javascript ]
This client event is fired when the page is resized and the dropdown is visible. Resizing the window while the dropdown is open can cause the base component and its dropdown to become detached, this method traps such occuranences and allows the dropdown to be repositioned.
clientmethod renderDropdown() [ Language = javascript ]
Create contents of the dropdown box using DHTML.
This is overridden in subclasses.
clientmethod selectItem(idx, show, update) [ Language = javascript ]
User has selected an item in the DropDown box. If show is true, make item visible. If update is true, update value of control.
clientmethod setProperty(property, value, value2) [ Language = javascript ]
Set the value of a named property.
Assume that subclasses that simply wrap HTML controls have named the control 'control' or else have overridden this method.
clientmethod showDropdown() [ Language = javascript ]
Make dropdown visible

Inherited Members

Inherited Properties (Including Private)

Inherited Methods (Including Private)