org.zkoss.zul
Class Button

java.lang.Object
  extended by org.zkoss.zk.ui.AbstractComponent
      extended by org.zkoss.zk.ui.HtmlBasedComponent
          extended by org.zkoss.zul.impl.XulElement
              extended by org.zkoss.zul.impl.LabelElement
                  extended by org.zkoss.zul.impl.LabelImageElement
                      extended by org.zkoss.zul.Button
All Implemented Interfaces:
java.io.Serializable, java.lang.Cloneable, Component, Disable, Scope, ComponentCtrl
Direct Known Subclasses:
Combobutton, Fileupload, MessageboxDlg.Button, Toolbarbutton

public class Button
extends LabelImageElement
implements Disable

A button.

Default getZclass(): z-button.(since 3.5.0)

Author:
tomyeh
See Also:
Serialized Form

Nested Class Summary
 
Nested classes/interfaces inherited from class org.zkoss.zul.impl.LabelImageElement
LabelImageElement.ExtraCtrl
 
Nested classes/interfaces inherited from class org.zkoss.zk.ui.AbstractComponent
AbstractComponent.Children
 
Field Summary
 
Fields inherited from class org.zkoss.zk.ui.HtmlBasedComponent
_zclass
 
Fields inherited from interface org.zkoss.zk.ui.Component
APPLICATION_SCOPE, COMPONENT_SCOPE, DESKTOP_SCOPE, PAGE_SCOPE, REQUEST_SCOPE, SESSION_SCOPE, SPACE_SCOPE
 
Fields inherited from interface org.zkoss.zk.ui.sys.ComponentCtrl
CE_BUSY_IGNORE, CE_DUPLICATE_IGNORE, CE_IMPORTANT, CE_NON_DEFERRABLE, CE_REPEAT_IGNORE
 
Constructor Summary
Button()
           
Button(java.lang.String label)
           
Button(java.lang.String label, java.lang.String image)
           
 
Method Summary
 java.lang.Object clone()
          Clones the component.
 java.lang.String getAutodisable()
          Returns a list of component IDs that shall be disabled when the user clicks this button.
 java.lang.String getDir()
          Returns the direction.
 java.lang.String getHref()
          Returns the href that the browser shall jump to, if an user clicks this button.
 java.lang.String getOrient()
          Returns the orient.
 int getTabindex()
          Returns the tab order of this component.
 java.lang.String getTarget()
          Returns the target frame or window.
 java.lang.String getType()
          Returns the button type.
 java.lang.String getUpload()
          Returns non-null if this button is used for file upload, or null otherwise.
 java.lang.String getZclass()
          Returns the ZK Cascading Style class(es) for this component.
protected  boolean isChildable()
          No child is allowed.
 boolean isDisabled()
          Returns whether it is disabled.
protected  void renderCrawlable(java.lang.String label)
          Renders the crawlable information.
protected  void renderProperties(ContentRenderer renderer)
          Renders the content of this component, excluding the enclosing tags and children.
 void setAutodisable(java.lang.String autodisable)
          Sets a list of component IDs that shall be disabled when the user clicks this button.
 void setDir(java.lang.String dir)
          Sets the direction to layout image.
 void setDisabled(boolean disabled)
          Sets whether it is disabled.
 void setHref(java.lang.String href)
          Sets the href.
 void setOrient(java.lang.String orient)
          Sets the orient to layout image.
 void setTabindex(int tabindex)
          Sets the tab order of this component.
 void setTarget(java.lang.String target)
          Sets the target frame or window.
 void setType(java.lang.String type)
          Sets the button type.
 void setUpload(java.lang.String upload)
          Sets the JavaScript class at the client to handle the upload if this button is used for file upload.
protected  void updateByClient(java.lang.String name, java.lang.Object value)
          Called when the widget running at the client asks the server to update a value.
 
Methods inherited from class org.zkoss.zul.impl.LabelImageElement
getExtraCtrl, getHoverImage, getHoverImageContent, getImage, getImageContent, getSrc, isImageAssigned, setHoverImage, setHoverImageContent, setHoverImageContent, setImage, setImageContent, setImageContent, setSrc
 
Methods inherited from class org.zkoss.zul.impl.LabelElement
getLabel, setLabel
 
Methods inherited from class org.zkoss.zul.impl.XulElement
getContext, getCtrlKeys, getPopup, getTooltip, setContext, setContext, setCtrlKeys, setPopup, setPopup, setTooltip, setTooltip
 
Methods inherited from class org.zkoss.zk.ui.HtmlBasedComponent
focus, getAction, getDraggable, getDroppable, getHeight, getHflex, getLeft, getRenderdefer, getSclass, getStyle, getTooltiptext, getTop, getVflex, getWidth, getZindex, getZIndex, service, setAction, setClass, setDraggable, setDroppable, setFocus, setHeight, setHeightDirectly, setHflex, setHflexDirectly, setLeft, setLeftDirectly, setRenderdefer, setSclass, setStyle, setTooltiptext, setTop, setTopDirectly, setVflex, setWidth, setWidthDirectly, setZclass, setZindex, setZIndex, setZIndexDirectly
 
Methods inherited from class org.zkoss.zk.ui.AbstractComponent
addAnnotation, addAnnotation, addClientEvent, addEventHandler, addEventListener, addEventListener, addForward, addForward, addForward, addForward, addMoved, addScopeListener, addSharedEventHandlerMap, appendChild, applyProperties, beforeChildAdded, beforeChildRemoved, beforeParentChanged, detach, didActivate, didActivate, didDeserialize, didDeserialize, disableClientUpdate, equals, getAnnotatedProperties, getAnnotatedPropertiesBy, getAnnotation, getAnnotation, getAnnotations, getAnnotations, getAnnotations, getAttribute, getAttribute, getAttribute, getAttributeOrFellow, getAttributes, getAttributes, getAuService, getAutag, getChildren, getClientEvents, getDefaultMold, getDefinition, getDesktop, getEventHandler, getEventHandlerNames, getEventListenerMap, getEventListeners, getFellow, getFellow, getFellowIfAny, getFellowIfAny, getFellows, getFirstChild, getId, getLastChild, getListenerIterator, getMold, getNextSibling, getPage, getParent, getPreviousSibling, getRoot, getSpaceOwner, getStubonly, getTemplate, getTemplateNames, getUuid, getWidgetAttribute, getWidgetAttributeNames, getWidgetClass, getWidgetListener, getWidgetListenerNames, getWidgetOverride, getWidgetOverrideNames, hasAttribute, hasAttribute, hasAttribute, hasAttributeOrFellow, hasFellow, hasFellow, insertBefore, invalidate, isInvalidated, isListenerAvailable, isVisible, onChildAdded, onChildRemoved, onPageAttached, onPageDetached, onWrongValue, query, queryAll, redraw, redrawChildren, removeAttribute, removeAttribute, removeAttribute, removeChild, removeEventListener, removeForward, removeForward, removeScopeListener, render, render, render, replace, response, response, response, service, sessionDidActivate, sessionWillPassivate, setAttribute, setAttribute, setAttribute, setAuService, setAutag, setDefinition, setDefinition, setId, setMold, setPage, setPageBefore, setParent, setStubonly, setStubonly, setTemplate, setVisible, setVisibleDirectly, setWidgetAttribute, setWidgetClass, setWidgetListener, setWidgetOverride, smartUpdate, smartUpdate, smartUpdate, smartUpdate, smartUpdate, smartUpdate, smartUpdate, smartUpdate, smartUpdate, smartUpdateWidgetListener, smartUpdateWidgetOverride, toString, willPassivate, willPassivate, willSerialize, willSerialize
 
Methods inherited from class java.lang.Object
finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

Button

public Button()

Button

public Button(java.lang.String label)

Button

public Button(java.lang.String label,
              java.lang.String image)
Method Detail

isDisabled

public boolean isDisabled()
Returns whether it is disabled.

Default: false.

Specified by:
isDisabled in interface Disable

setDisabled

public void setDisabled(boolean disabled)
Sets whether it is disabled.

Specified by:
setDisabled in interface Disable
See Also:
setAutodisable(java.lang.String)

getAutodisable

public java.lang.String getAutodisable()
Returns a list of component IDs that shall be disabled when the user clicks this button.

Since:
5.0.0

setAutodisable

public void setAutodisable(java.lang.String autodisable)
Sets a list of component IDs that shall be disabled when the user clicks this button.

To represent the button itself, the developer can specify self. For example, <button id="ok" autodisable="self,cancel"/> is the same as <button id="ok" autodisable="ok,cancel"/> that will disable both the ok and cancel buttons when an user clicks it.

The button being disabled will be enabled automatically once the client receives a response from the server. In other words, the server doesn't notice if a button is disabled with this method.

However, if you prefer to enable them later manually, you can prefix with '+'. For example, <button id="ok" autodisable="+self,+cancel"/>

Then, you have to enable them manually such as

if (something_happened){
  ok.setDisabled(false);
  cancel.setDisabled(false);

Default: null.

Since:
5.0.0

getDir

public java.lang.String getDir()
Returns the direction.

Default: "normal".


setDir

public void setDir(java.lang.String dir)
            throws WrongValueException
Sets the direction to layout image.

Parameters:
dir - either "normal" or "reverse".
Throws:
WrongValueException

getOrient

public java.lang.String getOrient()
Returns the orient.

Default: "horizontal".


setOrient

public void setOrient(java.lang.String orient)
               throws WrongValueException
Sets the orient to layout image.

Parameters:
orient - either "horizontal" or "vertical".
Throws:
WrongValueException

getType

public java.lang.String getType()
Returns the button type.

Default: "button".

Since:
5.0.4

setType

public void setType(java.lang.String type)
             throws WrongValueException
Sets the button type.

Default: "button". It is meaningful only if it is used with a HTML form. Refer to HTML Button Type for details.

Parameters:
type - either "button", "submit" or "reset".
Throws:
WrongValueException
Since:
5.0.4

getHref

public java.lang.String getHref()
Returns the href that the browser shall jump to, if an user clicks this button.

Default: null. If null, the button has no function unless you specify the onClick event listener.

If it is not null, the onClick event won't be sent.


setHref

public void setHref(java.lang.String href)
Sets the href.


getTarget

public java.lang.String getTarget()
Returns the target frame or window.

Note: it is useful only if href (setHref(java.lang.String)) is specified (i.e., use the onClick listener).

Default: null.


setTarget

public void setTarget(java.lang.String target)
Sets the target frame or window.

Parameters:
target - the name of the frame or window to hyperlink.

getTabindex

public int getTabindex()
Returns the tab order of this component.

Default: 0 (means the same as browser's default).


setTabindex

public void setTabindex(int tabindex)
                 throws WrongValueException
Sets the tab order of this component.

Throws:
WrongValueException

getUpload

public java.lang.String getUpload()
Returns non-null if this button is used for file upload, or null otherwise. Refer to setUpload(java.lang.String) for more details.

Since:
5.0.0

setUpload

public void setUpload(java.lang.String upload)
Sets the JavaScript class at the client to handle the upload if this button is used for file upload.

Default: null.

For example, the following example declares a button for file upload:

<button label="Upload" upload="true"
 onUpload="handle(event.media)"/>

As shown above, after the file is uploaded, an instance of UploadEvent is sent this component.

If you want to customize the handling of the file upload at the client, you can specify a JavaScript class when calling this method: <button upload="foo.Upload"/>

Another options for the upload can be specified as follows:

<button label="Upload" upload="true,maxsize=-1,multiple=true,native"

Note: if the options of the false or the customized handler (like foo.Upload) are not specified, the option of true is implicit by default.

Parameters:
upload - a JavaScript class to handle the file upload at the client, or "true" if the default class is used, or null or "false" to disable the file download (and then this button behaves like a normal button).
Since:
5.0.0

renderProperties

protected void renderProperties(ContentRenderer renderer)
                         throws java.io.IOException
Description copied from class: HtmlBasedComponent
Renders the content of this component, excluding the enclosing tags and children.

See also ZK Client-side Reference: Property Rendering

Overrides:
renderProperties in class LabelImageElement
Throws:
java.io.IOException

renderCrawlable

protected void renderCrawlable(java.lang.String label)
                        throws java.io.IOException
Description copied from class: LabelElement
Renders the crawlable information. It is called by LabelElement.renderProperties(org.zkoss.zk.ui.sys.ContentRenderer), and designed to be overriden if the deriving class wants to generate it differently.

Default: org.zkoss.zul.impl.Utils.renderCrawlableText(label)

Overrides:
renderCrawlable in class LabelElement
Throws:
java.io.IOException

getZclass

public java.lang.String getZclass()
Description copied from class: HtmlBasedComponent
Returns the ZK Cascading Style class(es) for this component. It usually depends on the implementation of the mold (@{link #getMold}).

Default: null (the default value depends on element).

HtmlBasedComponent.setZclass(java.lang.String)) will completely replace the default style of a component. In other words, the default style of a component is associated with the default value of HtmlBasedComponent.getZclass(). Once it is changed, the default style won't be applied at all. If you want to perform small adjustments, use HtmlBasedComponent.setSclass(java.lang.String) instead.

Overrides:
getZclass in class HtmlBasedComponent
See Also:
HtmlBasedComponent.getSclass()

clone

public java.lang.Object clone()
Description copied from interface: Component
Clones the component. All of its children and descendants are cloned. Also, ID are preserved.

Specified by:
clone in interface Component
Overrides:
clone in class LabelImageElement
Returns:
the new component. Notice that it doesn't belong to any page, nor desktop. It doesn't have a parent, either.

isChildable

protected boolean isChildable()
No child is allowed.

Overrides:
isChildable in class AbstractComponent

updateByClient

protected void updateByClient(java.lang.String name,
                              java.lang.Object value)
Description copied from class: AbstractComponent
Called when the widget running at the client asks the server to update a value. The update is caused by an AU request named setAttr (by invoking zk.Widget's smartUpdate at client).

By default, it does nothing but log a warning message, since it is not safe to allow the client to update a field arbitary.

However, if you'd like to allow the update for a particular component you could do one of the following

  1. For component developers: override this method to update the field directly. For example,
    protected void updateByClient(String name, Object value) {
            if ("disabled".equals(name))
                    setDisabled(name, ((Boolean)value).booleanValue());
            else
                    super.updateByClient(name, value);
  2. For application developers: set an attribute called org.zkoss.zk.ui.updateByClient to be true. Then, this method will use reflection to find out the setter to update the value. Nothing happens if the method is not found.
  3. Notice: this method will invoke AbstractComponent.disableClientUpdate(boolean) to disable any update to the client, when calling the setter.

    If you wanto enable the client update for all instances of a given component (though not recommended for the security reason), you could refer to here.

    See also zk.Widget.smartUpdate().

    Overrides:
    updateByClient in class AbstractComponent


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