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