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, HtmlBasedComponent, Component, ComponentCtrl

Direct Known Subclasses:

HtmlMacroComponent

public abstract class HtmlBasedComponent
extends AbstractComponent
implements HtmlBasedComponent

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

It supports

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

Author:

tomyeh

See Also:

Serialized Form

Nested Class Summary

protected class

HtmlBasedComponent.ExtraCtrl A utility class to implement AbstractComponent.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.
protected static int	RS_NO_DISPLAY Used by getRealStyleFlags() to denote that getRealStyle() shall not generate the display style.
protected static int	RS_NO_HEIGHT Used by getRealStyleFlags() to denote that getRealStyle() shall not generate the height style.
protected static int	RS_NO_WIDTH Used by getRealStyleFlags() to denote that getRealStyle() shall not generate the width style.

Fields inherited from class org.zkoss.zk.ui.AbstractComponent

_visible

Fields inherited from interface org.zkoss.zk.ui.Component

APPLICATION_SCOPE, COMPONENT_SCOPE, DESKTOP_SCOPE, PAGE_SCOPE, REQUEST_SCOPE, SESSION_SCOPE, SPACE_SCOPE

Constructor Summary

protected

HtmlBasedComponent()

Method Summary

void	focus() Sets focus to this element.
protected java.lang.String	getAllOnClickAttrs() Returns the attributes for onClick, onRightClick and onDoubleClick by checking whether the corresponding listeners are added, or null if none is added.
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 of a droppable type of objects, or "false" if not droppable (never null nor empty).
java.lang.String	getHeight() Returns the height.
java.lang.String	getInnerAttrs() Returns the interior attributes for generating the inner HTML tag; never return null.
java.lang.String	getLeft() Returns the left position.
java.lang.String	getMoldSclass() Deprecated. As of release 3.5.1, replaced with getZclass().
java.lang.String	getOuterAttrs() Returns the exterior attributes for generating the enclosing HTML tag; never return null.
protected java.lang.String	getRealSclass() Returns the real style class that will be generated to the client (when getOuterAttrs() is called).
protected java.lang.String	getRealStyle() Returns the real style that will be generated to client (when getOuterAttrs() is called).
protected int	getRealStyleFlags() Returns a combination of RS_NO_WIDTH and RS_NO_HEIGHT.
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	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 java.lang.Object	newExtraCtrl() Used by AbstractComponent.getExtraCtrl() to create a client control.
void	redraw(java.io.Writer out) Redraws this component.
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 droped to this component.
void	setFocus(boolean focus) Sets focus to this element.
void	setHeight(java.lang.String height) Sets the height.
void	setLeft(java.lang.String left) Sets the left position.
void	setMoldSclass(java.lang.String moldSclass) Deprecated. As of release 3.5.1, replaced with setZclass(java.lang.String).
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.
void	setWidth(java.lang.String width) Sets the width.
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.

Methods inherited from class org.zkoss.zk.ui.AbstractComponent

addAnnotation, addAnnotation, addEventHandler, addEventListener, addForward, addForward, addForward, addForward, addMoved, addSharedAnnotationMap, addSharedEventHandlerMap, appendAsapAttr, appendAsapAttr, appendChild, applyProperties, clone, containsVariable, detach, equals, getAnnotatedProperties, getAnnotatedPropertiesBy, getAnnotation, getAnnotation, getAnnotations, getAnnotations, getAttribute, getAttribute, getAttributes, getAttributes, getChildren, getCommand, getDefinition, getDesktop, getEventHandler, getEventHandlerNames, getExtraCtrl, getFellow, getFellowIfAny, getFellows, getFirstChild, getId, getLastChild, getListenerIterator, getMold, getMoldURI, getNamespace, getNextSibling, getPage, getParent, getPreviousSibling, getRoot, getSpaceOwner, getUuid, getVariable, hasFellow, insertBefore, invalidate, isAsapRequired, isChildable, isInvalidated, isListenerAvailable, isVisible, newChildren, onChildAdded, onChildRemoved, onDrawNewChild, onPageAttached, onPageDetached, onWrongValue, removeAttribute, removeAttribute, removeChild, removeEventListener, removeForward, removeForward, response, sessionDidActivate, sessionWillPassivate, setAttribute, setAttribute, setComponentDefinition, setId, setMold, setPage, setPageBefore, setParent, setVariable, setVisible, smartUpdate, smartUpdate, smartUpdate, smartUpdateDeferred, smartUpdateValues, toString, unsetVariable

Methods inherited from class java.lang.Object

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

Methods inherited from interface org.zkoss.zk.ui.Component

addEventListener, addForward, addForward, addForward, addForward, appendChild, applyProperties, clone, containsVariable, detach, getAttribute, getAttribute, getAttributes, getAttributes, getChildren, getDefinition, getDesktop, getFellow, getFellowIfAny, getFellows, getFirstChild, getId, getLastChild, getListenerIterator, getMold, getNamespace, getNextSibling, getPage, getParent, getPreviousSibling, getRoot, getSpaceOwner, getUuid, getVariable, insertBefore, invalidate, isChildable, isInvalidated, isListenerAvailable, isVisible, removeAttribute, removeAttribute, removeChild, removeEventListener, removeForward, removeForward, setAttribute, setAttribute, setId, setMold, setPage, setPageBefore, setParent, setVariable, setVisible, unsetVariable

Field Detail

_zclass

protected java.lang.String _zclass

The ZK CSS class.

RS_NO_WIDTH

protected static final int RS_NO_WIDTH

Used by getRealStyleFlags() to denote that getRealStyle() shall not generate the width style.

See Also:

Constant Field Values

RS_NO_HEIGHT

protected static final int RS_NO_HEIGHT

Used by getRealStyleFlags() to denote that getRealStyle() shall not generate the height style.

See Also:

Constant Field Values

RS_NO_DISPLAY

protected static final int RS_NO_DISPLAY

Used by getRealStyleFlags() to denote that getRealStyle() shall not generate the display style.

See Also:

Constant Field Values

Constructor Detail

HtmlBasedComponent

protected HtmlBasedComponent()

Method Detail

getLeft

public java.lang.String getLeft()

Returns the left position.

Specified by:

getLeft in interface HtmlBasedComponent

setLeft

public void setLeft(java.lang.String left)

Sets the left position.

Specified by:

setLeft in interface HtmlBasedComponent

getTop

public java.lang.String getTop()

Returns the top position.

Specified by:

getTop in interface HtmlBasedComponent

setTop

public void setTop(java.lang.String top)

Sets the top position.

Specified by:

setTop in interface HtmlBasedComponent

getZIndex

public int getZIndex()

Returns the Z index.

Default: -1 (means system default;

Specified by:

getZIndex in interface HtmlBasedComponent

setZIndex

public void setZIndex(int zIndex)

Sets the Z index.

Specified by:

setZIndex in interface HtmlBasedComponent

getZindex

public int getZindex()

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

Specified by:

getZindex in interface HtmlBasedComponent

Since:

3.5.2

setZindex

public void setZindex(int zIndex)

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

Specified by:

setZindex in interface HtmlBasedComponent

Since:

3.5.2

getHeight

public java.lang.String getHeight()

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

Default: null.

Specified by:

getHeight in interface HtmlBasedComponent

setHeight

public void setHeight(java.lang.String height)

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

Specified by:

setHeight in interface HtmlBasedComponent

getWidth

public java.lang.String getWidth()

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

Default: null.

Specified by:

getWidth in interface HtmlBasedComponent

setWidth

public void setWidth(java.lang.String width)

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

Specified by:

setWidth in interface HtmlBasedComponent

getTooltiptext

public java.lang.String getTooltiptext()

Returns the text as the tooltip.

Default: null.

Specified by:

getTooltiptext in interface HtmlBasedComponent

setTooltiptext

public void setTooltiptext(java.lang.String tooltiptext)

Sets the text as the tooltip.

Specified by:

setTooltiptext in interface HtmlBasedComponent

getMoldSclass

public java.lang.String getMoldSclass()

Deprecated. As of release 3.5.1, replaced with getZclass().

setMoldSclass

public void setMoldSclass(java.lang.String moldSclass)

Deprecated. As of release 3.5.1, replaced with setZclass(java.lang.String).

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.

Specified by:

getZclass in interface HtmlBasedComponent

Since:

3.5.1

See Also:

getSclass(), getRealSclass()

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

Specified by:

setZclass in interface HtmlBasedComponent

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.

Specified by:

getSclass in interface HtmlBasedComponent

See Also:

getRealSclass(), getZclass()

setSclass

public void setSclass(java.lang.String sclass)

Sets the CSS class.

Specified by:

setSclass in interface HtmlBasedComponent

See Also:

setZclass(java.lang.String)

setClass

public final 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.

Specified by:

getStyle in interface HtmlBasedComponent

setStyle

public void setStyle(java.lang.String style)

Sets the CSS style.

Specified by:

setStyle in interface HtmlBasedComponent

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.

Specified by:

setDraggable in interface HtmlBasedComponent

Parameters:

draggable - "false", null or "" to denote non-draggable; "true" for draggable with anonymous identifier; others for an identifier of draggable.

getDraggable

public final 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 droped 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 accpets dg1 and dg2, then assign "dg1, dg2" to this attribute.

Specified by:

setDroppable in interface HtmlBasedComponent

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 compoent accept (to be dropped in).

getDroppable

public final java.lang.String getDroppable()

Returns the identifier 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.

Specified by:

focus in interface HtmlBasedComponent

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"/>

Specified by:

setFocus in interface HtmlBasedComponent

Parameters:

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

Since:

3.0.5

getAllOnClickAttrs

protected java.lang.String getAllOnClickAttrs()

Returns the attributes for onClick, onRightClick and onDoubleClick by checking whether the corresponding listeners are added, or null if none is added.

Since:

3.0.5

getOuterAttrs

public java.lang.String getOuterAttrs()

Returns the exterior attributes for generating the enclosing HTML tag; never return null.

Used only by component developers.

Default: Generates the tooltip text, style, sclass, draggable and droppable attribute if necessary. In other words, the corresponding attribute is generated if getTooltiptext(), getRealStyle(), getSclass(), getDraggable(), getDroppable() are defined.

You have to call both getOuterAttrs() and getInnerAttrs() to generate complete attributes.

For simple components that all attributes are put on the outest HTML element, all you need is as follows.

<xx id="${self.uuid}"${self.outerAttrs}${self.innerAttrs}>

If you want to put attributes in a nested HTML element, you shall use the following pattern. Notice: if getInnerAttrs() in a different tag, the tag must be named with "${self.uuid}!real".

<xx id="${self.uuid}"${self.outerAttrs}>
 <yy id="${self.uuid}!real"${self.innerAttrs}>...

Note: This class handles non-deferrable event listeners automatically. However, you have to invoke AbstractComponent.appendAsapAttr(java.lang.StringBuffer, java.lang.String) for each event the component handles in getOuterAttrs() as follows.

        appendAsapAttr(sb, Events.ON_OPEN);
  appendAsapAttr(sb, Events.ON_CHANGE);

Theorectically, you could put any attributes in either getInnerAttrs() or getOuterAttrs(). However, zkau.js assumes all attributes are put at the outer one. If you want something different, you have to provide your own setAttr (refer to how checkbox is implemented).

getInnerAttrs

public java.lang.String getInnerAttrs()

Returns the interior attributes for generating the inner HTML tag; never return null.

Used only by component developers.

Default: empty string. Refer to getOuterAttrs() for more details.

getRealSclass

protected java.lang.String getRealSclass()

Returns the real style class that will be generated to the client (when getOuterAttrs() is called).

Default: it simply returns the catenation of getSclass() and getZclass() (since 3.5.0).

Derived classes might override it to provide, say, dual style classes. For example,

final String sclass = getSclass();
return sclass != null ? sclass + " my-addon": "myaddon";

Since:

3.0.0

See Also:

getZclass()

getRealStyle

protected java.lang.String getRealStyle()

Returns the real style that will be generated to client (when getOuterAttrs() is called).

Default: this method will append width, height and others to setStyle(java.lang.String) (never null).

Use getRealStyleFlags() to control what attributes to exclude.

getRealStyleFlags

protected int getRealStyleFlags()

Returns a combination of RS_NO_WIDTH and RS_NO_HEIGHT.

Default: return 0.

redraw

public void redraw(java.io.Writer out)
            throws java.io.IOException

Description copied from class: AbstractComponent

Redraws this component. This method implements the mold mechanism.

1. It first invokes AbstractComponent.getMoldURI() to retrieve the mold to redraw. The mold is either an URI (String) or a ComponentRenderer instance.
2. If URI, it invokes Execution.include(java.io.Writer, java.lang.String, java.util.Map, int) to generate the output.
3. If a ComponentRenderer instance, ComponentRenderer.render(org.zkoss.zk.ui.Component, java.io.Writer) is called to generate the output.

Specified by:

redraw in interface Component

Overrides:

redraw in class AbstractComponent

Throws:

java.io.IOException

newExtraCtrl

protected java.lang.Object newExtraCtrl()

Used by AbstractComponent.getExtraCtrl() to create a client control. It is used only by component developers.

Defaut: creates an instance of HtmlBasedComponent.ExtraCtrl.

Overrides:

newExtraCtrl in class AbstractComponent