Class: PopupMenu

Kekule.Widget. PopupMenu

new PopupMenu()

An popup menu widget.
Source:

Extends

Methods

addClassName(classNames, affectCustomProp)

Add class name(s) to widget element. If affectCustomProp is true, this method will change customHtmlClassName property.
Parameters:
Name Type Description
classNames Variant Can be a simple name, or a series of name separated by space ('name1 name2') or an array of strings.
affectCustomProp Bool Whether change customHtmlClassName property of widget.
Inherited From:
Source:

addIaController(id, controller, asDefault)

Link a controller with this component.
Parameters:
Name Type Description
id String Unique id of controller
controller Kekule.Widget.InteractionController
asDefault Bool Whether set this controller as the default one to handle events.
Inherited From:
Source:

appendMenuItem(menuItem)

Append a menu item.
Parameters:
Name Type Description
menuItem Kekule.Widget.MenuItem
Inherited From:
Source:

appendToElem(parentElem)

Append current widget to parentElem.
Parameters:
Name Type Description
parentElem HTMLElement
Inherited From:
Source:

appendToWidget(parentWidget)

Append widget as a child to parentWidget.
Parameters:
Name Type Description
parentWidget Kekule.Widget.BaseWidget
Inherited From:
Source:

appendWidget(widget)

Append an widget to container/
Parameters:
Name Type Description
widget Kekule.Widget.BaseWidget
Inherited From:
Source:

blur()

Move focus out of widget.
Inherited From:
Source:

canUsePlaceHolderOnElem(elem) → {Bool}

Returns whether a placeholder widget can be bind to element to represent this widget. This method is used when auto-launching widget on HTML element. Descendants can override this method.
Parameters:
Name Type Description
elem HTMLElement
Inherited From:
Source:
Returns:
Type
Bool

clearMenuItems(doNotFinalize)

Remove all items in menu.
Parameters:
Name Type Description
doNotFinalize Bool If set to true, the child menu items will not be finalized.
Inherited From:
Source:

clearWidgets(doNotFinalize)

Remove all children in container and destroy them.
Parameters:
Name Type Description
doNotFinalize Bool If set to true, the widget will not be finalized.
Inherited From:
Source:

createChildrenByDefs(defs)

Create child menu items by hash definitions.
Parameters:
Name Type Description
defs Array Hash definition of child menu items.
Inherited From:
Source:

createDecorationContent(parentElem, refElem) → {HTMLElement}

Create a decoration content element and insert it to parentElem before refElem.
Parameters:
Name Type Description
parentElem HTMLElement
refElem HTMLElement
Inherited From:
Source:
Returns:
Element created.
Type
HTMLElement

createElement() → {HTMLElement}

Create an HTML element to represent the widget. //@param {HTMLElement} parentElement
Inherited From:
Source:
Returns:
Type
HTMLElement

createGlyphContent(parentElem, refElem, htmlClassName) → {HTMLElement}

Create a glyph content container and insert it to parentElem before refElem.
Parameters:
Name Type Description
parentElem HTMLElement
refElem HTMLElement
htmlClassName String Class name added to content element.
Inherited From:
Source:
Returns:
Element created.
Type
HTMLElement

createTextContent(text, parentElem, refElem) → {HTMLElement}

Create an text content element and insert it to parentElem before refElem.
Parameters:
Name Type Description
text String
parentElem HTMLElement
refElem HTMLElement
Inherited From:
Source:
Returns:
Element created.
Type
HTMLElement

defineElemAttribMappingProp(propName, elemAttribName, options) → {Object}

Create a property that read/write attribute of HTML element.
Parameters:
Name Type Description
propName String
elemAttribName String Attribute name of HTML element.
options Hash Options to define property. If not set, default option will be used.
Inherited From:
Source:
Returns:
Property info object added to property list.
Type
Object

defineElemStyleMappingProp(propName, stylePropName, options) → {Object}

Create a property that read/write style property of HTML element.
Parameters:
Name Type Description
propName String
stylePropName String Property name of element.style.
options Hash Options to define property. If not set, default option will be used.
Inherited From:
Source:
Returns:
Property info object added to property list.
Type
Object

destroyElement(elem)

Remove the binding element from DOM tree.
Parameters:
Name Type Description
elem HTMLElement
Inherited From:
Source:

dismiss(caller, callback, hideType,)

Dismiss a widget and cancel its modified value. Here we simply hide the widget.Descendant may override this method to do more complex job.
Parameters:
Name Type Description
caller Kekule.Widget.BaseWidget Who calls the hide method and make this widget invisible.
callback Func This callback function will be called when the widget is totally hidden.
hideType, Int value from Kekule.Widget.ShowHideType. * @param {Hash} extraOptions Extra transition options. It may contains two special fields. One is "instantly". If this field is set to true, the showing process will be executed without transition. The other is "useVisible", if true, when hiding the widget, visible property will be setted to false, otherwise the displayed property will be setted to false.
Inherited From:
Source:

domElemAdded(elem)

Called when additional element inserted inside widget.
Parameters:
Name Type Description
elem HTMLElement
Inherited From:
Source:

domElemRemoved(elem)

Called when element removed from widget.
Parameters:
Name Type Description
elem HTMLElement
Inherited From:
Source:

doUnbindElement(element)

Do actual work of unbindElement for descendents' overriding.
Parameters:
Name Type Description
element HTMLElement
Inherited From:
Source:

execute(invokerHtmlEvent)

This method should be called when the primary action is taken on widge (such as click on button, select on menu and so on).
Parameters:
Name Type Description
invokerHtmlEvent Object HTML event object that invokes executing process.
Inherited From:
Source:

flash(time, caller, callback, showType,)

Show widget then hide it after a period of time.
Parameters:
Name Type Description
time Int In milliseconds.
caller Kekule.Widget.BaseWidget Who calls the show method and make this widget visible.
callback Func This callback function will be called when the widget is totally shown.
showType, Int value from Kekule.Widget.ShowHideType.
Inherited From:
Source:

focus()

Focus on widget.
Inherited From:
Source:

getBindableElemTagNames() → {Array}

Returns the tag names of element can be binded with widget. Tag names should be all lowercased. The return value of null means widget can bind to any element. On the contrary, if [](empty array) is returned, the widget will be regarded as unbindable to any element. Defaultly, this method will return widget.BINDABLE_TAG_NAMES. Descendants can overwrite that variable to meet their own needs.
Inherited From:
Source:
Returns:
Type
Array

getBoundingClientRect(elem, includeScroll) → {Hash}

Returns bounding client rectangle of widget.
Parameters:
Name Type Description
elem HTMLElement
includeScroll Bool If this value is true, scrollTop/Left of documentElement will be added to result.
Inherited From:
Source:
Returns:
{top, left, bottom, right, width, height}
Type
Hash

getChildActionClass(actionName, checkSupClasses) → {Class}

Returns child action class associated with name for this widget.
Parameters:
Name Type Description
actionName String
checkSupClasses Bool When true, if action is not found in current widget class, super classes will also be checked.
Inherited From:
Source:
Returns:
Type
Class

getChildAtIndex(index) → {Kekule.Widget.BaseWidget}

Returns child widget at index
Parameters:
Name Type Description
index Int
Inherited From:
Source:
Returns:
Type
Kekule.Widget.BaseWidget

getChildrenHolderElement() → {HTMLElement}

Returns the element that be used as root to insert child widgets. Descendants can override this method to reflect that situation.
Inherited From:
Source:
Returns:
Type
HTMLElement

getConfigurator() → {Kekule.Widget.BaseWidget}

Returns widget instance of configurator.
Inherited From:
Source:
Returns:
Type
Kekule.Widget.BaseWidget

getContainerElement() → {HTMLElement}

Returns the parent HTML element to hold all child widgets. Descendants can override this method.
Inherited From:
Source:
Returns:
Type
HTMLElement

getCoreElement() → {HTMLElement}

Returns core element of widget. Usually core element is the element widget binded to, but in some cases, core element may be a child of widget element. Descendants can override this method to reflect that situation.
Inherited From:
Source:
Returns:
Type
HTMLElement

getDimension() → {Hash}

Returns dimension in px of this widget.
Inherited From:
Source:
Returns:
{width, height}.
Type
Hash

getGlobalManager() → {Object}

Returns global widget manager in current document.
Inherited From:
Source:
Returns:
Type
Object

getIaController(id) → {Kekule.Widget.InteractionController}

Returns controller by id.
Parameters:
Name Type Description
id String
Inherited From:
Source:
Returns:
Type
Kekule.Widget.InteractionController

getMenuItems(rootMenuElem) → {Array}

Returns menu item widget in a menu or sub menu element.
Parameters:
Name Type Description
rootMenuElem HTMLElement Set null to get all first level items.
Inherited From:
Source:
Returns:
Type
Array

getNextSibling()

Returns next sibling widget under the same parent widget.
Inherited From:
Source:

getPageRect(elem, relToViewport) → {Hash}

Returns rectangle of widget in HTML page.
Parameters:
Name Type Description
elem HTMLElement
relToViewport Bool If this value is true, scrollTop/Left of documentElement will be substracted from result.
Inherited From:
Source:
Returns:
{top, left, bottom, right, width, height}
Type
Hash

getPrevSibling()

Returns previous sibling widget under the same parent widget.
Inherited From:
Source:

getStateClassName(state) → {String}

Get class name to set the outlook of current state. Descendants can override this method.
Parameters:
Name Type Description
state Int
Inherited From:
Source:
Returns:
Type
String

getStyleProperty(cssPropName, element) → {Variant}

Get CSS property value or a style resource linked to element.
Parameters:
Name Type Description
cssPropName String CSS property name in JavaScript form.
element HTMLElement If not set, widget element will be used.
Inherited From:
Source:
Returns:
A instance of Kekule.Widget.StyleResource or simply a CSS value.
Type
Variant

getSubMenuTagName() → {String}

Returns prefered menu list tag (ul or ol) to create new sub menu.
Inherited From:
Source:
Returns:
Type
String

getTextSelectable() → {Bool}

Whether the text content inside widget element can be user selected. Most widget (like tree, button) should return false, but form controls (like textbox) should return true. Descendants may override this method.
Inherited From:
Source:
Returns:
Type
Bool

getWidgetClassName() → {string}

Returns widget identity class name(s) need to add to HTML element.
Inherited From:
Source:
Returns:
Type
string

hasChild(widget) → {Bool}

Check if widget is a child of current widget.
Parameters:
Name Type Description
widget Kekule.Widget.BaseWidget
Inherited From:
Source:
Returns:
Type
Bool

hasClassName(className) → {Bool}

Check if a class is associate with element of this widget.
Parameters:
Name Type Description
className String
Inherited From:
Source:
Returns:
Type
Bool

hide(caller, callback, hideType,, extraOptions)

Hide widget.
Parameters:
Name Type Description
caller Kekule.Widget.BaseWidget Who calls the hide method and make this widget invisible.
callback Func This callback function will be called when the widget is totally hidden.
hideType, Int value from Kekule.Widget.ShowHideType.
extraOptions Hash Extra transition options. It may contains two special fields. One is "instantly". If this field is set to true, the showing process will be executed without transition. The other is "useVisible", if true, when hiding the widget, visible property will be setted to false, otherwise the displayed property will be setted to false.
Inherited From:
Source:

indexOfChild(widget) → {Int}

Returns index of child widget. If widget is not a child, -1 will be returned.
Parameters:
Name Type Description
widget Kekule.Widget.BaseWidget
Inherited From:
Source:
Returns:
Type
Int

initialize()

Inherited From:
Source:

insertedToDom()

Called when widget is inserted into DOM tree.
Inherited From:
Source:

insertMenuItem(menuItem, refItem)

Insert a menu item before refItem. If refItem is not set, new item will be appended.
Parameters:
Name Type Description
menuItem Kekule.Widget.MenuItem
refItem Kekule.Widget.MenuItem
Inherited From:
Source:

insertToElem(parentElem, refElem)

Insert current widget to parentElem, before refElem.
Parameters:
Name Type Description
parentElem HTMLElement
refElem HTMLElement
Inherited From:
Source:

insertToWidget(parentWidget, refWidget)

Insert this widget as child to parentWidget, before refWidget. If refWidget not set, widget will be appended to parent.
Parameters:
Name Type Description
parentWidget Kekule.Widget.BaseWidget
refWidget Kekule.Widget.BaseWidget
Inherited From:
Source:

insertWidgetBefore(widget, refWidget)

Insert an widget before refWidget.
Parameters:
Name Type Description
widget Kekule.Widget.BaseWidget
refWidget Kekule.Widget.BaseWidget
Inherited From:
Source:

isCaptureMouse() → {Bool}

Returns whether this widget is currently capturing mouse/touch event.
Inherited From:
Source:
Returns:
Type
Bool

isElementBindable(element) → {Bool}

Check if widget can bind to an element. Descendants can override this method to do some further check on element.
Parameters:
Name Type Description
element HTMLElement
Inherited From:
Source:
Returns:
Type
Bool

isInDomTree() → {Bool}

Check if widget is in document DOM tree.
Inherited From:
Source:
Returns:
Type
Bool

isPeriodicalExecuting() → {Bool}

Check if periodical executing is on process.
Inherited From:
Source:
Returns:
Type
Bool

isShown(ignoreDom) → {Bool}

Check if widget element is visible to user.
Parameters:
Name Type Description
ignoreDom Bool If true, this method will only check CSS visibility and display property.
Inherited From:
Source:
Returns:
Type
Bool

isTopLevel() → {Bool}

Returns whether current menu is the top level one.
Inherited From:
Source:
Returns:
Type
Bool

linkStyleResource(resOrName, element)

Apply style resource to self or an element.
Parameters:
Name Type Description
resOrName Variant An instance of Kekule.Widget.StyleResource or resource name.
element HTMLElement If not set, style will be set to widget element.
Inherited From:
Source:

openConfigurator(callerWidget)

Open a popup configurator to modify settings of displayer.
Parameters:
Name Type Description
callerWidget Kekule.Widget.BaseWidget Who invokes the action.
Inherited From:
Source:

removeClassName(classNames, affectCustomProp)

remove class(es) from widget element. This method not also change customHtmlClassName property.
Parameters:
Name Type Description
classNames Variant Can be a simple name, or a series of name separated by space ('name1 name2') or an array of strings.
affectCustomProp Bool Whether change customHtmlClassName property of widget.
Inherited From:
Source:

removedFromDom()

Called when widget is removed from DOM tree.
Inherited From:
Source:

removeFromDom()

Remove current widget from DOM temporarily.
Inherited From:
Source:

removeIaController(id)

Unlink a controller with this component.
Parameters:
Name Type Description
id String Unique id of controller
Inherited From:
Source:

removeMenuItem(menuItem, doNotFinalize)

Remove a menu item.
Parameters:
Name Type Description
menuItem Kekule.Widget.MenuItem
doNotFinalize Bool
Inherited From:
Source:

removeStyleProperty(cssPropName, element)

Clear CSS property to widget or another element.
Parameters:
Name Type Description
cssPropName String CSS property name in JavaScript form.
element HTMLElement If not set, style will be set to widget element.
Inherited From:
Source:

removeWidget(widget, doNotFinalize)

Remove an widget from container and destroy it.
Parameters:
Name Type Description
widget Kekule.Widget.BaseWidget
doNotFinalize Bool If set to true, the widget will not be finalized.
Inherited From:
Source:

setDimension(width, height, suppressResize)

Set width and height of current widget. Width and height value can be number (how many pixels) or a CSS string value directly.
Parameters:
Name Type Description
width Variant
height Variant
suppressResize Bool If this value is true, resized method will not be called.
Inherited From:
Source:

setMouseCapture(capture)

Set or unset mouse capture feature of current widget.
Parameters:
Name Type Description
capture Bool
Inherited From:
Source:

setStyleProperty(cssPropName, value, element)

Set CSS property value to widget or another element.
Parameters:
Name Type Description
cssPropName String CSS property name in JavaScript form.
value Variant A simple css value or an instance of Kekule.Widget.StyleResource or a style resource name.
element HTMLElement If not set, style will be set to widget element. UNFINISHED yet
Inherited From:
Source:

show(caller, callback, showType,, extraOptions)

Make widget visible.
Parameters:
Name Type Description
caller Kekule.Widget.BaseWidget Who calls the show method and make this widget visible.
callback Func This callback function will be called when the widget is totally shown.
showType, Int value from Kekule.Widget.ShowHideType.
extraOptions Hash Extra transition options. It may contains a field "instantly". If this field is set to true, the showing process will be executed without transition.
Inherited From:
Source:

startObservingGestureEvents(eventNames)

Start observing gesture events.
Parameters:
Name Type Description
eventNames Array Events need to be observed.
Inherited From:
Source:

startPeriodicalExec(htmlEvent)

Begin periodical execution.
Parameters:
Name Type Description
htmlEvent Object HTML event that starts periodical execution.
Inherited From:
Source:

stopObservingGestureEvents(eventNames)

Stop observing gesture events.
Parameters:
Name Type Description
eventNames Array Events need to be stopped.
Inherited From:
Source:

stopPeriodicalExec()

Stop periodical execution.
Inherited From:
Source:

testMouseCursor(coord, e) → {Variant}

Get mouse cursor at a certain coord. Component can implement this function, or dispatch it to controllers.
Parameters:
Name Type Description
coord Hash 2D mouse coord
e Object event arg passed from mouse move event
Inherited From:
Source:
Returns:
CSS cursor property value. Return '' to use default one. The return value can also be a array of cursor key words, the first legal one in current browser will be used.
Type
Variant

toggleClassName(className, affectCustomProp)

Toggle class(es) from element. This method not also change customHtmlClassName property.
Parameters:
Name Type Description
className Variant Can be a simple name, or a series of name separated by space ('name1 name2') or an array of strings.
affectCustomProp Bool Whether change customHtmlClassName property of widget.
Inherited From:
Source:

unlinkStyleResource(resOrName, element)

Remove style resource from self or an element.
Parameters:
Name Type Description
resOrName Variant An instance of Kekule.Widget.StyleResource or resource name.
element HTMLElement If not set, style will be removed from widget element.
Inherited From:
Source:

updateDimensionTransform()

Update widget transform based on current dimension.
Inherited From:
Source:

widgetDomStateChanged(isInDom)

Called when widget is inserted in or removed from HTML page DOM.
Parameters:
Name Type Description
isInDom Bool
Inherited From:
Source:

Events

activate

Invoked when a widget is activated (such as mouse down or enter key down on button). event param of it has field: {widget}
Inherited From:
Source:

bind

Invoked when a widget object is bind to an HTML element. event param of it has fields: {widget, element}
Inherited From:
Source:

deactivate

Invoked when a widget is deactivated (such as mouse up or enter key up on button). event param of it has field: {widget}
Inherited From:
Source:

execute

Invoked when a widget is executed (such as click on button, select on menu and so on). event param of it has field: {widget}
Inherited From:
Source:

resize

Invoked when a widget's width or height changed. event param of it has field: {widget} Note: This event will only be invoked when using width/height property or setDimension method to change size. Set CSS styles directly will not fire this event.
Inherited From:
Source:

showStateChange

Invoked when a widget is shown or hidden. event param of it has field: {widget, isShown, isDismissed}
Inherited From:
Source:

unbind

Invoked when a widget object is unbind from an HTML element. event param of it has fields: {widget, element}
Inherited From:
Source: