Home > Class Reference > ENSLIB namespace > %ZEN.Component.abstractComboBox
Private  Storage   


abstract class %ZEN.Component.abstractComboBox extends 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.


Parameters Properties Methods Queries Indices ForeignKeys Triggers
4 15 27


%condition %import %includeFiles %page
%resource align autocomplete aux
buttonCaption buttonImage buttonImageDown buttonTitle
clientType comboType composite containerStyle
controlClass controlStyle dataBinding delay
disabled dragEnabled dropEnabled dropdownHeight
dropdownWidth editable enclosingClass enclosingStyle
error height hidden hint
hintClass hintStyle hzScroll id
index inputtype invalid invalidMessage
isDropdownVisible label labelClass labelDisabledClass
labelStyle maxlength name onafterdrag
onbeforedrag onblur onchange onclick
ondblclick ondrag ondrop onfocus
onhide onkeydown onkeypress onkeyup
onmousedown onmouseout onmouseover onmouseup
onrefresh onshow onsubmit ontouchend
ontouchmove ontouchstart onupdate onvalidate
originalValue parent placeholder readOnly
required requiredMessage scrollIntoView selectedIndex
showLabel size slice spellcheck
tabIndex text title tuple
unrestricted valign value visible
width window

%AddToSaveSet %Attr %BindExport %ClassIsLatestVersion
%ClassName %ConstructClone %DispatchClassMethod %DispatchGetModified
%DispatchGetProperty %DispatchMethod %DispatchSetModified %DispatchSetMultidimProperty
%DispatchSetProperty %DrawComponentHTML %DrawHTML %DrawJSStrings
%EnclosingDivId %Eval %EvalC %Extends
%ForceClientRender %GetDisplayValue %GetEventHandlers %GetForm
%GetParameter %GetXMLName %IsA %IsModified
%MakeId %Name %New %NormalizeObject
%ObjectModified %OnAddToPageAfter %OnAddToPageBefore %OnDrawEnclosingDiv
%OnDrawObjectProperties %OnObjectSynch %OnZENDeserialize %OriginalNamespace
%PackageName %QuoteValue %QuoteValueL10N %RemoveFromSaveSet
%Self %SerializeObject %SetDefaultValues %SetModified
%ValidateObject XMLDTD XMLExport XMLExportToStream
XMLExportToString XMLNew XMLSchema XMLSchemaNamespace
XMLSchemaType adjustDropdownPosition comboboxButtonDown comboboxButtonUp
comboboxMouseOut comboboxMouseOver dragFinishHandler dragHandler
dragNotifyHandler dragStartHandler dropHandler dropStartHandler
exposeComponent findDisplayValue findElement findSelectedItem
fireOnUpdateEvent focus formatValue getCacheDiv
getDisabled getDragData getDropDownDiv getEnclosingDiv
getForm getHidden getHintElement getInvalidReason
getItemEl getLabelElement getOptionCount getOptionText
getOptionValue getProperty getReadOnly getSettings
getType getValue inputKeyHandler invokeSuper
isModified isOfType isValid makeId
normalizeValue onCreate onDelete onDisplayHandler
onEndModalHandler onPopupAction onRefreshContents onSerialize
onStartModalHandler onchangeHandler onloadHandler onresizeHandler
onunloadHandler onupdateHandler refreshContents render
renderContents renderDropdown renderSVG select
selectItem setDisabled setHidden setOverlayMode
setProperty setReadOnly setValue showDropdown
startProgressBar stopProgressBar sysName unformatValue

%DeepSee.Component.searchBox %ZEN.Component.combobox %ZEN.Component.dataCombo


• 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";
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.


• property buttonCaption as %ZEN.Datatype.caption;
Caption used for the dropdown button when comboType is "button".
• property buttonImage as %ZEN.Datatype.uri [ InitialExpression = ..#DEFAULTBUTTONIMAGE ];
URI of image to display for the combo button in its normal state.
• property buttonImageDown as %ZEN.Datatype.uri [ InitialExpression = ..#DEFAULTBUTTONIMAGEDOWN ];
URI of image to display for the combo button in its down (pressed) state.
• property buttonTitle as %ZEN.Datatype.caption;
Popup title used for the dropdown button when comboType is "button" or "image".
• 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 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 dropdownHeight as %ZEN.Datatype.length;
If defined, override default height of dropdown window.
This is a CSS length value, e.g., "400px"
• property dropdownWidth as %ZEN.Datatype.length;
If defined, override default width of dropdown window.
This is a CSS length value, e.g., "400px"
• 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 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 isDropdownVisible as %ZEN.Datatype.boolean(XMLPROJECTION="none") [ InitialExpression = 0 ];
Internal use only; client flag used to track if the dropdown is visible.
• property scrollIntoView as %ZEN.Datatype.boolean [ InitialExpression = 1 ];
If true, try and make the current item within the dropdown visible.
• 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 text as %ZEN.Datatype.string(XMLPROJECTION="none");
Text (display) value of current item. Do not access this directly; use getProperty('text') instead.
• 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.


• 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.
• method adjustDropdownPosition() [ Language = javascript ]
Adjust the placement and size of the dropdown box based on current screen geometry and scrolling conditions.
• method comboboxButtonDown(evt) [ Language = javascript ]
Mouse down on combobox button
• method comboboxButtonUp() [ Language = javascript ]
Mouse up on combobox button
• method comboboxMouseOut() [ Language = javascript ]
Mouse leaves combobox button
• method comboboxMouseOver() [ Language = javascript ]
Mouse over combobox button
• method dragStartHandler(dragData) [ Language = javascript ]
Default drag handler for comboBox.
• method 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.
• method 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.
• method focus() [ Language = javascript ]
Client-side method to input focus to this control.
• method getCacheDiv() [ Language = javascript ]
Find the local div element used to cache the dropdown list.
• method getDropDownDiv() [ Language = javascript ]
Find the div element used to display the dropdown list.
• method getItemEl(idx) [ Language = javascript ]
Return HTML element for given list item number.
• method getOptionCount() [ Language = javascript ]
Return number of items in the dropdown list.
This must be overridden in subclasses.
• method getOptionText(idx) [ Language = javascript ]
Return the display text for the given item (0-based) in the dropdown list.
This must be overridden in subclasses.
• method getOptionValue(idx) [ Language = javascript ]
Return the logical value of the given item (0-based) in the dropdown list.
This must be overridden in subclasses.
• method inputKeyHandler(evt) [ Language = javascript ]
Keydown within input control.
• method onDelete() [ Language = javascript ]
This client method, if present, is called when this component is removed from the page.
• method onEndModalHandler(zindex) [ Language = javascript ]
Notification that this component is about to stop being modal.
• method onStartModalHandler(zindex) [ Language = javascript ]
Notification that this component is about to become modal.
• method onloadHandler() [ Language = javascript ]
This client event, if present, is fired when the page is loaded.
• method 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.
• method renderDropdown() [ Language = javascript ]
Create contents of the dropdown box using DHTML.
This is overridden in subclasses.
• method 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.
• method 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.
• method showDropdown() [ Language = javascript ]
Make dropdown visible