org.zkoss.zk.ui
Class HtmlBasedComponent

java.lang.Object
  org.zkoss.zk.ui.AbstractComponent
      org.zkoss.zk.ui.HtmlBasedComponent

All Implemented Interfaces:

java.io.Serializable, java.lang.Cloneable, Component, Scope, ComponentCtrl

Direct Known Subclasses:

Applet, Borderlayout, Chosenbox, Flash, Fusionchart, HtmlMacroComponent, Iframe, Layout, Selectbox, Timer, XulElement

public abstract class HtmlBasedComponent
extends AbstractComponent

A skeletal implementation for HTML based components. It simplifies to implement methods common to HTML based components.

Events:
onClick, onDoubleClick, onRightClick, onDrop, onMouseOver, onMouseOut, onOK, onCacnel, onCtrlKey and onSwipe.

It supports

• getSclass() and getStyle().
• getWidth(), getHeight(), getLeft(), getTop(), getZIndex()
• focus()

Since:

5.0.0 supports onOK event., 5.0.0 supports onCancel event., 5.0.0 supports onCtrlKey event., 6.5.0 supports onSwipe event for tablet.

Author:

tomyeh

See Also:

Serialized Form

Nested Class Summary

protected class

HtmlBasedComponent.ExtraCtrl A utility class to implement getExtraCtrl().

Nested classes/interfaces inherited from class org.zkoss.zk.ui.AbstractComponent

AbstractComponent.Children

Field Summary

protected java.lang.String

_zclass The ZK CSS class.

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

protected

HtmlBasedComponent()

Method Summary

java.lang.Object	clone() Clones the component.
void	focus() Sets focus to this element.
java.lang.String	getAction() Returns the client-side action (CSA).
java.lang.String	getDraggable() Returns the identifier of a draggable type of objects, or "false" if not draggable (never null nor empty).
java.lang.String	getDroppable() Returns the identifier, or a list of identifiers of a droppable type of objects, or "false" if not droppable (never null nor empty).
java.lang.Object	getExtraCtrl() Returns the client control for this component.
java.lang.String	getHeight() Returns the height.
java.lang.String	getHflex() Returns horizontal flex hint of this component.
java.lang.String	getLeft() Returns the left position.
int	getRenderdefer() Returns the number of milliseconds before rendering this component at the client.
java.lang.String	getSclass() Returns the CSS class.
java.lang.String	getStyle() Returns the CSS style.
java.lang.String	getTooltiptext() Returns the text as the tooltip.
java.lang.String	getTop() Returns the top position.
java.lang.String	getVflex() Return vertical flex hint of this component.
java.lang.String	getWidth() Returns the width.
java.lang.String	getZclass() Returns the ZK Cascading Style class(es) for this component.
int	getZindex() Returns the Z index.
int	getZIndex() Returns the Z index.
protected void	renderProperties(ContentRenderer renderer) Renders the content of this component, excluding the enclosing tags and children.
void	service(AuRequest request, boolean everError) Processes an AU request.
void	setAction(java.lang.String action) Sets the client-side action (CSA).
void	setClass(java.lang.String sclass) Sets the CSS class.
void	setDraggable(java.lang.String draggable) Sets "true" or "false" to denote whether a component is draggable, or an identifier of a draggable type of objects.
void	setDroppable(java.lang.String droppable) Sets "true" or "false" to denote whether a component is droppable, or a list of identifiers of draggable types of objects that could be dropped to this component.
void	setFocus(boolean focus) Sets focus to this element.
void	setHeight(java.lang.String height) Sets the height.
protected void	setHeightDirectly(java.lang.String height) Sets the height directly without sending back the result (smart update) to the client
void	setHflex(java.lang.String flex) Sets horizontal flex hint of this component.
protected void	setHflexDirectly(java.lang.String hflex) Sets the hflex directly without sending back the result (smart update) to the client
void	setLeft(java.lang.String left) Sets the left position.
protected void	setLeftDirectly(java.lang.String left) Sets the left directly without sending back the result (smart update) to the client
void	setRenderdefer(int ms) Sets the number of milliseconds before rendering this component at the client.
void	setSclass(java.lang.String sclass) Sets the CSS class.
void	setStyle(java.lang.String style) Sets the CSS style.
void	setTooltiptext(java.lang.String tooltiptext) Sets the text as the tooltip.
void	setTop(java.lang.String top) Sets the top position.
protected void	setTopDirectly(java.lang.String top) Sets the top directly without sending back the result (smart update) to the client
void	setVflex(java.lang.String flex) Sets vertical flexibility hint of this component.
void	setWidth(java.lang.String width) Sets the width.
protected void	setWidthDirectly(java.lang.String width) Sets the width directly without sending back the result (smart update) to the client
void	setZclass(java.lang.String zclass) Sets the ZK Cascading Style class(es) for this component.
void	setZindex(int zIndex) Sets the Z index.
void	setZIndex(int zIndex) Sets the Z index.
protected void	setZIndexDirectly(int zIndex) Sets the z-index directly without sending back the result (smart update) to the client

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, isChildable, 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, updateByClient, willPassivate, willPassivate, willSerialize, willSerialize

Methods inherited from class java.lang.Object

finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

_zclass

protected java.lang.String _zclass

The ZK CSS class.

Constructor Detail

HtmlBasedComponent

protected HtmlBasedComponent()

Method Detail

getLeft

public java.lang.String getLeft()

Returns the left position.

setLeft

public void setLeft(java.lang.String left)

Sets the left position.

If you want to specify right, use setStyle(java.lang.String) instead. For example, setStyle("right: 0px");

Parameters:

left - the left position. Remember to specify px, pt or %.

getTop

public java.lang.String getTop()

Returns the top position.

setTop

public void setTop(java.lang.String top)

Sets the top position.

If you want to specify bottom, use setStyle(java.lang.String) instead. For example, setStyle("bottom: 0px");

Parameters:

top - the top position. Remember to specify px, pt or %.

getZIndex

public int getZIndex()

Returns the Z index.

Default: -1 (means system default;

setZIndex

public void setZIndex(int zIndex)

Sets the Z index.

getZindex

public int getZindex()

Returns the Z index. It is the same as getZIndex().

Since:

3.5.2

setZindex

public void setZindex(int zIndex)

Sets the Z index. It is the same as setZIndex(int).

Since:

3.5.2

getHeight

public java.lang.String getHeight()

Returns the height. If null, the best fit is used.

Default: null.

setHeight

public void setHeight(java.lang.String height)

Sets the height. If null, the best fit is used.

getWidth

public java.lang.String getWidth()

Returns the width. If null, the best fit is used.

Default: null.

setWidth

public void setWidth(java.lang.String width)

Sets the width. If null, the best fit is used.

See Also:

setWidthDirectly(java.lang.String), AbstractComponent.disableClientUpdate(boolean)

setWidthDirectly

protected void setWidthDirectly(java.lang.String width)

Sets the width directly without sending back the result (smart update) to the client

Since:

5.0.4

setHeightDirectly

protected void setHeightDirectly(java.lang.String height)

Sets the height directly without sending back the result (smart update) to the client

Since:

5.0.4

setLeftDirectly

protected void setLeftDirectly(java.lang.String left)

Sets the left directly without sending back the result (smart update) to the client

Since:

5.0.4

setTopDirectly

protected void setTopDirectly(java.lang.String top)

Sets the top directly without sending back the result (smart update) to the client

Since:

5.0.4

setZIndexDirectly

protected void setZIndexDirectly(int zIndex)

Sets the z-index directly without sending back the result (smart update) to the client

Since:

5.0.4

setHflexDirectly

protected void setHflexDirectly(java.lang.String hflex)

Sets the hflex directly without sending back the result (smart update) to the client

Since:

5.0.6

getTooltiptext

public java.lang.String getTooltiptext()

Returns the text as the tooltip.

Default: null.

setTooltiptext

public void setTooltiptext(java.lang.String tooltiptext)

Sets the text as the tooltip.

getZclass

public java.lang.String getZclass()

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

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 getZclass(). Once it is changed, the default style won't be applied at all. If you want to perform small adjustments, use setSclass(java.lang.String) instead.

Since:

3.5.1

See Also:

getSclass()

setZclass

public void setZclass(java.lang.String zclass)

Sets the ZK Cascading Style class(es) for this component. It usually depends on the implementation of the mold (@{link #getMold}).

Parameters:

zclass - the style class used to apply to the whole widget.

Since:

3.5.0

See Also:

setSclass(java.lang.String), getZclass()

getSclass

public java.lang.String getSclass()

Returns the CSS class.

Default: null.

The default styles of ZK components doesn't depend on the value of getSclass(). Rather, setSclass(java.lang.String) is provided to perform small adjustment, e.g., only changing the font size. In other words, the default style is still applied if you change the value of getSclass(), unless you override it. To replace the default style completely, use setZclass(java.lang.String) instead.

See Also:

getZclass()

setSclass

public void setSclass(java.lang.String sclass)

Sets the CSS class.

See Also:

setZclass(java.lang.String)

setClass

public void setClass(java.lang.String sclass)

Sets the CSS class. This method is a bit confused with Java's class, but we provide it for XUL compatibility. The same as setSclass(java.lang.String).

getStyle

public java.lang.String getStyle()

Returns the CSS style.

Default: null.

setStyle

public void setStyle(java.lang.String style)

Sets the CSS style.

setDraggable

public void setDraggable(java.lang.String draggable)

Sets "true" or "false" to denote whether a component is draggable, or an identifier of a draggable type of objects.

The simplest way to make a component draggable is to set this attribute to true. To disable it, set this to false.

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.

Parameters:

draggable - "false", "" or null to denote non-draggable; "true" for draggable with anonymous identifier; others for an identifier of draggable.
Notice that if the parent is DragControl and draggable is null, then it means draggable.

getDraggable

public java.lang.String getDraggable()

Returns the identifier of a draggable type of objects, or "false" if not draggable (never null nor empty).

setDroppable

public void setDroppable(java.lang.String droppable)

Sets "true" or "false" to denote whether a component is droppable, or a list of identifiers of draggable types of objects that could be dropped to this component.

The simplest way to make a component droppable is to set this attribute to true. To disable it, set this to false.

If there are several types of draggable objects and this component accepts only some of them, you could assign a list of identifiers that this component accepts, separated by comma. For example, if this component accepts 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 component accept (to be dropped in).

getDroppable

public java.lang.String getDroppable()

Returns the identifier, or a list of identifiers of a droppable type of objects, or "false" if not droppable (never null nor empty).

focus

public void focus()

Sets focus to this element. If an element does not accept focus, this method has no effect.

setFocus

public void setFocus(boolean focus)

Sets focus to this element. It is same as focus(), but used to allow ZUML to set focus to particular component.

<textbox focus="true"/>

Parameters:

focus - whether to set focus. If false, this method has no effect.

Since:

3.0.5

setVflex

public void setVflex(java.lang.String flex)

Sets vertical flexibility hint of this component.

Number flex indicates how this component's container distributes remaining empty space among its children vertically. Flexible component grow and shrink to fit their given space. Flexible components with larger flex values will be made larger than components with lower flex values, at the ratio determined by all flexible components. The actual flex value is not relevant unless there are other flexible components within the same container. Once the default sizes of components in a container are calculated, the remaining space in the container is divided among the flexible components, 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 component to enclose all of its children components. That is, the flexible component grow and shrink to fit its children components.

Parameters:

flex - the vertical flex hint.

Since:

5.0.0

See Also:

setHflex(java.lang.String), getVflex()

getVflex

public java.lang.String getVflex()

Return vertical flex hint of this component.

Default: null

Returns:

vertical flex hint of this component.

Since:

5.0.0

See Also:

setVflex(java.lang.String)

setHflex

public void setHflex(java.lang.String flex)

Sets horizontal flex hint of this component.

Number flex indicates how this component's container distributes remaining empty space among its children horizontally. Flexible component grow and shrink to fit their given space. Flexible components with larger flex values will be made larger than components with lower flex values, at the ratio determined by all flexible components. The actual flex value is not relevant unless there are other flexible components within the same container. Once the default sizes of components in a container are calculated, the remaining space in the container is divided among the flexible components, 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 component to enclose all of its children components. That is, the flexible component grow and shrink to fit its children components.

Parameters:

flex - horizontal flex hint of this component.

Since:

5.0.0

See Also:

setVflex(java.lang.String), getHflex()

getHflex

public java.lang.String getHflex()

Returns horizontal flex hint of this component.

Default: null

Returns:

horizontal flex hint of this component.

Since:

5.0.0

See Also:

setHflex(java.lang.String)

getRenderdefer

public int getRenderdefer()

Returns the number of milliseconds before rendering this component at the client.

Default: -1 (don't wait).

Since:

5.0.2

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 sophisticated 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-renderdefer.

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 rendered).

Since:

5.0.2

getAction

public java.lang.String getAction()

Returns the client-side action (CSA).

Default: null (no CSA at all)

Since:

5.0.6

setAction

public void setAction(java.lang.String action)

Sets the client-side action (CSA).

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

You could specify the effects as follows:
show: slideDown({duration:1000})

Security Tips: the action is not encoded and it is OK to embed JavaScript, so, if you want to allow users to specify the action, you have to encode it.

Note for developers upgraded from ZK 3: CSA's format is different and limited. In additions, it is part of HtmlBasedComponent.

Since:

5.0.6

renderProperties

protected void renderProperties(ContentRenderer renderer)
                         throws java.io.IOException

Renders the content of this component, excluding the enclosing tags and children.

See also ZK Client-side Reference: Property Rendering

Overrides:

renderProperties in class AbstractComponent

Throws:

java.io.IOException

Since:

5.0.0

service

public void service(AuRequest request,
                    boolean everError)

Processes an AU request.

Default: it handles onClick, onDoubleClick, onRightClick onMove, onSize, onZIndex.

Specified by:

service in interface ComponentCtrl

Overrides:

service in class AbstractComponent

everError - whether any error ever occurred before processing this request.

Since:

5.0.0

See Also:

AbstractComponent.setAuService(org.zkoss.zk.au.AuService)

getExtraCtrl

public java.lang.Object getExtraCtrl()

Returns the client control for this component. It is used only by component developers.

Default: creates an instance of HtmlBasedComponent.ExtraCtrl.

Specified by:

getExtraCtrl in interface ComponentCtrl

Overrides:

getExtraCtrl in class AbstractComponent

Returns:

null if no special handling required. If the component requires some special controls, it could return an object that implements one or several interfaces in the org.zkoss.zk.ui.ext.render package. For example, Cropper.

See Also:

ComponentCtrl.getExtraCtrl()

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 AbstractComponent

Returns:

the new component. Notice that it doesn't belong to any page, nor desktop. It doesn't have a parent, either.