zk
Class Widget

java.lang.Object
  extended by zk.Object
      extended by zk.Widget
Direct Known Subclasses:
Area, Colorbox, Colorpalette, Colorpicker, Desktop, Fusionchart, Layout, Macro, Native, Page, RefWidget, Script, Style, Timer, Widget

public class Widget
extends Object

A widget, i.e., an UI object. Each component running at the server is associated with a widget running at the client.

Refer to ZK Component Development Essentials and ZK Client-side Reference for more information.

Notice that, unlike the component at the server, Desktop and Page are derived from zk.Widget. It means desktops, pages and widgets are in a widget tree.


Field Summary
 Object $weave
          The weave controller that is used by ZK Weaver.
static int auDelay
          The default delay before sending an AU request when fire(_global_.String, zk.Object, _global_.Map, int) is called (and the server has an ARAP event listener registered).
 String autag
          The AU tag of this widget.
 int bindLevel
          The bind level (readonly) The level in the widget tree after this widget is bound to a DOM tree (bind_(zk.Desktop, zk.Skipper, _global_.Array)).
 String className
          The class name of the widget.
 Desktop desktop
          The desktop that this widget belongs to (readonly).
 Map effects_
          A map of objects that are associated with this widget, and they shall be removed when this widget is unbound (unbind(zk.Desktop, zk.Skipper)).
 Widget firstChild
          The first child, or null if no child at all (readonly).
 String id
          The identifier of this widget, or null if not assigned (readonly).
 boolean insertingBefore_
          Indicates an invocation of appendChild(zk.Widget, boolean) is made by insertBefore(zk.Widget, zk.Widget).
 boolean inServer
          Whether this widget has a peer component (readonly).
 Widget lastChild
          The last child, or null if no child at all (readonly).
 int nChildren
          The number of children (readonly).
 Widget nextSibling
          The next sibling, or null if this widget is the last child (readonly).
 Widget parent
          The parent, or null if this widget has no parent (readonly).
 Widget previousSibling
          The previous sibling, or null if this widget is the first child (readonly).
 String uuid
          The UUID.
 String widgetName
          The widget name of the widget.
 
Fields inherited from class zk.Object
$class, $oid
 
Method Summary
static Widget $(Object n, Map opts)
          Retrieves the widget.
 Map $f()
          Returns the map of all fellows of this widget.
 Widget $f(String id)
          Returns the fellow of the specified ID of the ID space that this widget belongs to.
 Widget $f(String id, boolean global)
          Returns the fellow of the specified ID of the ID space that this widget belongs to.
 void $init(Map props)
          The constructor.
 DOMElement $n()
          Returns the DOM element that this widget is bound to.
 DOMElement $n(String subId)
          Returns the child element of the DOM element(s) that this widget is bound to.
 Widget $o()
          Returns the owner of the ID space that this widget belongs to, or null if it doesn't belong to any ID space.
 String $s()
          Returns the sub zclass name that cache for this widget.
protected  void afterAnima_(boolean visible)
          Invoked after an animation (e.g., jqzk.slideDown(zk.Widget, _global_.Map)) has finished.
protected  void afterParentChanged_(Widget oldparent)
          A callback called after the parent has been changed.
 boolean appendChild(Widget child)
          Append a child widget.
 boolean appendChild(Widget child, boolean ignoreDom)
          Append a child widget with more control.
protected  void beforeParentChanged_(Widget newparent)
          A callback called before the parent is changed.
protected  void beforeSendAU_(Widget wgt, Event evt)
          Callback before sending an AU request.
protected  void bind_(Desktop dt, Skipper skipper, Array after)
          Callback when this widget is bound (aka., attached) to the DOM tree.
 Widget bind(Desktop dt, Skipper skipper)
          Binds this widget.
protected  void bindChildren_(Desktop dt, Skipper skipper, Array after)
          Binds the children of this widget.
protected  void bindDoubleTap_()
          Bind double click event to the widget on tablet device.
protected  void bindSwipe_()
          Bind swipe event to the widget on tablet device.
protected  void bindTapHold_()
          Bind right click event to the widget on tablet device.
 boolean canActivate(Map opts)
          Checks if this widget can be activated (gaining focus and so on).
protected  void cleanDrag_()
          Cleans up the widget to make it un-draggable.
 void clear()
          Removes all children.
 void clearCache()
          Clears the cached nodes (by $n(_global_.String)).
protected  DOMElement cloneDrag_(Draggable drag, Offset ofs)
          Called to create the visual effect representing what is being dragged.
protected  void deferRedraw_(Array out)
          Utilities for handling the so-called render defer (setRenderdefer(int)).
protected  void deferRedrawHTML_(Array out)
          Renders a fake DOM element that will replace with the correct element after the deferring time is up.
 void detach()
          Removes this widget (from its parent).
protected  void doBlur_(Event evt)
          A utility to simplify the listening of onBlur.
protected  void doClick_(Event evt)
          Called when the user clicks on a widget or a child widget.
protected  void doDoubleClick_(Event evt)
          Called when the user double-clicks on a widget or a child widget.
protected  void doFocus_(Event evt)
          A utility to simplify the listening of onFocus.
protected  void doKeyDown_(Event evt)
          Called when the user presses down a key when this widget has the focus (focus(int)).
protected  void doKeyPress_(Event evt)
          Called when the user presses a key when this widget has the focus (focus(int)).
protected  void doKeyUp_(Event evt)
          Called when the user presses up a key when this widget has the focus (focus(int)).
protected  String domAttrs_(Map no)
          Returns the HTML attributes that is used to generate DOM element of this widget.
protected  String domClass_(Map no)
          Returns the class name(s) used for the DOM element of this widget.
protected  Widget domListen_(DOMElement node, String evtnm, Object fn, String keyword)
          Registers an DOM event listener for the specified DOM element (aka., node).
protected  void doMouseDown_(Event evt)
          Called when the user presses down the mouse button on this widget (or one of its child widget).
protected  void doMouseEnter_(Event evt)
          Called when the user moves the mouse pointer on top of a widget (or one of its child widget).
protected  void doMouseLeave_(Event evt)
          Called when the user moves the mouse pointer out of a root widget.
protected  void doMouseMove_(Event evt)
          Called when the user moves the mouse pointer over this widget (or one of its child widget).
protected  void doMouseOut_(Event evt)
          Called when the user moves the mouse pointer out of a widget (or one of its child widget).
protected  void doMouseOver_(Event evt)
          Called when the user moves the mouse pointer on top of a widget (or one of its child widget).
protected  void doMouseUp_(Event evt)
          Called when the user presses up the mouse button on this widget (or one of its child widget).
protected  String domStyle_(Map no)
          Returns the style used for the DOM element of this widget.
protected  String domTextStyleAttr_()
          Returns the style attribute that contains only the text related CSS styles.
protected  String domTooltiptext_()
          Returns the tooltiptext for generating the title attribute of the DOM element.
protected  Widget domUnlisten_(DOMElement node, String evtnm, Object fn, String keyword)
          Un-registers an event listener for the specified DOM element (aka., node).
protected  void doResizeScroll_()
          Resize zul.Scrollbar size after child added/removed or hide/show.
protected  void doRightClick_(Event evt)
          Called when the user right-clicks on a widget or a child widget.
protected  void doSelect_(Event evt)
          Called when the user clicks or right-clicks on widget or a child widget.
protected  void doSwipe_(Event evt)
          Called when the user swipe left/right/up/down this widget.
protected  void doTooltipOut_()
          Called when the mouse is moved out of this widget.
protected  void doTooltipOver_()
          Called when the mouse is moved over this widget.
protected  void dropEffect_(boolean over)
          Called to have some visual effect when the user is dragging a widget over this widget and this widget is droppable.
protected  void extraBind_(String uuid, boolean add)
          Associates UUID with this widget.
 Event fire(String evtnm, Object data, Map opts, int timeout)
          Fire a widget event.
 Event fireX(Event evt, int timeout)
          Fire a widget event.
protected  boolean focus_(int timeout)
          Called by focus(int) to set the focus.
 boolean focus(int timeout)
          Sets the focus to this widget.
 void forcerender()
          Forces the rendering if it is deferred.
 Offset fromPageCoord(int x, int y)
          Converts a coordinate related to the browser window into the coordinate related to this widget.
 Object get(String name)
          Retrieves a value from the specified property.
 String getAction()
          Returns the client-side action.
 DOMElement getCaveNode()
          Called by insertChildHTML_(zk.Widget, zk.Widget, zk.Desktop) to to find the location to place the DOM element of the child.
 Widget getChildAt(int j)
          Return the child widget at the specified index.
 int getChildIndex()
          Returns the child index of this widget.
static Class getClass(String wgtnm)
          Returns the class of the specified widget's name.
 String getDraggable()
          Returns the identifier of a draggable type for this widget, or null if not draggable.
protected  String getDragMessage_()
          Returns the message to show when an user is dragging this widget, or null if it prefers to clone the widget with cloneDrag_(zk.Draggable, _global_.Offset).
 DOMElement getDragNode()
          Returns the DOM element of this widget that can be dragged.
protected  Map getDragOptions_(Map map)
          Returns the options used to instantiate Draggable.
protected  Widget getDrop_(Widget dragged)
          Returns the widget if it allows to drop the specified widget (being dragged), or null if not allowed.
 String getDroppable()
          Returns the identifier, or a list of identifiers of a droppable type for this widget, or null if not droppable.
static Array getElementsById(String id)
          Returns all elements with the given ID.
static Array getElementsByName(String name)
          Returns all elements with the given widget name.
protected  DOMElement getFirstNode_()
          Returns the first DOM element of this widget.
protected  void getFloatZIndex_(DOMElement node)
          Returns the z-index of a floating widget.
 String getHeight()
          Returns the height of this widget.
 String getHflex()
          Return horizontal flex hint of this widget.
 String getId()
          Returns the identifier of this widget, or null if not assigned.
 String getLeft()
          Returns the left of this widget.
 String getMold()
          Returns this widget's mold.
protected  void getOldWidget_(DOMElement n)
          Returns the widget associated with the given node element.
 Page getPage()
          Returns the page that this widget belongs to, or null if there is no page available.
 int getRenderdefer()
          Returns the number of milliseconds before rendering this component at the client.
 String getSclass()
          Returns the CSS class of this widget.
 int getScrollLeft()
          Returns the scoll left of the associated DOM element of this widget.
 int getScrollTop()
          Returns the scoll top of the associated DOM element of this widget.
 String getStyle()
          Returns the CSS style of this widget
 DOMElement getTextNode()
          Returns the DOM element that is used to hold the text, or null if this widget doesn't show any text.
 String getTooltiptext()
          Returns the tooltip text of this widget.
 String getTop()
          Returns the top of this widget.
 Widget getTopWidget()
          Returns the top widget, which is the first floating ancestor, or null if no floating ancestor.
 String getVflex()
          Returns vertical flex hint of this widget.
 String getWidth()
          Returns the width of this widget.
 String getZclass()
          Returns the ZK Cascading Style class(es) for this widget.
 int getZIndex()
          Returns the Z index.
 Widget hide()
          Makes this widget invisible.
protected  boolean ignoreDescendantFloatUp_()
          A widget call this function of its ancestor if it wants to know whether its ancestor prefer ignore float up event of it self.
protected  boolean ignoreDrag_(Draggable pt)
          Returns if the location that an user is trying to drag is allowed.
protected  void initDrag_()
          Initializes the widget to make it draggable.
 boolean insertBefore(Widget child, Widget sibling)
          Inserts a child widget before the reference widget (the sibling argument).
protected  void insertChildHTML_(Widget child, Widget before, Desktop desktop)
          Inserts the HTML content generated by the specified child widget before the reference widget (the before argument).
static boolean isAutoId(String uuid)
          Deprecated. we cannot really detect at the client if UUID is generated automatically.
 boolean isBinding()
          Returns whether this widget is being bound to DOM.
protected  boolean isFloating_()
          Returns if this widget is floating.
 boolean isListen(String evtnm, Map opts)
          Returns if a listener is registered for the specified event.
 boolean isRealElement()
          Returns whether the widget has its own element bound to HTML DOM tree.
 boolean isRealVisible()
          Returns if this widget is really visible, i.e., all ancestor widget and itself are visible.
 boolean isRealVisible(Map opts)
          Returns if this widget is really visible, i.e., all ancestor widget and itself are visible.
 boolean isVisible()
          Returns if this widget is visible
 boolean isVisible(boolean strict)
          Returns if this widget is visible
protected  boolean isWatchable_(String name, Widget p, Map cache)
          Returns if the given watch shall be fired for this widget.
 Widget listen(Map infos, int priority)
          Registers listener(s) to the specified event.
protected  void listenOnFitSize_()
          Listens to onFitSize event.
protected static void mimicMouseDown_(Widget wgt, boolean noFocusChange, int which)
          Called to mimic the mouse down event fired by the browser.
static Widget newInstance(String wgtnm, Map props)
          Creates a widget by specifying the widget name.
static String nextUuid()
          Returns the next unique UUID for a widget.
 void onAfterSize()
          Called to fire the onAfterSize event.
protected  void onChildAdded_(Widget child)
          A callback called after a child has been added to this widget.
protected  void onChildRemoved_(Widget child)
          A callback called after a child has been removed to this widget.
protected  void onChildRenderDefer_(Widget child)
          A callback called after a child has been delay rendered.
protected  void onChildReplaced_(Widget oldc, Widget newc)
          A callback called after a child has been replaced.
protected  void onChildVisible_(Widget child)
          A callback called after a child's visibility is changed (i.e., setVisible(boolean) was called).
protected  void onDrop_(Draggable drag, Event evt)
          Called to fire the onDrop event.
 void redraw(Array out)
          Generates the HTML fragment for this widget.
protected  String redrawHTML_(Skipper skipper, boolean trim)
          Returns the HTML fragment of this widget.
static void register(String clsnm, boolean blankPreserved)
          Registers a widget class.
 boolean removeChild(Widget child)
          Removes a child.
 boolean removeChild(Widget child, boolean ignoreDom)
          Removes a child with more control.
protected  void removeChildHTML_(Widget child, boolean ignoreDom)
          Removes the corresponding DOM content of the specified child.
protected  void removeHTML_(Array n)
          Removes the HTML DOM content.
protected  void replaceCavedChildren_(String subId, Array wgts, String tagBeg, String tagEnd)
          Replaced the child widgets with the specified widgets.
protected  void replaceChildHTML_(Widget child, DOMElement n, Desktop dt, Skipper skipper)
          Replaces the DOM element(s) of the specified child widget.
 Widget replaceHTML(Object n, Desktop desktop, Skipper skipper)
          Replaces the specified DOM element with the HTML content generated this widget.
 void replaceWidget(Widget newwgt)
          Replaces this widget with the specified one.
 Widget rerender(int timeout)
          Re-renders after the specified time (milliseconds).
 Widget rerender(Skipper skipper)
          Re-renders the DOM element(s) of this widget.
 Widget scrollIntoView()
          Makes this widget visible in the browser window by scrolling ancestors up or down, if necessary.
protected  void sendAU_(Event evt, int timeout)
          Sends an AU request to the server.
 Widget set(String name, Object value)
          Sets a property.
 Widget set(String name, Object value, Object extra)
          Sets a property.
 void setAction(String action)
          Sets the client-side action.
 Widget setChildren(Array children)
          Appends an array of children.
protected  void setDomVisible_(DOMElement n, boolean visible, Map opts)
          Changes the visibility of a child DOM content of this widget.
 Widget setDraggable(String draggable)
          Sets the identifier of a draggable type for this widget.
 Widget setDroppable(String droppable)
          Sets the identifier, or a list of identifiers of a droppable type for this widget.
protected  Widget setFloating_(boolean floating, Map opts)
          Sets a status to indicate if this widget is floating.
protected  void setFloatZIndex_(DOMElement node, int zi)
          Sets the z-index for a floating widget.
 Widget setHeight(String height)
          Sets the height of this widget.
 void setHflex(String flex)
          Sets horizontal flexibility hint of this widget.
 Widget setId(String id)
          Sets the identifier of this widget.
 Widget setLeft(String left)
          Sets the left of this widget.
 void setListener(Array inf)
          Sets a listener that can be unlistened easily.
 void setListener(String evt, Function fn)
          Sets a listener It is designed to be called from server.
 void setListeners(Map infos)
          Sets the listener a map of listeners.
 Widget setMold(String mold)
          Sets this widget's mold.
 void setRenderdefer(int ms)
          Sets the number of milliseconds before rendering this component at the client.
 Widget setSclass(String sclass)
          Sets the CSS class of this widget.
 Widget setScrollLeft(int the)
          Sets the scoll left of the associated DOM element of this widget.
 Widget setScrollTop(int the)
          Sets the scoll top of the associated DOM element of this widget.
 Widget setStyle(String style)
          Sets the CSS style of this widget.
 Widget setTooltiptext(String title)
          Sets the tooltip text of this widget.
 Widget setTop(String top)
          Sets the top of this widget.
 int setTopmost()
          Makes this widget as topmost.
 void setVflex(String flex)
          Sets vertical flexibility hint of this widget.
 Widget setVisible(boolean visible)
          Sets whether this widget is visible.
 Widget setWidth(String width)
          Sets the width of this widget.
 Widget setZclass(String zclass)
          Sets the ZK Cascading Style class(es) for this widget.
 Widget setZIndex(int zIndex, Map opts)
          Sets the Z index.
protected  boolean shallChildROD_()
          Returns whether a new child shall be ROD.
protected  boolean shallIgnoreClick_(Event the)
          Check whether to ignore the click which might be caused by doClick_(zk.Event) doRightClick_(zk.Event), or doDoubleClick_(zk.Event).
 Widget show()
          Makes this widget visible.
 Widget smartUpdate(String name, Object value, int timeout)
          Smart-updates a property of the peer component associated with this widget, running at the server, with the specified value.
protected  void unbind_(Skipper skipper, Array after)
          Callback when a widget is unbound (aka., detached) from the DOM tree.
 Widget unbind(Desktop dt, Skipper skipper)
          Unbinds this widget.
protected  void unbindChildren_(Skipper skipper, Array after)
          Unbinds the children of this widget.
protected  void unbindDoubleTap_()
          Unbind double click event to the widget on tablet device.
protected  void unbindSwipe_()
          Unbind swipe event to the widget on tablet device.
protected  void unbindTapHold_()
          Unbind right click event to the widget on tablet device.
protected  void uncloneDrag_(Draggable drag)
          Undo the visual effect created by cloneDrag_(zk.Draggable, _global_.Offset).
 Widget unlisten(Map infos)
          Removes a listener from the sepcified event.
protected  void unlistenOnFitSize_()
          Unlistens to onFitSize event.
protected  void updateDomClass_()
          Updates the DOM element's CSS class.
protected  void updateDomStyle_()
          Updates the DOM element's style.
static String uuid(String subId)
          Converts an ID of a DOM element to UUID.
 void zsync(Map opts)
          Synchronizes a map of objects that are associated with this widget, and they shall be resized when the size of this widget is changed.
 
Methods inherited from class zk.Object
$init, $instanceof, $super, $super, $supers, $supers, afterInit, isAssignableFrom, isInstance, proxy
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

nChildren

public int nChildren
The number of children (readonly).


bindLevel

public int bindLevel
The bind level (readonly) The level in the widget tree after this widget is bound to a DOM tree (bind_(zk.Desktop, zk.Skipper, _global_.Array)). For example, a widget's bind level is one plus the parent widget's

It starts at 0 if it is the root of the widget tree (a desktop, zk.Desktop), then 1 if a child of the root widget, and son on. Notice that it is -1 if not bound.

It is mainly useful if you want to maintain a list that parent widgets is in front of (or after) child widgets. bind level.


className

public String className
The class name of the widget. For example, zk.Widget's class name is "zk.Widget", while zul.wnd.Window's "zul.wnd.Window".

Notice that it is available if a widget class is loaded by WPD loader (i.e., specified in zk.wpd). If you create a widget class dynamically, you have to invoke register(_global_.String, boolean) to make this member available. On the other hand, Object.$class is available for all objects extending from Object.

See Also:
widgetName

widgetName

public String widgetName
The widget name of the widget. It is the same as this.className.substring(this.className.lastIndexOf('.') + 1).toLowerCase(). For example, if className is zul.wnd.Window, then widgetName is window.

Notice that className is unique while widgetName is not necessary unique.

Since:
5.0.2
See Also:
className

autag

public String autag
The AU tag of this widget. The AU tag tag is used to tag the AU requests sent by the peer widget. For instance, if the AU tag is xxx,yyy and the desktop's request path (Desktop.requestPath) is /foo.zul, then the URL of the AU request will contain /_/foo.zul/xxx,yyy,.

Default: null.

Since:
6.0.0

firstChild

public Widget firstChild
The first child, or null if no child at all (readonly).

See Also:
getChildAt(int)

lastChild

public Widget lastChild
The last child, or null if no child at all (readonly).

See Also:
getChildAt(int)

parent

public Widget parent
The parent, or null if this widget has no parent (readonly).


nextSibling

public Widget nextSibling
The next sibling, or null if this widget is the last child (readonly).


previousSibling

public Widget previousSibling
The previous sibling, or null if this widget is the first child (readonly).


desktop

public Desktop desktop
The desktop that this widget belongs to (readonly). It is set when it is bound to the DOM tree.

Notice it is always non-null if bound to the DOM tree, while $n() is always non-null if bound. For example, Timer.

It is readonly, and set automcatically when bind_(zk.Desktop, zk.Skipper, _global_.Array) is called.


id

public String id
The identifier of this widget, or null if not assigned (readonly). It is the same as getId().

To change the value, use setId(_global_.String). the ID


inServer

public boolean inServer
Whether this widget has a peer component (readonly). It is set if a widget is created automatically to represent a component ( at the server. On the other hand, it is false if a widget is created by the client application (by calling, say, new zul.inp.Textox()).


uuid

public String uuid
The UUID. Don't change it if it is bound to the DOM tree, or inServer is true. Developers rarely need to modify it since it is generated automatically.


insertingBefore_

public boolean insertingBefore_
Indicates an invocation of appendChild(zk.Widget, boolean) is made by insertBefore(zk.Widget, zk.Widget).


effects_

public Map effects_
A map of objects that are associated with this widget, and they shall be removed when this widget is unbound (unbind(zk.Desktop, zk.Skipper)).

The key must be an unique name of the object, while the value must be an object that implement the destroy method.

When unbind_(zk.Skipper, _global_.Array) is called, destroy() is called for each object stored in this map. Furthermore, if the visibility of this widget is changed, and the object implements the sync method, then sync() will be called. Notice that the sync method is optional. It is ignored if not implemented.

It is useful if you implement an effect, such as shadow, mask and error message, that is tightly associated with a widget.


$weave

public Object $weave
The weave controller that is used by ZK Weaver. It is not null if it is created and controlled by ZK Weaver. In other words, it is called in the Design Mode if $weave is not null.


auDelay

public static int auDelay
The default delay before sending an AU request when fire(_global_.String, zk.Object, _global_.Map, int) is called (and the server has an ARAP event listener registered).

Default: 38 (Unit: miliseconds).

Since:
5.0.8
Method Detail

getMold

public String getMold()
Returns this widget's mold. A mold is a template to render a widget. In other words, a mold represents a visual presentation of a widget. Depending on implementation, a widget can have multiple molds.

Returns:
String

setMold

public Widget setMold(String mold)
Sets this widget's mold. A mold is a template to render a widget. In other words, a mold represents a visual presentation of a widget. Depending on implementation, a widget can have multiple molds.

Default: default

Parameters:
mold - the mold
Returns:
zk.Widget this widget

getStyle

public String getStyle()
Returns the CSS style of this widget

Returns:
String
See Also:
setStyle(_global_.String), getSclass(), getZclass()

setStyle

public Widget setStyle(String style)
Sets the CSS style of this widget.

Default: null

Parameters:
style - the CSS style
Returns:
zk.Widget this widget
See Also:
getStyle(), setSclass(_global_.String), setZclass(_global_.String)

getSclass

public String getSclass()
Returns the CSS class of this widget.

Returns:
String
See Also:
setSclass(_global_.String), getZclass(), getStyle()

setSclass

public Widget setSclass(String sclass)
Sets the CSS class of this widget.

Default: null.

The default styles of ZK components doesn't depend on sclass at all. Rather, setSclass is provided to perform small adjustment, e.g., changing only the font size. In other words, the default style is still applied if you change sclass.

To replace the default style completely, use setZclass(_global_.String) instead.

The real CSS class is a concatenation of getZclass() and getSclass().

Parameters:
sclass - the style class
Returns:
zk.Widget this widget
See Also:
getSclass(), setZclass(_global_.String), setStyle(_global_.String)

getZclass

public String getZclass()
Returns the ZK Cascading Style class(es) for this widget.

Returns:
String
See Also:
setZclass(_global_.String), getSclass(), getStyle()

setZclass

public Widget setZclass(String zclass)
Sets the ZK Cascading Style class(es) for this widget. It is the CSS class used to implement a mold of this widget. n implementation It usually depends on the implementation of the mold (getMold()).

Default: null but an implementation usually provides a default class, such as z-button.

Calling setZclass with a different value will completely replace the default style of a widget. Once you change it, all default styles are gone. If you want to perform small adjustments, use setSclass(_global_.String) instead.

The real CSS class is a concatenation of getZclass() and getSclass().

Parameters:
zclass - the style class used to apply the whote widget.
Returns:
zk.Widget this widget
See Also:
getZclass(), setSclass(_global_.String), setStyle(_global_.String)

getWidth

public String getWidth()
Returns the width of this widget.

Returns:
String
See Also:
getHeight()

setWidth

public Widget setWidth(String width)
Sets the width of this widget.

Parameters:
width - the width. Remember to specify 'px', 'pt' or '%'. An empty or null value means "auto"
Returns:
zk.Widget this widget

getHeight

public String getHeight()
Returns the height of this widget.

Returns:
String
See Also:
getWidth()

setHeight

public Widget setHeight(String height)
Sets the height of this widget.

Parameters:
height - the height. Remember to specify 'px', 'pt' or '%'. An empty or null value means "auto"
Returns:
zk.Widget this widget

getLeft

public String getLeft()
Returns the left of this widget.

Returns:
String
See Also:
getTop()

setLeft

public Widget setLeft(String left)
Sets the left of this widget.

Parameters:
left - the left. Remember to specify 'px', 'pt' or '%'. An empty or null value means "auto"
Returns:
zk.Widget this widget

getTop

public String getTop()
Returns the top of this widget.

Returns:
String
See Also:
getLeft()

setTop

public Widget setTop(String top)
Sets the top of this widget. If you want to specify bottom, use setStyle(_global_.String) instead. For example, setStyle("bottom: 0px");

Parameters:
top - the top. Remember to specify 'px', 'pt' or '%'. An empty or null value means "auto"
Returns:
zk.Widget this widget

getTooltiptext

public String getTooltiptext()
Returns the tooltip text of this widget.

Returns:
String

setTooltiptext

public Widget setTooltiptext(String title)
Sets the tooltip text of this widget.

Default implementation of setTooltiptext: update the title attribute of $n(_global_.String)

Parameters:
title - the tooltip text
Returns:
zk.Widget this widget

getDroppable

public String getDroppable()
Returns the identifier, or a list of identifiers of a droppable type for this widget, or null if not droppable.

Returns:
String

setDroppable

public Widget setDroppable(String droppable)
Sets the identifier, or a list of identifiers of a droppable type for this widget.

Default: null

The simplest way to make a component droppable is to set this attribute to "true". To disable it, set this to "false" (or null).

If there are several types of draggable objects and this widget accepts only some of them, you could assign a list of identifiers that this widget accepts, separated by comma.

For example, if this component accpets dg1 and dg2, then assign "dg1, dg2" to this attribute.

Parameters:
droppable - "false", null or "" to denote not-droppable; "true" for accepting any draggable types; a list of identifiers, separated by comma for identifiers of draggables this widget accept (to be dropped in).
Returns:
zk.Widget this widget

setVflex

public void setVflex(String flex)
Sets vertical flexibility hint of this widget.

The parameter flex is a number in String type indicating how this widget's parent container distributes remaining empty space among its children widget vertically. Flexible widget grow and shrink to fit their given space. Flexible widget with larger flex values will be made larger than widget with lower flex values, at the ratio determined by all flexible widgets. The actual flex value is not relevant unless there are other flexible widget within the same parent container. Once the default sizes of widget in a parent container are calculated, the remaining space in the parent container is divided among the flexible widgets, according to their flex ratios.

Specify a flex value of negative value, 0, or "false" has the same effect as leaving the flex attribute out entirely. Specify a flex value of "true" has the same effect as a flex value of 1.

Special flex hint, "min", indicates that the minimum space shall be given to this flexible widget to enclose all of its children widgets. That is, the flexible widget grow and shrink to fit its children widgets.

Parameters:
flex - the vertical flex hint.
See Also:
setHflex(_global_.String), getVflex()

getVflex

public String getVflex()
Returns vertical flex hint of this widget.

Returns:
String vertical flex hint of this widget.
See Also:
setVflex(_global_.String)

getHflex

public String getHflex()
Return horizontal flex hint of this widget.

Returns:
String horizontal flex hint of this widget.
See Also:
setHflex(_global_.String)

setHflex

public void setHflex(String flex)
Sets horizontal flexibility hint of this widget.

The parameter flex is a number in String type indicating how this widget's parent container distributes remaining empty space among its children widget horizontally. Flexible widget grow and shrink to fit their given space. Flexible widget with larger flex values will be made larger than widget with lower flex values, at the ratio determined by all flexible widgets. The actual flex value is not relevant unless there are other flexible widget within the same parent container. Once the default sizes of widget in a parent container are calculated, the remaining space in the parent container is divided among the flexible widgets, according to their flex ratios.

Specify a flex value of negative value, 0, or "false" has the same effect as leaving this flex attribute out entirely. Specify a flex value of "true" has the same effect as a flex value of 1.

Special flex hint, "min", indicates that the minimum space shall be given to this flexible widget to enclose all of its children widgets. That is, the flexible widget grow and shrink to fit its children widgets.

Parameters:
flex - the horizontal flex hint.
See Also:
setVflex(_global_.String), getHflex()

setRenderdefer

public void setRenderdefer(int ms)
Sets the number of milliseconds before rendering this component at the client.

Default: -1 (don't wait).

This method is useful if you have a sophiscated page that takes long to render at a slow client. You can specify a non-negative value as the render-defer delay such that the other part of the UI can appear earlier. The styling of the render-deferred widget is controlled by a CSS class called z-render-defer.

Notice that it has no effect if the component has been rendered at the client.

Parameters:
ms - time to wait in milliseconds before rendering. Notice: 0 also implies deferring the rendering (just right after all others are renderred).
Since:
5.0.2

getRenderdefer

public int getRenderdefer()
Returns the number of milliseconds before rendering this component at the client.

Default: -1 (don't wait).

Returns:
int the number of milliseconds to wait
Since:
5.0.2

setAction

public void setAction(String action)
Sets the client-side action.

Default: null (no CSA at all)

The format:
action1: action-effect1; action2: action-effect2

Currently, only two actions are show and hide. They are called when the widget is becoming visible (show) and invisible (hide).

The action effect (action-effect1) is the name of a method defined in zk.eff.Actions, such as show: slideDown; hide: slideUp

Parameters:
action - the cient-side action
Since:
5.0.6

getAction

public String getAction()
Returns the client-side action.

Returns:
String the client-side action
Since:
5.0.6

$init

public void $init(Map props)
The constructor. For example,

new zul.wnd.Window({
  border: 'normal',
  title: 'Hello World',
  closable: true
});

Parameters:
props - the properties to be assigned to this widget.

afterAnima_

protected void afterAnima_(boolean visible)
Invoked after an animation (e.g., jqzk.slideDown(zk.Widget, _global_.Map)) has finished. You could override to clean up anything related to animation. Notice that, if you override, you have to call back this method.

Parameters:
visible - whether the result of the animation will make the DOM element visible
Since:
5.0.6

setDraggable

public Widget setDraggable(String draggable)
Sets the identifier of a draggable type for this widget.

Default: null

The simplest way to make a widget draggable is to set this property to "true". To disable it, set this to "false" (or null). If there are several types of draggable objects, you could assign an identifier for each type of draggable object. The identifier could be anything but empty and "false".

Parameters:
draggable - "false", "" or null to denote non-draggable; "true" for draggable with anonymous identifier; others for an identifier of draggable.
Returns:
zk.Widget this widget

getDraggable

public String getDraggable()
Returns the identifier of a draggable type for this widget, or null if not draggable.

Returns:
String

$o

public Widget $o()
Returns the owner of the ID space that this widget belongs to, or null if it doesn't belong to any ID space.

Notice that, if this widget is an ID space owner, this method returns itself.

Returns:
zk.Widget

$f

public Widget $f(String id,
                 boolean global)
Returns the fellow of the specified ID of the ID space that this widget belongs to. It returns null if not found.

Parameters:
id - the widget's ID (id)
global - whether to search all ID spaces of this desktop. If true, it first search its own ID space, and then the other Id spaces in this browser window (might have one or multiple desktops). If omitted, it won't search all ID spaces.
Returns:
zk.Widget

$f

public Widget $f(String id)
Returns the fellow of the specified ID of the ID space that this widget belongs to. It returns null if not found.

Parameters:
id - the widget's ID (id)
Returns:
zk.Widget

$f

public Map $f()
Returns the map of all fellows of this widget.

wgt.$f().main.setTitle("foo");

Returns:
Map the map of all fellows.
Since:
5.0.2

getId

public String getId()
Returns the identifier of this widget, or null if not assigned. It is the same as id.

Returns:
String the ID

setId

public Widget setId(String id)
Sets the identifier of this widget.

Parameters:
id - the identifier to assigned to.
Returns:
zk.Widget this widget

set

public Widget set(String name,
                  Object value,
                  Object extra)
Sets a property. The property updates sent from the server, including renderProperties and smartUpdate, will invoke this method.

Parameters:
name - the name of property. Refer to set(String, Object) for special names.
value - the value
extra - the extra argument. It could be anything.
Returns:
zk.Widget this widget

set

public Widget set(String name,
                  Object value)
Sets a property. The property updates sent from the server, including renderProperties and smartUpdate, will invoke this method.

Special Names

onXxx

If the name starts with on, it is assumed to be an event listener and setListener(_global_.String, _global_.Function) will be called.

$onXxx

If the name starts with $on, the value is assumed to be a boolean indicating if the server registers a listener.

$$onXxx

If the name starts with $$on, it indicates the event is an important event that the client must send it back to the server. In additions, the value is assumed to be a boolean indicating if the server registers a listener.

Special Value

{$u: uuid}

If the value is in this format, it indicates $u's value is UUID of a widget, and it will be resolved to a widget before calling the real method.

However, since we cannot resolve a widget by its UUID until the widget is bound (to DOM). Thus, ZK sets property after mounted. For example, wgt.set("radiogroup", {$u: uuid}) is equivalent to the following.

zk.afterMount(function () {
         wgt.set("radiogroup", zk.Widget.$(uuid))
});

Parameters:
name - the name of property.
value - the value
Returns:
zk.Widget this widget

get

public Object get(String name)
Retrieves a value from the specified property.

Parameters:
name - the name of property.
Returns:
Object the value of the property
Since:
5.0.2

getChildAt

public Widget getChildAt(int j)
Return the child widget at the specified index.

Notice this method is not good if there are a lot of children since it iterates all children one by one.

Parameters:
j - the index of the child widget to return. 0 means the first child, 1 for the second and so on.
Returns:
zk.Widget the widget or null if no such index
See Also:
getChildIndex()

getChildIndex

public int getChildIndex()
Returns the child index of this widget. By child index we mean the order of the child list of the parent. For example, if this widget is the parent's first child, then 0 is returned.

Notice that getChildAt(int) is called against the parent, while this method called against the child. In other words, w.parent.getChildAt(w.getChildIndex()) returns w.

Notice this method is not good if there are a lot of children since it iterates all children one by one.

Returns:
int the child index

setChildren

public Widget setChildren(Array children)
Appends an array of children. Notice this method does NOT remove any existent child widget.

Parameters:
children - an array of children (Widget) to add
Returns:
zk.Widget this widget

appendChild

public boolean appendChild(Widget child,
                           boolean ignoreDom)
Append a child widget with more control. It is similar to appendChild(zk.Widget) except the caller could prevent it from generating DOM element. It is usually used with rerender(int).

Parameters:
child - the child widget to add
ignoreDom - whether not to generate DOM elements
Returns:
boolean whether the widget was added successfully. It returns false if the child is always the last child (lastChild).
See Also:
appendChild(zk.Widget), insertBefore(zk.Widget, zk.Widget)

appendChild

public boolean appendChild(Widget child)
Append a child widget. The child widget will be attached to the DOM tree automatically, if this widget has been attached to the DOM tree, unless this widget is Desktop. In other words, you have to attach child widgets of Desktop manually (by use of, say, replaceHTML(zk.Object, zk.Desktop, zk.Skipper)).

Subclass Note

Parameters:
child - the child widget to add
Returns:
boolean whether the widget was added successfully. It returns false if the child is always the last child (lastChild).
See Also:
insertBefore(zk.Widget, zk.Widget)

shallChildROD_

protected boolean shallChildROD_()
Returns whether a new child shall be ROD.

Default: return true if child.z_rod or this.z_rod

Returns:
boolean whether a new child shall be ROD.
Since:
5.0.1

insertBefore

public boolean insertBefore(Widget child,
                            Widget sibling)
Inserts a child widget before the reference widget (the sibling argument).

Subclass Note


removeChild

public boolean removeChild(Widget child,
                           boolean ignoreDom)
Removes a child with more control. It is similar to removeChild(zk.Widget) except the caller could prevent it from removing the DOM element.

Notice that the associated DOM elements and unbind_(zk.Skipper, _global_.Array) is called first (i.e., called before beforeParentChanged_(zk.Widget), modifying the widget tree, ID space, and onChildRemoved_(zk.Widget)).

Parameters:
child - the child to remove.
ignoreDom - whether to remove the DOM element
Returns:
boolean whether it is removed successfully.
See Also:
detach(), clear()

removeChild

public boolean removeChild(Widget child)
Removes a child.

Parameters:
child - the child to remove.
Returns:
boolean whether it is removed successfully.
See Also:
detach(), clear()

detach

public void detach()
Removes this widget (from its parent). If it was attached to a DOM tree, the associated DOM elements will be removed, too.

See Also:
removeChild(zk.Widget, boolean)

clear

public void clear()
Removes all children.


replaceWidget

public void replaceWidget(Widget newwgt)
Replaces this widget with the specified one. The parent and siblings of this widget will become the parent and siblings of the specified one.

Notice that replaceHTML(zk.Object, zk.Desktop, zk.Skipper) is used to replace a DOM element that usually doesn't not belong to any widget. And, replaceWidget(zk.Widget) is used to replace the widget, and it maintains both the widget tree and the DOM tree.

Parameters:
newwgt - the new widget that will replace this widget.
Since:
5.0.1
See Also:
replaceHTML(zk.Object, zk.Desktop, zk.Skipper)

replaceCavedChildren_

protected void replaceCavedChildren_(String subId,
                                     Array wgts,
                                     String tagBeg,
                                     String tagEnd)
Replaced the child widgets with the specified widgets. It is usefull if you want to replace a part of children whose DOM element is a child element of subId (this.$n(subId)).

Note: it assumes this.$n(subId) exists.

Parameters:
subId - the ID of the cave that contains the child widgets to replace with.
wgts - an arrray of widgets that will become children of this widget
tagBeg - the beginning of HTML tag, such as &tl;tbody>. Ignored if null.
tagEnd - the ending of HTML tag, such as </tbody> Ignored if null.
See Also:
zAu.createWidgets(_global_.Array, _global_.Function, _global_.Function)

isRealVisible

public boolean isRealVisible(Map opts)
Returns if this widget is really visible, i.e., all ancestor widget and itself are visible.

Parameters:
opts - [optional] the options. Allowed values:
  • dom - whether to check DOM element instead of isVisible(boolean)
  • until - specifies the ancestor to search up to (included). If not specified, this method searches all ancestors. If specified, this method searches only this widget and ancestors up to the specified one (included).
  • strict - whether to check DOM element's style.visibility. It is used only if dom is also specified.
  • cache - a map of cached result (since 5.0.8). Ignored if null. If specified, the result will be stored and used to speed up the processing.
Returns:
boolean
See Also:
isVisible(boolean)

isRealVisible

public boolean isRealVisible()
Returns if this widget is really visible, i.e., all ancestor widget and itself are visible.

Returns:
boolean
See Also:
isVisible(boolean)

isVisible

public boolean isVisible(boolean strict)
Returns if this widget is visible

Parameters:
strict - whether to check the visibility of the associated DOM element. If true, this widget and the associated DOM element must be both visible.
Returns:
boolean
See Also:
isRealVisible(_global_.Map), jqzk.isVisible(boolean), setVisible(boolean)

isVisible

public boolean isVisible()
Returns if this widget is visible

Returns:
boolean
See Also:
isRealVisible(_global_.Map), jqzk.isVisible(boolean)

setVisible

public Widget setVisible(boolean visible)
Sets whether this widget is visible.

Subclass Notes

Parameters:
visible - whether to be visible
Returns:
zk.Widget this widget

zsync

public void zsync(Map opts)
Synchronizes a map of objects that are associated with this widget, and they shall be resized when the size of this widget is changed.

It is useful to sync the layout, such as shadow, mask and error message, that is tightly associated with a widget.

Parameters:
opts - the options, or undefined if none of them specified. Allowed values:

show

public Widget show()
Makes this widget visible. It is a shortcut of setVisible(true)

Returns:
zk.Widget this widget

hide

public Widget hide()
Makes this widget invisible. It is a shortcut of setVisible(false)

Returns:
zk.Widget this widget

setDomVisible_

protected void setDomVisible_(DOMElement n,
                              boolean visible,
                              Map opts)
Changes the visibility of a child DOM content of this widget. It is called by setVisible(boolean) to really change the visibility of the associated DOM elements.

Default: change n.style.display directly.

Parameters:
n - the element (never null)
visible - whether to make it visible
opts - [optional] the options. If omitted, {display:true} is assumed. Allowed value:
  • display - Modify n.style.display
  • visibility - Modify n.style.visibility

onChildReplaced_

protected void onChildReplaced_(Widget oldc,
                                Widget newc)
A callback called after a child has been replaced. Unlike onChildAdded_(zk.Widget) and onChildRemoved_(zk.Widget), this method is called only if AuCmd1.outer(zk.Widget, _global_.String). And if this method is called, neither onChildAdded_(zk.Widget) nor onChildRemoved_(zk.Widget) will be called.

Default: invoke onChildRemoved_(zk.Widget) and then onChildAdded_(zk.Widget). Furthermore, it sets this.childReplacing_ to true before invoking onChildRemoved_(zk.Widget) and onChildAdded_(zk.Widget), so we can optimize the code (such as rerender only once) by checking its value.

Parameters:
oldc - the old child (being removed). Note: it might be null.
newc - the new child (being added). Note: it might be null.

onChildVisible_

protected void onChildVisible_(Widget child)
A callback called after a child's visibility is changed (i.e., setVisible(boolean) was called).

Notice that this method is called after the _visible property and the associated DOM element(s) have been changed.

To know if it is becoming visible, you can check isVisible(boolean) (such as this._visible).

Parameters:
child - the child whose visiblity is changed

setTopmost

public int setTopmost()
Makes this widget as topmost.

If this widget is not floating, this method will look for its ancestors for the first ancestor who is floating. In other words, this method makes the floating containing this widget as topmost. To make a widget floating, use setFloating_(boolean, _global_.Map).

This method has no effect if it is not bound to the DOM tree, or none of the widget and its ancestors is floating.

Notice that it does not fire onFloatUp so it is caller's job if it is necessary to close other popups.

Returns:
int the new value of z-index of the topmost floating window, -1 if this widget and none of its ancestors is floating or not bound to the DOM tree.
See Also:
setFloating_(boolean, _global_.Map)

setFloatZIndex_

protected void setFloatZIndex_(DOMElement node,
                               int zi)
Sets the z-index for a floating widget. It is called by setTopmost() to set the z-index, and called only if setFloating_(boolean, _global_.Map) is ever called.

Parameters:
node - the element whose z-index needs to be set. It is the value specified in opts.node when setFloating_(boolean, _global_.Map) is called. If not specified, it is the same as $n(_global_.String).
zi - the z-index to set
Since:
5.0.3
See Also:
setFloating_(boolean, _global_.Map)

getFloatZIndex_

protected void getFloatZIndex_(DOMElement node)
Returns the z-index of a floating widget. It is called by setTopmost() to decide the topmost z-index, and called only if setFloating_(boolean, _global_.Map) is ever called.

Parameters:
node - the element whose z-index needs to be set. It is the value specified in opts.node when setFloating_(boolean, _global_.Map) is called. If not specified, it is the same as $n(_global_.String).
Since:
5.0.3
See Also:
setFloating_(boolean, _global_.Map)

getTopWidget

public Widget getTopWidget()
Returns the top widget, which is the first floating ancestor, or null if no floating ancestor.

Returns:
zk.Widget
See Also:
isFloating_()

isFloating_

protected boolean isFloating_()
Returns if this widget is floating.

We say a widget is floating if the widget floats on top of others, rather than embed inside the parent. For example, an overlapped window is floating, while an embedded window is not.

Returns:
boolean
See Also:
setFloating_(boolean, _global_.Map)

setFloating_

protected Widget setFloating_(boolean floating,
                              Map opts)
Sets a status to indicate if this widget is floating.

Notice that it doesn't change the DOM tree. It is caller's job. In the other words, the caller have to adjust the style by assiging position with absolute or relative.

Parameters:
floating - whther to make it floating
opts - [optional] The options. Allowed options:
Returns:
zk.Widget this widget
See Also:
isFloating_()

getScrollTop

public int getScrollTop()
Returns the scoll top of the associated DOM element of this widget.

0 is always returned if this widget is not bound to a DOM element yet.

Returns:
int

getScrollLeft

public int getScrollLeft()
Returns the scoll left of the associated DOM element of this widget.

0 is always returned if this widget is not bound to a DOM element yet.

Returns:
int

setScrollTop

public Widget setScrollTop(int the)
Sets the scoll top of the associated DOM element of this widget.

This method does nothing if this widget is not bound to a DOM element yet.

Parameters:
the - scroll top.
Returns:
zk.Widget this widget.

setScrollLeft

public Widget setScrollLeft(int the)
Sets the scoll left of the associated DOM element of this widget.

This method does nothing if this widget is not bound to a DOM element yet.

Parameters:
the - scroll top.
Returns:
zk.Widget this widget.

scrollIntoView

public Widget scrollIntoView()
Makes this widget visible in the browser window by scrolling ancestors up or down, if necessary.

Default: invoke zk(this).scrollIntoView();

Returns:
zk.Widget this widget
See Also:
jqzk.scrollIntoView()

redraw

public void redraw(Array out)
Generates the HTML fragment for this widget. The HTML fragment shall be pushed to out. For example,

out.push('');
for (var w = this.firstChild; w; w = w.nextSibling)
        w.redraw(out);
out.push('');

Default: it retrieves the redraw function associated with the mold (getMold()) and then invoke it. The redraw function must have the same signature as this method.

Parameters:
out - an array to output HTML fragments. Technically it can be anything that has the method called push

deferRedraw_

protected void deferRedraw_(Array out)
Utilities for handling the so-called render defer (setRenderdefer(int)). This method is called automatically by redraw(_global_.Array), so you only need to use it if you override redraw(_global_.Array).

A typical usage is as follows.


redraw: function (out) {
  if (!this.deferRedraw_(out)) {
        out.push(...); //redraw
  }
}
 

Parameters:
out - an array to output the HTML fragments.
Since:
5.0.2

deferRedrawHTML_

protected void deferRedrawHTML_(Array out)
Renders a fake DOM element that will replace with the correct element after the deferring time is up. The method is designed for some widgets to override, such as Treeitem, Listitem, and Row, whose HTML tag is created inside a table.

By default, the Div tag is assumed.

Parameters:
out - an array to output the HTML fragments.
Since:
5.0.6

forcerender

public void forcerender()
Forces the rendering if it is deferred. A typical way to defer the render is to specify setRenderdefer(int) with a non-negative value. The other example is some widget might be optimized for the performance by not rendering some or the whole part of the widget. If the rendering is deferred, the corresponding DOM elements ($n(_global_.String)) are not available. If it is important to you, you can force it to be rendered.

Notice that this method only forces this widget to render. It doesn't force any of its children. If you want, you have invoke forcerender() one-by-one

The derived class shall override this method, if it implements the render deferring (other than setRenderdefer(int)).

Since:
5.0.2

updateDomClass_

protected void updateDomClass_()
Updates the DOM element's CSS class. It is called when the CSS class is changed (e.g., setZclass is called).

Default: it changes the class of $n(_global_.String).

Subclass Note

See Also:
updateDomStyle_()

updateDomStyle_

protected void updateDomStyle_()
Updates the DOM element's style. It is called when the CSS style is changed (e.g., setStyle is called).

Default: it changes the CSS style of $n(_global_.String).

Subclass Note


getTextNode

public DOMElement getTextNode()
Returns the DOM element that is used to hold the text, or null if this widget doesn't show any text.

Default: return null (no text node).

For example, updateDomStyle_() will change the style of the text node, if any, to make sure the text is displayed correctly.

Returns:
DOMElement the DOM element.

See also ZK Client-side Reference: Text Styles and Inner Tags.

See Also:
domTextStyleAttr_(), updateDomStyle_()

domStyle_

protected String domStyle_(Map no)
Returns the style used for the DOM element of this widget.

Default: a concatenation of style, width, visible and so on.

Parameters:
no - [options] the style to exclude (i.e., to turn off). If omitted, it means none (i.e., all included). For example, you don't want width to generate, call domStyle_({width:1}). Notice, though a bit counter-intuition, specify 1 (or true) to denote exclusion. Allowed value (subclass might support more options):
Returns:
String the content of the style, such as width:100px;z-index:1;
See Also:
domClass_(_global_.Map), domAttrs_(_global_.Map)

domClass_

protected String domClass_(Map no)
Returns the class name(s) used for the DOM element of this widget.

Default: a concatenation of getZclass() and getSclass().

Parameters:
no - [options] the style class to exclude (i.e., to turn off). If omitted, it means none (i.e., all included). For example, you don't want sclass to generate, call domClass_({sclass:1}). Notice, though a bit counter-intuition, specify 1 (or true) to denote exclusion. Allowed value (subclass might support more options):
Returns:
String the CSS class names, such as z-button foo
See Also:
domStyle_(_global_.Map), domAttrs_(_global_.Map)

domAttrs_

protected String domAttrs_(Map no)
Returns the HTML attributes that is used to generate DOM element of this widget. It is usually used to implement a mold (redraw(_global_.Array)): function () { return ''; }

Default: it generates id, style, class, and tooltiptext. Notice that it invokes domClass_(_global_.Map) and domStyle_(_global_.Map), unless they are disabled by the no argument.

Parameters:
no - [options] the attributes to exclude (i.e., to turn off). If omitted, it means none (i.e., all included). For example, you don't want the style class to generate, call domAttrs_({domClass:1}). Notice, though a bit counter-intuition, specify 1 (or true) to denote exclusion. Allowed value (subclass might support more options):

return the HTML attributes, such as id="z_u7_3" class="z-button"

Returns:
String

domTooltiptext_

protected String domTooltiptext_()
Returns the tooltiptext for generating the title attribute of the DOM element.

Default: return getTooltiptext().

Deriving class might override this method if the parent widget is not associated with any DOM element, such as treerow's parent: treeitem.

Returns:
String the tooltiptext
Since:
5.0.2

domTextStyleAttr_

protected String domTextStyleAttr_()
Returns the style attribute that contains only the text related CSS styles. For example, it returns style="font-size:12pt;font-weight:bold" if #getStyle is border:none;font-size:12pt;font-weight:bold.

It is usually used with getTextNode() to ZK Client-side Reference: Text Styles and Inner Tags.

Returns:
String the CSS style that are related to text (string).
See Also:
getTextNode()

replaceHTML

public Widget replaceHTML(Object n,
                          Desktop desktop,
                          Skipper skipper)
Replaces the specified DOM element with the HTML content generated this widget. It is the same as jq(n).replaceWith(wgt, desktop, skipper).

The DOM element to be replaced can be $n(_global_.String) or any independent DOM element. For example, you can replace a DIV element (and all its descendants) with this widget (and its descendants).

This method is usually used to replace a DOM element with a root widget (though, with care, it is OK for non-root widgets). Non-root widgets usually use appendChild(zk.Widget, boolean) and insertBefore(zk.Widget, zk.Widget) to attach to the DOM tree[1]

If the DOM element doesn't exist, you can use jq.before(java.lang.Object, zk.Desktop) or jq.after(java.lang.Object, zk.Desktop) instead.

Notice that, both replaceHTML(zk.Object, zk.Desktop, zk.Skipper) fires the beforeSize and onSize watch events (refer to zWatch).

If skipper is null. It implies the caller has to fire these two events if it specifies a skipper (that is how rerender(int) is implemented).

Subclass Note

This method actually forwards the invocation to its parent by invoking parent's replaceChildHTML_(zk.Widget, _global_.DOMElement, zk.Desktop, zk.Skipper) to really replace the DOM element. Thus, override replaceChildHTML_(zk.Widget, _global_.DOMElement, zk.Desktop, zk.Skipper) if you want to do something special for particular child widgets.

Parameters:
n - the DOM element (DOMElement) or anything $(zk.Object, _global_.Map) allowed.
desktop - [optional] the desktop that this widget shall belong to. If omitted, it is retrieve from the current desktop. If null, it is decided automatically ( such as the current value of desktop or the first desktop)
skipper - [optional] it is used only if it is called by rerender(int)
Returns:
zk.Widget
See Also:
replaceWidget(zk.Widget), jq.replaceWith(zk.Widget, zk.Desktop, zk.Skipper)

getOldWidget_

protected void getOldWidget_(DOMElement n)
Returns the widget associated with the given node element. It is used by replaceHTML(zk.Object, zk.Desktop, zk.Skipper) and replaceChildHTML_(zk.Widget, _global_.DOMElement, zk.Desktop, zk.Skipper) to retrieve the widget associated with the note.

It is similar to $(zk.Object, _global_.Map) but it gives the widget a chance to handle extreme cases. For example, Treeitem doesn't associate a DOM element (or you can say Treeitem and Treerow shares the same DOM element), so zk.Widget.$(n) will return Treerow, not Treeitem. If it is the case, you can override it to make replaceHTML(zk.Object, zk.Desktop, zk.Skipper) works correctly.

Parameters:
n - the DOM element to match the widget.
Since:
5.0.3

redrawHTML_

protected String redrawHTML_(Skipper skipper,
                             boolean trim)
Returns the HTML fragment of this widget.

Parameters:
skipper - the skipper. Ignored if null
trim - whether to trim the HTML content before replacing
Returns:
String the HTML fragment

rerender

public Widget rerender(int timeout)
Re-renders after the specified time (milliseconds).

Notice that, to have the best performance, we use the single timer to handle all pending rerenders for all widgets. In other words, if the previous timer is not expired (and called), the second call will reset the expiration time to the value given in the second call.

Parameters:
timeout - the number milliseconds (non-negative) to wait before rerender. If negative, it means rerender shall take place immediately. If not specified, 0 is assumed (since ZK 6).
Returns:
zk.Widget this widget.
Since:
5.0.4

rerender

public Widget rerender(Skipper skipper)
Re-renders the DOM element(s) of this widget. By re-rendering we mean to generate HTML again (redraw(_global_.Array)) and then replace the DOM elements with the new generated HTML code snippet.

It is equivalent to replaceHTML(this.node, null, skipper).

It is usually used to implement a setter of this widget. For example, if a setter (such as setBorder) has to modify the visual appearance, it can update the DOM tree directly, or it can call this method to re-render all DOM elements associated with is widget and its desendants.

It is coonvenient to synchronize the widget's state with the DOM tree with this method. However, it shall be avoided if the HTML code snippet is complex (otherwise, the performance won't be good).

If re-rendering is required, you can improve the performance by passing an instance of Skipper that is used to re-render some or all descendant widgets of this widget.

Parameters:
skipper - [optional] skip some portion of this widget to speed up the re-rendering. If not specified, rerender(0) is assumed (since ZK 6).
Returns:
zk.Widget this widget.

replaceChildHTML_

protected void replaceChildHTML_(Widget child,
                                 DOMElement n,
                                 Desktop dt,
                                 Skipper skipper)
Replaces the DOM element(s) of the specified child widget. It is called by replaceHTML(zk.Object, zk.Desktop, zk.Skipper) to give the parent a chance to do something special for particular child widgets.

Parameters:
child - the child widget whose DOM content is used to replace the DOM tree
n - the DOM element to be replaced
dt - [optional the desktop that this widget shall belong to. If null, it is decided automatically ( such as the current value of desktop or the first desktop)
skipper - it is used only if it is called by rerender(int)

insertChildHTML_

protected void insertChildHTML_(Widget child,
                                Widget before,
                                Desktop desktop)
Inserts the HTML content generated by the specified child widget before the reference widget (the before argument). It is called by insertBefore(zk.Widget, zk.Widget) and appendChild(zk.Widget, boolean) to handle the DOM tree.

Deriving classes might override this method to modify the HTML content, such as enclosing with TD.

Notice that when inserting the child (without the before argument), this method will call getCaveNode() to find the location to place the DOM element of the child. More precisely, the node returned by getCaveNode() is the parent DOM element of the child. The default implementation of getCaveNode() is to look for a sub-node named uuid$cave. In other words, it tried to place the child inside the so-called cave sub-node, if any. Otherwise, $n(_global_.String) is assumed.

Parameters:
child - the child widget to insert
before - the child widget as the reference to insert the new child before. If null, the HTML content will be appended as the last child. The implementation can use before.getFirstNode_() (getFirstNode_()) to retrieve the DOM element
desktop -
See Also:
getCaveNode()

getCaveNode

public DOMElement getCaveNode()
Called by insertChildHTML_(zk.Widget, zk.Widget, zk.Desktop) to to find the location to place the DOM element of the child. More precisely, the node returned by getCaveNode() is the parent DOM element of the child's DOM element.

Default: this.$n('cave') || this.$n() You can override it to return whatever DOM element you want.

Returns:
DOMElement
See Also:
insertChildHTML_(zk.Widget, zk.Widget, zk.Desktop)

getFirstNode_

protected DOMElement getFirstNode_()
Returns the first DOM element of this widget. If this widget has no corresponding DOM element, this method will look for its siblings.

This method is designed to be used with insertChildHTML_(zk.Widget, zk.Widget, zk.Desktop) for retrieving the DOM element of the before widget.

Returns:
DOMElement

removeChildHTML_

protected void removeChildHTML_(Widget child,
                                boolean ignoreDom)
Removes the corresponding DOM content of the specified child. It is called by removeChild(zk.Widget, boolean) to remove the DOM content.

The default implementation of this method will invoke removeHTML_(_global_.Array) if the ignoreDom argument is false or not specified.

Overrides this method or removeHTML_(_global_.Array) if you have to remove DOM elements other than child's node (and the descendants).

Parameters:
child - the child widget to remove
ignoreDom - whether to remove the DOM element

removeHTML_

protected void removeHTML_(Array n)
Removes the HTML DOM content.

The default implementation simply removes the DOM element passed in.

Overrides this method if you have to remove the related DOM elements.

Parameters:
n - an array of DOMElement to remove. If this widget is associated with a DOM element ($n(_global_.String) returns non-null), n is a single element array. If this widget is not assoicated with any DOM element, an array of child widget's DOM elements are returned.
Since:
5.0.1

$n

public DOMElement $n(String subId)
Returns the child element of the DOM element(s) that this widget is bound to. This method assumes the ID of the child element the concatenation of uuid, -, and subId. For example,
var cave = wgt.$n('cave'); //the same as jq('#' + wgt.uuid + '-' + 'cave')[0]
Like $n(), this method caches the result so the performance is much better than invoking jq() directly.

Parameters:
subId - the sub ID of the child element
Returns:
DOMElement
See Also:
$n()

$n

public DOMElement $n()
Returns the DOM element that this widget is bound to. It is null if it is not bound to the DOM tree, or it doesn't have the associated DOM node (for example, Timer).

Notice that desktop is always non-null if it is bound to the DOM tree. In additions, this method is much faster than invoking jq() (see jq, since it caches the result (and clean up at the unbind_(zk.Skipper, _global_.Array)).

var n = wgt.$n();

Returns:
DOMElement
See Also:
$n(String)

isRealElement

public boolean isRealElement()
Returns whether the widget has its own element bound to HTML DOM tree.

Returns:
boolean
Since:
7.0.0

$s

public String $s()
Returns the sub zclass name that cache for this widget. It returns the zclass if the subclass is empty or null, since it caches the result (and clean up at the setZclass(String)).
var subzcls = wgt.$s('hover'); // z-xxx-hover will be return

Returns:
String
Since:
7.0.0
See Also:
getZclass()

clearCache

public void clearCache()
Clears the cached nodes (by $n(_global_.String)).


getPage

public Page getPage()
Returns the page that this widget belongs to, or null if there is no page available.

Returns:
zk.Page

isBinding

public boolean isBinding()
Returns whether this widget is being bound to DOM. In other words, it returns true if bind(zk.Desktop, zk.Skipper) is called against this widget or any of its ancestors.

Returns:
boolean
Since:
5.0.8

bind

public Widget bind(Desktop dt,
                   Skipper skipper)
Binds this widget. It is called to assoicate (aka., attach) the widget with the DOM tree.

Notice that you rarely need to invoke this method, since it is called automatically (such as replaceHTML(zk.Object, zk.Desktop, zk.Skipper) and appendChild(zk.Widget, boolean)).

Notice that you rarely need to override this method, either. Rather, override bind_(zk.Desktop, zk.Skipper, _global_.Array) instead.

Parameters:
dt - [optional] the desktop the DOM element belongs to. If not specified, ZK will decide it automatically.
skipper - [optional] used if rerender(int) is called with a non-null skipper.
Returns:
zk.Widget this widget
See Also:
bind_(zk.Desktop, zk.Skipper, _global_.Array), unbind(zk.Desktop, zk.Skipper)

unbind

public Widget unbind(Desktop dt,
                     Skipper skipper)
Unbinds this widget. It is called to remove the assoication (aka., detach) the widget from the DOM tree.

Notice that you rarely need to invoke this method, since it is called automatically (such as replaceHTML(zk.Object, zk.Desktop, zk.Skipper)).

Notice that you rarely need to override this method, either. Rather, override unbind_(zk.Skipper, _global_.Array) instead.

Parameters:
dt - [optional] the desktop the DOM element belongs to. If not specified, ZK will decide it automatically.
skipper - [optional] used if rerender(int) is called with a non-null skipper.
Returns:
zk.Widget this widget
See Also:
unbind_(zk.Skipper, _global_.Array), bind(zk.Desktop, zk.Skipper)

bind_

protected void bind_(Desktop dt,
                     Skipper skipper,
                     Array after)
Callback when this widget is bound (aka., attached) to the DOM tree. It is called after the DOM tree has been modified (with the DOM content of this widget, i.e., redraw(_global_.Array)) (for example, by replaceHTML(zk.Object, zk.Desktop, zk.Skipper)).

Note: don't invoke this method directly. Rather, invoke bind(zk.Desktop, zk.Skipper) instead.


wgt.bind();

Subclass Note

Subclass overrides this method to initialize the DOM element(s), such as adding a DOM listener. Refer to Widget and DOM Events and domListen_(_global_.DOMElement, _global_.String, zk.Object, _global_.String) for more information.

Parameters:
dt - [optional] the desktop the DOM element belongs to. If not specified, ZK will decide it automatically.
skipper - [optional] used if rerender(int) is called with a non-null skipper.
after - an array of function (Function) that will be invoked after bind_(zk.Desktop, zk.Skipper, _global_.Array) has been called. For example,

bind_: function (desktop, skipper, after) {
  this.$supers('bind_', arguments);
  var self = this;
  after.push(function () {
    self._doAfterBind(something);
    ...
  });
}
See Also:
bind(zk.Desktop, zk.Skipper), unbind_(zk.Skipper, _global_.Array)

bindChildren_

protected void bindChildren_(Desktop dt,
                             Skipper skipper,
                             Array after)
Binds the children of this widget. It is called by bind_(zk.Desktop, zk.Skipper, _global_.Array) to invoke child's bind_(zk.Desktop, zk.Skipper, _global_.Array) one-by-one.

Parameters:
dt - [optional] the desktop the DOM element belongs to. If not specified, ZK will decide it automatically.
skipper - [optional] used if rerender(int) is called with a non-null skipper.
after - an array of function (Function) that will be invoked after bind_(zk.Desktop, zk.Skipper, _global_.Array) has been called. For example,
Since:
5.0.5

unbind_

protected void unbind_(Skipper skipper,
                       Array after)
Callback when a widget is unbound (aka., detached) from the DOM tree. It is called before the DOM element(s) of this widget is going to be removed from the DOM tree (such as removeChild(zk.Widget, boolean).

Note: don't invoke this method directly. Rather, invoke unbind(zk.Desktop, zk.Skipper) instead.

Note: after invoking this.$supers('unbind_', arguments), the association with DOM elements are lost. Thus it is better to invoke it as the last statement.

Notice that removeChild(zk.Widget, boolean) removes DOM elements first, so unbind_(zk.Skipper, _global_.Array) is called before beforeParentChanged_(zk.Widget) and the modification of the widget tree. It means it is safe to access parent and other information here

Parameters:
skipper - [optional] used if rerender(int) is called with a non-null skipper
after - an array of function (Function)that will be invoked after unbind_(zk.Skipper, _global_.Array) has been called. For example,

unbind_: function (skipper, after) {
  var self = this;
  after.push(function () {
    self._doAfterUnbind(something);
    ...
  }
  this.$supers('unbind_', arguments);
}
See Also:
bind_(zk.Desktop, zk.Skipper, _global_.Array), unbind(zk.Desktop, zk.Skipper)

unbindChildren_

protected void unbindChildren_(Skipper skipper,
                               Array after)
Unbinds the children of this widget. It is called by unbind_(zk.Skipper, _global_.Array) to invoke child's unbind_(zk.Skipper, _global_.Array) one-by-one.

Parameters:
skipper - [optional] used if rerender(int) is called with a non-null skipper
after - an array of function (Function)that will be invoked after unbind_(zk.Skipper, _global_.Array) has been called. For example,
Since:
5.0.5

extraBind_

protected void extraBind_(String uuid,
                          boolean add)
Associates UUID with this widget.

Notice that uuid is automically associated (aka., bound) to this widget. Thus, you rarely need to invoke this method unless you want to associate with other identifiers.

For example, ZK Google Maps uses this method since it has to bind the anchors manually.

Parameters:
uuid - the UUID to assign to the widgtet
add - whether to bind. Specify true if you want to bind; false if you want to unbind.

initDrag_

protected void initDrag_()
Initializes the widget to make it draggable. It is called if getDraggable() is set (and bound).

You rarely need to override this method, unless you want to handle drag-and-drop differently.

Default: use Draggable to implement drag-and-drop, and the handle to drag is the element returned by getDragNode()

See Also:
cleanDrag_()

cleanDrag_

protected void cleanDrag_()
Cleans up the widget to make it un-draggable. It is called if getDraggable() is cleaned (or unbound).

You rarely need to override this method, unless you want to handle drag-and-drop differently.

See Also:
cleanDrag_()

getDragNode

public DOMElement getDragNode()
Returns the DOM element of this widget that can be dragged.

Default, it returns $n(_global_.String), i.e., the user can drag the widget anywhere.

Returns:
DOMElement
See Also:
ignoreDrag_(zk.Draggable)

getDragOptions_

protected Map getDragOptions_(Map map)
Returns the options used to instantiate Draggable.

Default, it does nothing but returns the map parameter, i.e., the default options.

Though rarely used, you can override any option passed to Draggable, such as the start effect, ghosting and so on.

Parameters:
map - the default implementation
Returns:
Map

ignoreDrag_

protected boolean ignoreDrag_(Draggable pt)
Returns if the location that an user is trying to drag is allowed.

Default: it always returns false. If the location that an user can drag is static, override getDragNode(), which is easier to implement.

Parameters:
pt -
Returns:
boolean whether to ignore

getDrop_

protected Widget getDrop_(Widget dragged)
Returns the widget if it allows to drop the specified widget (being dragged), or null if not allowed. It is called when the user is dragging a widget on top a widget.

Default: it check if the values of droppable and draggable match. It will check the parent (parent), parent's parent, and so on until matched, or none of them are matched.

Notice that the widget to test if droppable might be the same as the widget being dragged (i.e., this == dragged). By default, we consider them as non-matched.

Parameters:
dragged - - the widget being dragged (never null).
Returns:
zk.Widget the widget to drop to.

dropEffect_

protected void dropEffect_(boolean over)
Called to have some visual effect when the user is dragging a widget over this widget and this widget is droppable. Notice it is the effect to indicate a widget is droppable.

Default, it adds the CSS class named 'z-drag-over' if over is true, and remove it if over is false.

Parameters:
over - whether the user is dragging over (or out, if false)

getDragMessage_

protected String getDragMessage_()
Returns the message to show when an user is dragging this widget, or null if it prefers to clone the widget with cloneDrag_(zk.Draggable, _global_.Offset).

Default, it return the inner text if if $n(_global_.String) returns a TR, TD, or TH element. Otherwise, it returns null and cloneDrag_(zk.Draggable, _global_.Offset) will be called to create a DOM element to indicate dragging.

Returns:
String the message to indicate the dragging, or null if clone is required

onDrop_

protected void onDrop_(Draggable drag,
                       Event evt)
Called to fire the onDrop event. You could override it to implement some effects to indicate dropping.

Default, it fires the onDrop event (with fire(_global_.String, zk.Object, _global_.Map, int)). The subclass can override this method to pass more options such as the coordination where a widget is dropped.

Parameters:
drag - the draggable controller
evt - the event causes the drop

cloneDrag_

protected DOMElement cloneDrag_(Draggable drag,
                                Offset ofs)
Called to create the visual effect representing what is being dragged. In other words, it creates the DOM element that will be moved with the mouse pointer when the user is dragging.

This method is called if getDragMessage_() returns null. If getDragMessage_() returns a string (empty or not), a small popup containing the message is created to represent the widget being dragged.

You rarely need to override this method, unless you want a different visual effect.

Parameters:
drag - the draggable controller
ofs - the offset of the returned element (left/top)
Returns:
DOMElement the clone
See Also:
uncloneDrag_(zk.Draggable)

uncloneDrag_

protected void uncloneDrag_(Draggable drag)
Undo the visual effect created by cloneDrag_(zk.Draggable, _global_.Offset).

Parameters:
drag - the draggable controller

onAfterSize

public void onAfterSize()
Called to fire the onAfterSize event.

Since:
6.5.2

focus

public boolean focus(int timeout)
Sets the focus to this widget. This method will check if this widget can be activated by invoking canActivate(_global_.Map) first.

Notice: don't override this method. Rather, override focus_(int), which this method depends on.

Parameters:
timeout - how many milliseconds before changing the focus. If not specified or negative, the focus is changed immediately,
Returns:
boolean whether the focus is gained to this widget.

focus_

protected boolean focus_(int timeout)
Called by focus(int) to set the focus.

Default: call child widget's focus until it returns true, or no child at all.

Subclass Note

  • If a widget is able to gain focus, it shall override this method to invoke jqzk.focus(int).
  • It is called only if the DOM element is real visible (so you don't need to check again)

focus_: function (timeout) {
  zk(this.$n('foo').focus(timeout);
  return true;
}

Parameters:
timeout - how many milliseconds before changing the focus. If not specified or negative, the focus is changed immediately,
Returns:
boolean whether the focus is gained to this widget.
Since:
5.0.5

canActivate

public boolean canActivate(Map opts)
Checks if this widget can be activated (gaining focus and so on).

Default: return false if it is not a descendant of zk.currentModal.

Parameters:
opts - [optional] the options. Allowed values:
  • checkOnly: not to change focus back to modal dialog if unable to activate. If not specified, the focus will be changed back to zk.currentModal. In additions, if specified, it will ignore zk, which is set if AuCmd0.showBusy(_global_.String) is called. This flag is usually set by focus(int), and not set if it is caused by user's activity, such as clicking.
The reason to ignore busy is that we allow application to change focus even if busy, while the user cannot.
Returns:
boolean

smartUpdate

public Widget smartUpdate(String name,
                          Object value,
                          int timeout)
Smart-updates a property of the peer component associated with this widget, running at the server, with the specified value.

It is actually fired an AU requst named setAttr, and it is handled by the updateByClient method in org.zkoss.zk.ui.AbstractComponent (at the server).

By default, it is controlled by a component attribute called org.zkoss.zk.ui.updateByClient. And, it is default to false. Thus, the component developer has to override updateByClient at the server (in Java) and then update it rather than calling back superclass. For example,

protected void updateByClient(String name, Object value) {
        if ("disabled".equals(name))
                setDisabled(value instanceof Boolean && ((Boolean)value).booleanValue());
        else
                super.updateByClient(name, value);
}

Parameters:
name - the property name
value - the property value
timeout - the delay before sending out the AU request. It is optional. If omitted, -1 is assumed (i.e., it will be sent with next non-deferrable request).
Returns:
zk.Widget
See Also:
zAu.send(zk.Event, int)

fireX

public Event fireX(Event evt,
                   int timeout)
Fire a widget event.

Parameters:
evt - the event to fire
timeout - the delay before sending the non-deferrable AU request (if necessary). If not specified or negative, it is decided automatically. It is ignored if no non-deferrable listener is registered at the server.
Returns:
zk.Event the event being fired, i.e., evt.
See Also:
fire(_global_.String, zk.Object, _global_.Map, int), listen(_global_.Map, int)

beforeSendAU_

protected void beforeSendAU_(Widget wgt,
                             Event evt)
Callback before sending an AU request. It is called by sendAU_(zk.Event, int).

Default: this method will stop the event propagation and prevent the browser's default handling (by calling Event.stop(_global_.Map)), if the event is onClick, onRightClick or onDoubleClick.

Notice that sendAU_(zk.Event, int) is called against the widget sending the AU request to the server, while beforeSendAU_(zk.Widget, zk.Event) is called against the event's target (evt.target).

Notice that since this method will stop the event propagation for onClick, onRightClick and onDoubleClick, it means the event propagation is stopped if the server registers a listener. However, it doesn't stop if only a client listener is registered (and, in this case, Event.stop(_global_.Map) must be called explicitly if you want to stop).

Parameters:
wgt - the widget that causes the AU request to be sent. It will be the target widget when the server receives the event.
evt - the event to be sent back to the server. Its content will be cloned to the AU request.
Since:
5.0.2
See Also:
sendAU_(zk.Event, int)

sendAU_

protected void sendAU_(Event evt,
                       int timeout)
Sends an AU request to the server. It is invoked when fire(_global_.String, zk.Object, _global_.Map, int) will send an AU request to the server.

Override Notice: sendAU_(zk.Event, int) will call evt.target's beforeSendAU_(zk.Widget, zk.Event) to give the original target a chance to process it.

Parameters:
evt - the event that will be sent to the server.
timeout - the delay before really sending out the AU request
Since:
5.0.1
See Also:
fire(_global_.String, zk.Object, _global_.Map, int), beforeSendAU_(zk.Widget, zk.Event), zAu.sendAhead(zk.Event, int)

shallIgnoreClick_

protected boolean shallIgnoreClick_(Event the)
Check whether to ignore the click which might be caused by doClick_(zk.Event) doRightClick_(zk.Event), or doDoubleClick_(zk.Event).

Default: return false.

Deriving class might override this method to return true if it wants to ignore the click on certain DOM elements, such as the open icon of a treerow.

Notice: if true is returned, doClick_(zk.Event) doRightClick_(zk.Event), and doDoubleClick_(zk.Event) won't be called. In additions, the popup and context of Widget won't be handled, either.

Parameters:
the - event that causes the click (doClick_(zk.Event) doRightClick_(zk.Event), or doDoubleClick_(zk.Event)).
Returns:
boolean whether to ignore it
Since:
5.0.1

fire

public Event fire(String evtnm,
                  Object data,
                  Map opts,
                  int timeout)
Fire a widget event. An instance of Event is created to represent the event.

The event listeners for this event will be called one-by-one unless Event.stop(_global_.Map) is called.

If the event propagation is not stopped (i.e., Event.stop(_global_.Map) not called) and inServer is true, the event will be converted to an AU request and sent to the server. Refer to ZK Client-side Reference: AU Requests: Client-side Firing for more information.

Parameters:
evtnm - the event name, such as onClick
data - [optional] the data depending on the event (Event).
opts - [optional] the options. Refer to Event.opts
timeout - the delay before sending the non-deferrable AU request (if necessary). If not specified or negative, it is decided automatically. It is ignored if no non-deferrable listener is registered at the server.
Returns:
zk.Event the event being fired.
See Also:
fire(_global_.String, zk.Object, _global_.Map, int), listen(_global_.Map, int)

listen

public Widget listen(Map infos,
                     int priority)
Registers listener(s) to the specified event. For example,

wgt.listen({
  onClick: wgt,
  onOpen: wgt._onOpen,
  onMove: [o, o._onMove]
});

As shown above, you can register multiple listeners at the same time, and echo value in infos can be a target, a function, or a two-element array, where the first element is a target and the second the function. A target can be any object that this will reference to when the event listener is called. Notice it is not Event.target. Rather, it is this when the listener is called.

If the function is not specified, the target must have a method having the same name as the event. For example, if wgt.listen({onChange: target}) was called, then target.onChange(evt) will be called when onChange event is fired (by fire(_global_.String, zk.Object, _global_.Map, int)). On the other hand, if the target is not specified, the widget is assumed to be the target.

Parameters:
infos - a map of event listeners. Each key is the event name, and each value can be the target, the listener function, or a two-element array, where the first element is the target and the second the listener function. Notice that the target is not Event.target. Rather, it is this when the listener is called.
priority - the higher the number, the earlier it is called. If omitted, 0 is assumed. If a widget needs to register a listener as the default behavior (such as zul.wnd.Window's onClose), -1000 is suggested
Returns:
zk.Widget this widget
See Also:
unlisten(_global_.Map), fire(_global_.String, zk.Object, _global_.Map, int), fireX(zk.Event, int), setListeners(_global_.Map), setListener(_global_.String, _global_.Function)

unlisten

public Widget unlisten(Map infos)
Removes a listener from the sepcified event.

wgt.unlisten({
  onClick: wgt,
  onOpen: wgt._onOpen,
  onMove: [o, o._onMove]
});

Parameters:
infos - a map of event listeners. Each key is the event name, and each value can be the target, the listener function, or a two-element array, where the first element is the target and the second the listener function.
Returns:
zk.Widget this widget
See Also:
listen(_global_.Map, int), isListen(_global_.String, _global_.Map), fire(_global_.String, zk.Object, _global_.Map, int), fireX(zk.Event, int)

isListen

public boolean isListen(String evtnm,
                        Map opts)
Returns if a listener is registered for the specified event.

Parameters:
evtnm - the event name, such as onClick.
opts - [optional] the options. If omitted, it checks only if the server registers any non-deferrable listener, and if the client register any listener. Allowed values:
  • any - in addition to the server's non-deferrable listener and client's listener, it also checks deferrable listener, and the so-called important events
  • asapOnly - it checks only if the server registers a non-deferrable listener, and if any non-deferrable important event. Use this option, if you want to know whether an AU request will be sent.
Returns:
boolean

setListeners

public void setListeners(Map infos)
Sets the listener a map of listeners. It is similar to listen(_global_.Map, int), except
  • It will 'remember' what the listeners are, such that it can unlisten by specifying null as the value of the infs argument
  • The function can be a string and it will be converted to Function automatically.

This method is mainly designed to be called by the application running at the server.

Example:


wgt.setListeners({
 onChange: function (event) {this.doSomething();},
 onFocus: 'this.doMore();',
 onBlur: null //unlisten
});

Parameters:
infos - a map of event listeners. Each key is the event name, and each value is a string, a function or null. If the value is null, it means unlisten. If the value is a string, it will be converted to a Function. Notice that the target is not Event.target. Rather, it is this when the listener is called.

setListener

public void setListener(String evt,
                        Function fn)
Sets a listener It is designed to be called from server. For client-side programming, it is suggested to use listen(_global_.Map, int). Use it only if you want to unlisten the listener registered at the server (by use of the client namespace).

It is based listen(_global_.Map, int), but, unlike listen(_global_.Map, int), the second invocation for the same event will unlisten the previous one automatically.

In additions, if fn is null, it unlistens the previous invocation.

Parameters:
evt - the event name
fn - the listener function. If null, it means unlisten.
See Also:
setListeners(_global_.Map), listen(_global_.Map, int)

setListener

public void setListener(Array inf)
Sets a listener that can be unlistened easily. It is designed to be called from server. For client-side programming, it is suggested to use listen(_global_.Map, int).

It is based listen(_global_.Map, int), but, unlike listen(_global_.Map, int), the second invocation for the same event will unlisten the previous one automatically.

In additions, if the function (specified in the second element of inf) is null, it unlistens the previous invocation.

Parameters:
inf - a two-element array. The first element is the event name, while the second is the listener function
See Also:
setListeners(_global_.Map)

doSelect_

protected void doSelect_(Event evt)
Called when the user clicks or right-clicks on widget or a child widget. It is called before doClick_(zk.Event) and doRightClick_(zk.Event).

Default: does nothing but invokes the parent's doSelect_(zk.Event). Notice that it does not fire any event.

Deriving class that supports selection (such as ItemWidget) shall override this to handle the selection.

Technically, the selection can be handled in doClick_(zk.Event). However, it is better to handle here since this method is invoked first such that the widget will be selected before one of its descendant widget handles doClick_(zk.Event).

Notice that calling Event.stop(_global_.Map) will stop the invocation of parent's doSelect_(zk.Event) and doClick_(zk.Event)/doRightClick_(zk.Event). If you just don't want to call parent's doSelect_(zk.Event), simply not to invoke super's doSelect_.

Parameters:
evt - the widget event. The original DOM event and target can be retrieved by Event.domEvent and Event.domTarget
Since:
5.0.1
See Also:
doClick_(zk.Event), doRightClick_(zk.Event)

doTooltipOver_

protected void doTooltipOver_()
Called when the mouse is moved over this widget. It is called before doMouseOver_(zk.Event).

Default: does nothing but invokes the parent's doTooltipOver_(). Notice that it does not fire any event.

Notice that calling Event.stop(_global_.Map) will stop the invocation of parent's doTooltipOver_() and doMouseOver_(zk.Event). If you just don't want to call parent's doMouseOver_(zk.Event), simply not to invoke super's doMouseOver_.

Since:
5.0.5
See Also:
doTooltipOut_()

doTooltipOut_

protected void doTooltipOut_()
Called when the mouse is moved out of this widget. It is called before doMouseOut_(zk.Event).

Default: does nothing but invokes the parent's doTooltipOut_(). Notice that it does not fire any event.

Notice that calling Event.stop(_global_.Map) will stop the invocation of parent's doTooltipOut_() and doMouseOut_(zk.Event). If you just don't want to call parent's doMouseOut_(zk.Event), simply not to invoke super's doMouseOut_.

Since:
5.0.5
See Also:
doTooltipOver_()

doClick_

protected void doClick_(Event evt)
Called when the user clicks on a widget or a child widget. A widget doesn't need to listen the click DOM event. Rather, it shall override this method if necessary.

Default: fire the widget event (fireX(zk.Event, int)), and call parent's doClick_ if the event propagation is not stopped (Event.stopped). It is the so-called event propagation.

If a widget, such as zul.wgt.Button, handles onClick, it is better to override this method and not calling back the superclass.

Note: if shallIgnoreClick_(zk.Event) returns true, fireX(zk.Event, int) won't be called and this method invokes the parent's doClick_(zk.Event) instead (unless Event.stopped is set).

See also ZK Client-side Reference: Notifications

Parameters:
evt - the widget event. The original DOM event and target can be retrieved by Event.domEvent and Event.domTarget
See Also:
doDoubleClick_(zk.Event), doRightClick_(zk.Event), doSelect_(zk.Event)

doDoubleClick_

protected void doDoubleClick_(Event evt)
Called when the user double-clicks on a widget or a child widget. A widget doesn't need to listen the dblclick DOM event. Rather, it shall override this method if necessary.

Default: fire the widget event (fireX(zk.Event, int)), and call parent's doDoubleClick_ if the event propagation is not stopped (Event.stopped). It is the so-called event propagation.

Note: if shallIgnoreClick_(zk.Event) returns true, fireX(zk.Event, int) won't be called and this method invokes the parent's doDoubleClick_(zk.Event) instead (unless Event.stopped is set).

See also ZK Client-side Reference: Notifications

Parameters:
evt - the widget event. The original DOM event and target can be retrieved by Event.domEvent and Event.domTarget
See Also:
doClick_(zk.Event), doRightClick_(zk.Event)

doRightClick_

protected void doRightClick_(Event evt)
Called when the user right-clicks on a widget or a child widget. A widget doesn't need to listen the contextmenu DOM event. Rather, it shall override this method if necessary.

Default: fire the widget event (fireX(zk.Event, int)), and call parent's doRightClick_ if the event propagation is not stopped (Event.stopped). It is the so-called event propagation.

Note: if shallIgnoreClick_(zk.Event) returns true, fireX(zk.Event, int) won't be called and this method invokes the parent's doRightClick_(zk.Event) instead (unless Event.stopped is set).

See also ZK Client-side Reference: Notifications

Parameters:
evt - the widget event. The original DOM event and target can be retrieved by Event.domEvent and Event.domTarget
See Also:
doClick_(zk.Event), doDoubleClick_(zk.Event)

doMouseOver_

protected void doMouseOver_(Event evt)
Called when the user moves the mouse pointer on top of a widget (or one of its child widget). A widget doesn't need to listen the mouseover DOM event. Rather, it shall override this method if necessary.

Default: fire the widget event (fireX(zk.Event, int)), and call parent's doMouseOver_ if the event propagation is not stopped (Event.stopped).

See also ZK Client-side Reference: Notifications

Parameters:
evt - the widget event. The original DOM event and target can be retrieved by Event.domEvent and Event.domTarget
See Also:
doMouseMove_(zk.Event), doMouseEnter_(zk.Event), doMouseLeave_(zk.Event), doMouseOver_(zk.Event), doMouseOut_(zk.Event), doMouseDown_(zk.Event), doMouseUp_(zk.Event), doTooltipOver_()

doMouseOut_

protected void doMouseOut_(Event evt)
Called when the user moves the mouse pointer out of a widget (or one of its child widget). A widget doesn't need to listen the mouseout DOM event. Rather, it shall override this method if necessary.

Default: fire the widget event (fireX(zk.Event, int)), and call parent's doMouseOut_ if the event propagation is not stopped (Event.stopped).

Parameters:
evt - the widget event. The original DOM event and target can be retrieved by Event.domEvent and Event.domTarget

See also ZK Client-side Reference: Notifications

See Also:
doMouseMove_(zk.Event), doMouseEnter_(zk.Event), doMouseLeave_(zk.Event), doMouseOver_(zk.Event), doMouseDown_(zk.Event), doMouseUp_(zk.Event), doTooltipOut_()

doMouseEnter_

protected void doMouseEnter_(Event evt)
Called when the user moves the mouse pointer on top of a widget (or one of its child widget). A widget doesn't need to listen the mouseover DOM event. Rather, it shall override this method if necessary.

Default: fire the widget event (fireX(zk.Event, int)), and call parent's doMouseEnter_ if the event propagation is not stopped (Event.stopped).

See also ZK Client-side Reference: Notifications

Parameters:
evt - the widget event. The original DOM event and target can be retrieved by Event.domEvent and Event.domTarget
Since:
7.0.0
See Also:
doMouseMove_(zk.Event), doMouseEnter_(zk.Event), doMouseLeave_(zk.Event), doMouseOver_(zk.Event), doMouseOut_(zk.Event), doMouseDown_(zk.Event), doMouseUp_(zk.Event), doTooltipOver_()

doMouseLeave_

protected void doMouseLeave_(Event evt)
Called when the user moves the mouse pointer out of a root widget. A widget doesn't need to listen the mouseout DOM event. Rather, it shall override this method if necessary.

Default: fire the widget event (fireX(zk.Event, int)), and call parent's doMouseLeave_ if the event propagation is not stopped (Event.stopped).

Parameters:
evt - the widget event. The original DOM event and target can be retrieved by Event.domEvent and Event.domTarget

See also ZK Client-side Reference: Notifications

Since:
7.0.0
See Also:
doMouseMove_(zk.Event), doMouseEnter_(zk.Event), doMouseLeave_(zk.Event), doMouseOver_(zk.Event), doMouseDown_(zk.Event), doMouseUp_(zk.Event), doTooltipOut_()

doMouseDown_

protected void doMouseDown_(Event evt)
Called when the user presses down the mouse button on this widget (or one of its child widget). A widget doesn't need to listen the mousedown DOM event. Rather, it shall override this method if necessary.

Default: fire the widget event (fireX(zk.Event, int)), and call parent's doMouseDown_ if the event propagation is not stopped (Event.stopped).

See also ZK Client-side Reference: Notifications

Parameters:
evt - the widget event. The original DOM event and target can be retrieved by Event.domEvent and Event.domTarget
See Also:
doMouseMove_(zk.Event), doMouseOver_(zk.Event), doMouseOut_(zk.Event), doMouseUp_(zk.Event), doClick_(zk.Event)

doMouseUp_

protected void doMouseUp_(Event evt)
Called when the user presses up the mouse button on this widget (or one of its child widget). A widget doesn't need to listen the mouseup DOM event. Rather, it shall override this method if necessary.

Default: fire the widget event (fireX(zk.Event, int)), and call parent's doMouseUp_ if the event propagation is not stopped (Event.stopped). It is the so-called event propagation.

See also ZK Client-side Reference: Notifications

Parameters:
evt - the widget event. The original DOM event and target can be retrieved by Event.domEvent and Event.domTarget
See Also:
doMouseMove_(zk.Event), doMouseOver_(zk.Event), doMouseOut_(zk.Event), doMouseDown_(zk.Event), doClick_(zk.Event)

doMouseMove_

protected void doMouseMove_(Event evt)
Called when the user moves the mouse pointer over this widget (or one of its child widget). A widget doesn't need to listen the mousemove DOM event. Rather, it shall override this method if necessary.

Default: fire the widget event (fireX(zk.Event, int)), and call parent's doMouseMove_ if the event propagation is not stopped (Event.stopped). It is the so-called event propagation.

See also ZK Client-side Reference: Notifications

Parameters:
evt - the widget event. The original DOM event and target can be retrieved by Event.domEvent and Event.domTarget
See Also:
doMouseOver_(zk.Event), doMouseOut_(zk.Event), doMouseDown_(zk.Event), doMouseUp_(zk.Event)

doKeyDown_

protected void doKeyDown_(Event evt)
Called when the user presses down a key when this widget has the focus (focus(int)).

Notice that not every widget can have the focus. A widget doesn't need to listen the keydown DOM event. Rather, it shall override this method if necessary.

Default: fire the widget event (fireX(zk.Event, int)), and call parent's doKeyDown_ if the event propagation is not stopped (Event.stopped). It is the so-called event propagation.

See also ZK Client-side Reference: Notifications

Parameters:
evt - the widget event. The original DOM event and target can be retrieved by Event.domEvent and Event.domTarget
See Also:
doKeyUp_(zk.Event), doKeyPress_(zk.Event)

doKeyUp_

protected void doKeyUp_(Event evt)
Called when the user presses up a key when this widget has the focus (focus(int)).

Notice that not every widget can have the focus. A widget doesn't need to listen the keyup DOM event. Rather, it shall override this method if necessary.

Default: fire the widget event (fireX(zk.Event, int)), and call parent's doKeyUp_ if the event propagation is not stopped (Event.stopped). It is the so-called event propagation.

See also ZK Client-side Reference: Notifications

Parameters:
evt - the widget event. The original DOM event and target can be retrieved by Event.domEvent and Event.domTarget
See Also:
doKeyDown_(zk.Event), doKeyPress_(zk.Event)

doKeyPress_

protected void doKeyPress_(Event evt)
Called when the user presses a key when this widget has the focus (focus(int)).

Notice that not every widget can have the focus. A widget doesn't need to listen the keypress DOM event. Rather, it shall override this method if necessary.

Default: fire the widget event (fireX(zk.Event, int)), and call parent's doKeyPress_ if the event propagation is not stopped (Event.stopped). It is the so-called event propagation.

See also ZK Client-side Reference: Notifications

Parameters:
evt - the widget event. The original DOM event and target can be retrieved by Event.domEvent and Event.domTarget
See Also:
doKeyDown_(zk.Event), doKeyUp_(zk.Event)

doSwipe_

protected void doSwipe_(Event evt)
Called when the user swipe left/right/up/down this widget.

For example,


var opts = evt.opts, dir = opts.dir;
switch (dir) {
case 'left': doSwipeLeft(); break;
case 'right': doSwipeRight(); break;
case 'up': doSwipeUp(); break;
case 'down': doSwipeDown(); break;
}
To define swipe direction rather than default condition,

var opts = evt.opts, start = opts.start, stop = opts.stop,
        dispT = stop.time - start.time,
        deltaX = start.coords[0] - stop.coords[0],
        deltaY = start.coords[1] - stop.coords[1],
        dispX = Math.abs(deltaX),
        dispY = Math.abs(deltaY);

//if swipe time is less than 500ms, it is considered as swipe event
if (dispT < 500) {
        //if horizontal displacement is larger than 30px and vertical displacement is smaller than 75px, it is considered swipe left/right
        if (dispX > 30 && dispY < 75)
                //swipe left if deltaX > 0

        //if vertical displacement is large than 30px and horizontal displacement is smaller than 75px, it is considered swipe up/down
        else if (dispY > 30 && dispX < 75)
                //swipe up if deltaY > 0
}

Default: fire the widget event (fireX(zk.Event, int)), and call parent's doSwipe_ if the event propagation is not stopped (Event.stopped). It is the so-called event propagation.

Parameters:
evt - the widget event.
Since:
6.5.0

doFocus_

protected void doFocus_(Event evt)
A utility to simplify the listening of onFocus. Unlike other doXxx_ (such as doClick_(zk.Event)), a widget needs to listen the onFocus event explicitly if it might gain and lose the focus.

For example,


var fn = this.$n('focus');
this.domListen_(fn, 'onFocus', 'doFocus_');
this.domListen_(fn, 'onBlur', 'doBlur_');

Of course, you can listen it with jQuery DOM-level utilities, if you pefer to handle it differently.

Default: fire the widget event (fireX(zk.Event, int)), and call parent's doFocus_ if the event propagation is not stopped (Event.stopped). It is the so-called event propagation.

See also ZK Client-side Reference: Notifications

Parameters:
evt - the widget event. The original DOM event and target can be retrieved by Event.domEvent and Event.domTarget
See Also:
doBlur_(zk.Event)

doBlur_

protected void doBlur_(Event evt)
A utility to simplify the listening of onBlur. Unlike other doXxx_ (such as doClick_(zk.Event)), a widget needs to listen the onBlur event explicitly if it might gain and lose the focus.

For example,


var fn = this.$n('focus');
this.domListen_(fn, 'onFocus', 'doFocus_');
this.domListen_(fn, 'onBlur', 'doBlur_');

Of course, you can listen it with jQuery DOM-level utilities, if you pefer to handle it differently.

Default: fire the widget event (fireX(zk.Event, int)), and call parent's doBlur_ if the event propagation is not stopped (Event.stopped). It is the so-called event propagation.

See also ZK Client-side Reference: Notifications

Parameters:
evt - the widget event. The original DOM event and target can be retrieved by Event.domEvent and Event.domTarget
See Also:
doFocus_(zk.Event)

doResizeScroll_

protected void doResizeScroll_()
Resize zul.Scrollbar size after child added/removed or hide/show.

Since:
6.5.0

domListen_

protected Widget domListen_(DOMElement node,
                            String evtnm,
                            Object fn,
                            String keyword)
Registers an DOM event listener for the specified DOM element (aka., node). You can use jQuery to listen the DOM event directly, or use this method instead.

bind_: function () {
  this.$supers('bind_', arguments);
  this.domListen_(this.$n(), "onChange"); //fn is omitted, so _doChange is assumed
  this.domListen_(this.$n("foo"), "onSelect", "_doFooSelect"); //specify a particular listener
},
unbind_: function () {
  this.domUnlisten_(this.$n(), "onChange"); //unlisten
  this.domUnlisten_(this.$n("foo"), "onSelect", "_doFooSelect");
  this.$supers('unbind_', arguments);
},
_doChange_: function (evt) { //evt is an instance of zk.Event
  //event listener
},
_doFooSelect: function (evt) {
}
See also ZK Client-side Reference: Notifications

Design Mode

If a widget is created and controlled by ZK Weaver for visual design, we call the widget is in design mode ($weave). Furthermore, this method does nothing if the widget is in the design mode. Thus, if you want to listen a DOM event (Event), you have to use jQuery directly.

Parameters:
node - a node of this widget. It is usually retrieved by $n(_global_.String).
evtnm - the event name to register, such as onClick.
fn - the name (String) of the member method to handle the event, or the function (Function). It is optional. If omitted, _doEvtnm is assumed, where evtnm is the value passed thru the evtnm argument. For example, if the event name is onFocus, then the method is assumed to be _doFocus.
keyword - the extra argumenet for the function, which is passed into the callback function. (since 7.0)
Returns:
zk.Widget this widget
See Also:
domUnlisten_(_global_.DOMElement, _global_.String, zk.Object, _global_.String)

domUnlisten_

protected Widget domUnlisten_(DOMElement node,
                              String evtnm,
                              Object fn,
                              String keyword)
Un-registers an event listener for the specified DOM element (aka., node).

Refer to domListen_(_global_.DOMElement, _global_.String, zk.Object, _global_.String) for more information.

Parameters:
node - a node of this widget. It is usually retrieved by $n(_global_.String).
evtnm - the event name to register, such as onClick.
fn - the name (String) of the member method to handle the event, or the function (Function). It is optional. If omitted, _doEvtnm is assumed, where evtnm is the value passed thru the evtnm argument. For example, if the event name is onFocus, then the method is assumed to be _doFocus.
keyword - the extra argumenet for the function, which is passed into the callback function. (since 7.0)
Returns:
zk.Widget this widget
See Also:
domListen_(_global_.DOMElement, _global_.String, zk.Object, _global_.String)

listenOnFitSize_

protected void listenOnFitSize_()
Listens to onFitSize event. Override if a subclass wants to skip listening or have extra processing.

Since:
5.0.8
See Also:
unlistenOnFitSize_()

unlistenOnFitSize_

protected void unlistenOnFitSize_()
Unlistens to onFitSize event. Override if a subclass wants to skip listening or have extra processing.

Since:
5.0.8
See Also:
listenOnFitSize_()

fromPageCoord

public Offset fromPageCoord(int x,
                            int y)
Converts a coordinate related to the browser window into the coordinate related to this widget.

Parameters:
x - the X coordinate related to the browser window
y - the Y coordinate related to the browser window
Returns:
Offset the coordinate related to this widget (i.e., [0, 0] is the left-top corner of the widget).
Since:
5.0.2

isWatchable_

protected boolean isWatchable_(String name,
                               Widget p,
                               Map cache)
Returns if the given watch shall be fired for this widget. It is called by zWatch to check if the given watch shall be fired

Parameters:
name - the name of the watch, such as onShow
p - the parent widget causing the watch event. It is null if it is not caused by zWatch.fireDown(_global_.String, java.lang.Object, _global_.Map, java.lang.Object...).
cache - a map of cached result (since 5.0.8). Ignored if null. If specified, the result will be stored and used to speed up the processing
Returns:
boolean
Since:
5.0.3

ignoreDescendantFloatUp_

protected boolean ignoreDescendantFloatUp_()
A widget call this function of its ancestor if it wants to know whether its ancestor prefer ignore float up event of it self.

Default: false.

Returns:
boolean
Since:
6.0.0

beforeParentChanged_

protected void beforeParentChanged_(Widget newparent)
A callback called before the parent is changed.

Parameters:
newparent - the new parent (null if it is removed) The previous parent can be found by parent.
See Also:
onChildAdded_(zk.Widget), onChildRemoved_(zk.Widget), afterParentChanged_(zk.Widget)

afterParentChanged_

protected void afterParentChanged_(Widget oldparent)
A callback called after the parent has been changed.

Parameters:
oldparent - the previous parent (null if it was not attached) The current parent can be found by parent.
Since:
5.0.4
See Also:
beforeParentChanged_(zk.Widget)

onChildAdded_

protected void onChildAdded_(Widget child)
A callback called after a child has been added to this widget.

Notice: when overriding this method, onChildReplaced_(zk.Widget, zk.Widget) is usually required to override, too.

Parameters:
child - the child being added
See Also:
beforeParentChanged_(zk.Widget), onChildRemoved_(zk.Widget)

onChildRemoved_

protected void onChildRemoved_(Widget child)
A callback called after a child has been removed to this widget.

Notice: when overriding this method, onChildReplaced_(zk.Widget, zk.Widget)

Parameters:
child - the child being removed
See Also:
beforeParentChanged_(zk.Widget), onChildAdded_(zk.Widget)

onChildRenderDefer_

protected void onChildRenderDefer_(Widget child)
A callback called after a child has been delay rendered.

Parameters:
child - the child being rendered
Since:
6.5.1
See Also:
deferRedraw_(_global_.Array)

getZIndex

public int getZIndex()
Returns the Z index.

Returns:
int

setZIndex

public Widget setZIndex(int zIndex,
                        Map opts)
Sets the Z index.

Parameters:
zIndex - the Z index to assign to
opts - if opts.fire is specified, the onZIndex event will be triggered.
Returns:
zk.Widget this widget.

bindSwipe_

protected void bindSwipe_()
Bind swipe event to the widget on tablet device. It is called if HTML 5 data attribute (data-swipeable) is set to true.

You rarely need to override this method, unless you want to bind swipe behavior differently.

Default: use Swipe to implement swipe event.

Since:
6.5.0
See Also:
doSwipe_(zk.Event)

unbindSwipe_

protected void unbindSwipe_()
Unbind swipe event to the widget on tablet device. It is called if swipe event is unbound.

You rarely need to override this method, unless you want to unbind swipe event differently.

Since:
6.5.0
See Also:
doSwipe_(zk.Event)

bindDoubleTap_

protected void bindDoubleTap_()
Bind double click event to the widget on tablet device. It is called if the widget is listen to onDoubleClick event.

You rarely need to override this method, unless you want to implement double click behavior differently.

Since:
6.5.0
See Also:
doDoubleClick_(zk.Event)

unbindDoubleTap_

protected void unbindDoubleTap_()
Unbind double click event to the widget on tablet device. It is called if the widget is listen to onDoubleClick event.

You rarely need to override this method, unless you want to implement double click behavior differently.

Since:
6.5.0
See Also:
doDoubleClick_(zk.Event)

bindTapHold_

protected void bindTapHold_()
Bind right click event to the widget on tablet device. It is called if the widget is listen to onRightClick event.

You rarely need to override this method, unless you want to implement right click behavior differently.

Since:
6.5.1
See Also:
doRightClick_(zk.Event)

unbindTapHold_

protected void unbindTapHold_()
Unbind right click event to the widget on tablet device. It is called if the widget is listen to onRightClick event.

You rarely need to override this method, unless you want to implement right click behavior differently.

Since:
6.5.1
See Also:
doRightClick_(zk.Event)

$

public static Widget $(Object n,
                       Map opts)
Retrieves the widget.

Parameters:
n - the object to look for. If it is a string, it is assumed to be UUID, unless it starts with '$'. For example, zk.Widget.$('uuid') is the same as zk.Widget.$('#uuid'), and both look for a widget whose ID is 'uuid'. On the other hand, zk.Widget.$('$id') looks for a widget whose ID is 'id'.
If it is an DOM element (DOMElement), it will look up which widget it belongs to.
If the object is not a DOM element and has a property called target, then target is assumed. Thus, you can pass an instance of Event or Event, and the target widget will be returned.
opts - [optional] the options. Allowed values:
  • exact - id must exactly match uuid (i.e., uuid-xx ignored). It also implies strict (since 5.0.2)
  • strict - whether not to look up the parent node.(since 5.0.2) If omitted, false is assumed (and it will look up parent).
  • child - whether to ensure the given element is a child element of the widget's main element ($n(_global_.String)). In most cases, if ID of an element is xxx-yyy, the the element must be a child of the element whose ID is xxx. However, there is some exception such as the shadow of a window.
Returns:
zk.Widget

mimicMouseDown_

protected static void mimicMouseDown_(Widget wgt,
                                      boolean noFocusChange,
                                      int which)
Called to mimic the mouse down event fired by the browser. It is used for implement a widget. In most cases, you don't need to invoke this method.

However, it is useful if the widget you are implemented will 'eat' the mouse-down event so ZK Client Engine won't be able to intercept it at the document level.

Parameters:
wgt - the widget that receives the mouse-down event
noFocusChange - whether zk.currentFocus shall be changed to wgt.
which - the button number that was pressed.

getElementsByName

public static Array getElementsByName(String name)
Returns all elements with the given widget name.

Parameters:
name - the widget name widgetName.
Returns:
Array an array of DOMElement
Since:
5.0.2

getElementsById

public static Array getElementsById(String id)
Returns all elements with the given ID.

Parameters:
id - the id of a widget, id.
Returns:
Array an array of DOMElement
Since:
5.0.2

uuid

public static String uuid(String subId)
Converts an ID of a DOM element to UUID. It actually removes '-*'. For example, zk.Widget.uuid('z_aa-box') returns 'z_aa'.

Parameters:
subId - the ID of a DOM element
Returns:
String the uuid of the widget (notice that the widget might not exist)

nextUuid

public static String nextUuid()
Returns the next unique UUID for a widget. The UUID is unique in the whole browser window and does not conflict with the peer component's UUID.

This method is called automatically if $init(_global_.Map) is called without uuid.

Returns:
String the next unique UUID for a widget

isAutoId

public static boolean isAutoId(String uuid)
Deprecated. we cannot really detect at the client if UUID is generated automatically.

Parameters:
uuid - the UUID to test
Returns:
boolean

register

public static void register(String clsnm,
                            boolean blankPreserved)
Registers a widget class. It is called automatically if the widget is loaded by WPD loader, so you rarely need to invoke this method. However, if you create a widget class at run time, you have to call this method explicitly. Otherwise, className, getClass(_global_.String), and newInstance(_global_.String, _global_.Map) won't be applicable.

Notice that the class must be declared before calling this method. In other words, zk.$import(clsnm) must return the class of the specified class name.


zk.Widget.register('foo.Cool'); //class name
zk.Widget.getClass('cool'); //widget name

Parameters:
clsnm - the class name, such as zul.wnd.Window
blankPreserved - whether to preserve the whitespaces between child widgets when declared in iZUML. If true, a widget of clsnm will have a data member named blankPreserved (assigned with true). And, iZUML won't trim the whitespaces (aka., the blank text) between two adjacent child widgets.

getClass

public static Class getClass(String wgtnm)
Returns the class of the specified widget's name. For example,

zk.Widget.getClass('combobox');

Notice that null is returned if the widget is not loaded (or not exist) yet.

Parameters:
wgtnm - the widget name, such as textbox.
Returns:
zk.Class the class of the widget.
See Also:
newInstance(_global_.String, _global_.Map), register(_global_.String, boolean)

newInstance

public static Widget newInstance(String wgtnm,
                                 Map props)
Creates a widget by specifying the widget name. The widget name is the last part of the class name of a widget (and converting the first letter to lower case). For example, if a widget's class name is zul.inp.Textbox, then the widget name is textbox.

This method is usually used by tools, such as zk.zuml.Parser, rather than developers, since developers can create the widget directly if he knows the class name.

Parameters:
wgtnm - the widget name, such as textbox.
props - [optional] the properties that will be passed to $init(_global_.Map).
Returns:
zk.Widget
See Also:
getClass(_global_.String), register(_global_.String, boolean)


Copyright © 2005-2011 Potix Corporation. All Rights Reserved. SourceForge.net Logo