Zimlet JavaScript API Reference - DwtButton

Class DwtButton


Extends DwtLabel.

This class represents a button, which is basically a smart label that can handle various UI events. It knows when it has been hovered (the mouse is over it), when it is active (mouse down), and when it has been pressed (mouse up). In addition to a label's image and/or text, a button may have a dropdown menu.

There are several different types of button:

  • Push - This is the standard push button
  • Toggle - This is a button that exhibits selectable behaviour when clicked e.g. on/off. To make a button selectable style "or" DwtButton.SELECT_STYLE to the constructor's style parameter
  • Menu - By setting a mene via the #setMenu method a button will become a drop down or menu button.

CSS

  • className-hover - hovered style
  • className-active - mouse down style
  • className-selected - permanently down style
  • className-disabled - disabled style

Keyboard Actions

  • DwtKeyMap.SELECT - triggers the button
  • DwtKeyMap.SUBMENU - display's the button's submenu if one is set


Defined in: DwtButton.js.

Class Summary
Constructor Attributes Constructor Name and Description
 
DwtButton(params)
Creates a button.
Method Summary
Method Attributes Method Name and Description
 
Adds a listener to be notified when the dropdown arrow is pressed.
 
addSelectionListener(listener, index)
Adds a listener to be notified when the button is pressed.
 
Disposes of the button.
 
Gets the key map name.
 
getMenu(dontCreate)
Gets the button menu.
 
handleKeyAction(actionCode, ev)
Handles a key action event.
 
Checks if the button is toggled.
 
popup(menu, event)
Pops-up the button menu (if present).
 
Removes a dropdown selection listener.
 
Removes options from drop down menu
 
Removes a selection listener.
 
Removes all the selection listeners.
 
Resets the button display to normal (not hovered or active).
 
setActionTiming(actionTiming)
Sets whether actions for this button should occur on mouse up or mouse down.
 
setDepressedImage(imageInfo)
Sets the depressed image
 
setDisplayState(state, force)
Sets the display state.
 
Sets the Drop Down Hover Image
 
setDropDownImages(enabledImg, disImg, hovImg, depImg)
Sets the dropdown images.
 
setEnabled(enabled)
Sets the enabled/disabled state of the button.
 
setEnabledImage(imageInfo)
Sets the enabled image
 
setHovered(hovered)
Activates/de-activates the button.
 
setHoverImage(hoverImageInfo, direction)
Sets the hover image.
 
setImage(imageInfo, direction)
Sets the main (enabled) image.
 
setMenu(params, menu, shouldToggle, menuPopupStyle, popupAbove, popupRight)
Adds a dropdown menu to the button, available through a small down-arrow.
 
setSelected(selected)
Sets the button as selected.
 
setText(text)
Sets the text.
Methods borrowed from class DwtLabel:
getImage, getText, isStyle, setAlign, setDisabledImage, setIconEl, setTextBackground, setTextForeground, toString
Methods borrowed from class DwtComposite:
addChild, cleanupSeparators, clear, getChild, getChildren, getNumChildren, getTabGroupMember, removeChild, removeChildren
Methods borrowed from class DwtControl:
addClassName, addControlListener, addDisposeListener, addListener, appendElement, blur, clearContent, clearHandler, condClassName, delClassName, focus, getBounds, getClassName, getContent, getCursor, getData, getDragBox, getDragSource, getDropTarget, getEnabled, getFocusElement, getH, getHtmlElement, getHTMLElId, getInsetBounds, getInsets, getLocation, getMargins, getOpacity, getOuterSize, getPosition, getScrollContainer, getScrollStyle, getSize, getTooltipBase, getToolTipContent, getVisibility, getVisible, getW, getX, getXW, getY, getYH, getZIndex, hasFocus, isAlertShown, isDisposed, isInitialized, isListenerRegistered, notifyListeners, preventContextMenu, preventSelection, removeAllListeners, removeControlListener, removeDisposeListener, removeListener, reparent, reparentHtmlElement, replaceElement, setBounds, setClassName, setContent, setCursor, setData, setDisplay, setDragBox, setDragSource, setDropTarget, setEventPropagation, setFocusElement, setHandler, setHtmlElementId, setLocation, setOpacity, setPosition, setScrollStyle, setSize, setToolTipContent, setVisibility, setVisible, setZIndex, showAlert, zShow
Class Detail
DwtButton(params)
Creates a button.
Author: Ross Dargahi, Conrad Damon.
Parameters:
{hash} params
a hash of parameters
{DwtComposite} params.parent
the parent widget
{constant} params.style
the button style
{string} params.className
the CSS class
{constant} params.posStyle
the positioning style
{DwtButton.ACTION_MOUSEUP|DwtButton.ACTION_MOUSEDOWN} params.actionTiming
if DwtButton.ACTION_MOUSEUP, then the button is triggered on mouseup events, else if DwtButton.ACTION_MOUSEDOWN, then the button is triggered on mousedown events
{string} params.id
the id to use for the control HTML element
{number} params.index
the index at which to add this control among parent's children
{hash} params.listeners
a hash of event listeners
Method Detail
addDropDownSelectionListener(listener)
Adds a listener to be notified when the dropdown arrow is pressed.
Parameters:
{AjxListener} listener
the listener

addSelectionListener(listener, index)
Adds a listener to be notified when the button is pressed.
Parameters:
{AjxListener} listener
the listener
{number} index
the index at which to add listener

dispose()
Disposes of the button.

{string} getKeyMapName()
Gets the key map name.
Returns:
{string} the key map name

{DwtMenu} getMenu(dontCreate)
Gets the button menu.
Parameters:
{boolean} dontCreate
if true, the menu will not be lazily created
Returns:
{DwtMenu} the menu or null if menu is not set

{boolean} handleKeyAction(actionCode, ev)
Handles a key action event.
Parameters:
{constant} actionCode
the action code (see DwtKeyMap)
{DwtEvent} ev
the event
Returns:
{boolean} true if the event is handled; false otherwise
See:
DwtKeyMap

{boolean} isToggled()
Checks if the button is toggled.
Returns:
{boolean} true if toggled

popup(menu, event)
Pops-up the button menu (if present).
Parameters:
{DwtMenu} menu
the menu to use or null to use currently set menu
event

removeDropDownSelectionListener(listener)
Removes a dropdown selection listener.
Parameters:
{AjxListener} listener
the listener to remove

removePullDownMenuOptions()
Removes options from drop down menu

removeSelectionListener(listener)
Removes a selection listener.
Parameters:
{AjxListener} listener
the listener to remove

removeSelectionListeners()
Removes all the selection listeners.

resetClassName()
Resets the button display to normal (not hovered or active).

setActionTiming(actionTiming)
Sets whether actions for this button should occur on mouse up or mouse down.
Parameters:
{DwtButton.ACTION_MOUSEDOWN|DwtButton.ACTION_MOUSEUP} actionTiming
the action timing

setDepressedImage(imageInfo)
Sets the depressed image
Parameters:
{string} imageInfo
the image

setDisplayState(state, force)
Sets the display state.
Parameters:
{string} state
the display state
{boolean} force
if true, force the state change
See:
DwtControl

setDropDownHovImage(hovImg)
Sets the Drop Down Hover Image
Parameters:
hovImg

setDropDownImages(enabledImg, disImg, hovImg, depImg)
Sets the dropdown images.
Parameters:
{string} enabledImg
the enabled image
{string} disImg
the disabled image
{string} hovImg
the hover image
{string} depImg
the depressed image

setEnabled(enabled)
Sets the enabled/disabled state of the button. A disabled button may have a different image, and greyed out text. The button (and its menu) will only have listeners if it is enabled.
Parameters:
{boolean} enabled
if true, enable the button

setEnabledImage(imageInfo)
Sets the enabled image
Parameters:
{string} imageInfo
the image

setHovered(hovered)
Activates/de-activates the button. A button is hovered when the mouse is over it.
Parameters:
{boolean} hovered
if true, the button is hovered

setHoverImage(hoverImageInfo, direction)
Sets the hover image.
Parameters:
{string} hoverImageInfo
the image
{string} direction
position of the image

setImage(imageInfo, direction)
Sets the main (enabled) image. If the button is currently enabled, the image is updated.
Parameters:
{string} imageInfo
the image
direction

setMenu(params, menu, shouldToggle, menuPopupStyle, popupAbove, popupRight)
Adds a dropdown menu to the button, available through a small down-arrow. If a callback is passed as the dropdown menu, it is called the first time the menu is requested. The callback must return a valid DwtMenu object.
Parameters:
{hash} params
hash of params:
{DwtMenu|AjxCallback} menu
the dropdown menu or a callback
{boolean} shouldToggle
if true, toggle
{string} menuPopupStyle
one of DwtButton.MENU_POPUP_STYLE_* (default is BELOW)
{boolean} popupAbove
if true, pop up the menu above the button
{boolean} popupRight
if true, align the right edge of the menu to the right edge of the button

setSelected(selected)
Sets the button as selected.
Parameters:
{boolean} selected
if true, the button is selected

setText(text)
Sets the text.
Parameters:
{string} text
the text

Documentation generated by JsDoc Toolkit 2.3.0 on Tue Jun 28 2016 21:01:27 GMT-0400 (EDT)