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

Direct Known Subclasses:

HtmlMacroComponent

public abstract class HtmlBasedComponent
extends AbstractComponent

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

Field Summary

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

boolean	addEventListener(java.lang.String evtnm, EventListener listener) Adds an event listener to specified event for this component.
protected java.lang.StringBuffer	appendAsapAttr(java.lang.StringBuffer sb, java.lang.String evtnm) Appends the HTML attribute for the specified event name, say, onChange.
void	focus() Sets focus to this element.
java.lang.String	getDraggable() Returns the identifier of a draggable type of objects, or "false" if not draggable (never null or empty).
java.lang.String	getDroppable() Returns the identifier of a droppable type of objects, or "false" if not droppable (never null or 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	getOuterAttrs() Returns the exterior attributes for generating the enclosing HTML tag; never return null.
protected java.lang.String	getRealStyle() Returns the real style after appending width, height and others to setStyle(java.lang.String) (never null).
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.
int	getZIndex() Returns the Z index.
protected boolean	isAsapRequired(java.lang.String evtnm) Returns whether to send back the request of the specified event immediately -- i.e., non-deferrable.
protected java.lang.Object	newExtraCtrl() Used by AbstractComponent.getExtraCtrl() to create a client control.
boolean	removeEventListener(java.lang.String evtnm, EventListener listener) Removes an event listener.
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	setHeight(java.lang.String height) Sets the height.
void	setLeft(java.lang.String left) Sets the left position.
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	setZIndex(int zIndex) Sets the Z index.

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

addAnnotation, addAnnotation, addEventHandler, addSharedAnnotationMap, addSharedEventHandlerMap, appendChild, applyProperties, clone, containsVariable, detach, equals, getAnnotatedProperties, getAnnotatedPropertiesBy, getAnnotation, getAnnotation, getAnnotations, getAnnotations, getAttribute, getAttribute, getAttributes, getAttributes, getChildren, getDefinition, getDesktop, getEventHandler, getExtraCtrl, getFellow, getFellowIfAny, getId, getListenerIterator, getMold, getMoldURI, getNamespace, getPage, getParent, getPropagatee, getRoot, getSpaceOwner, getUuid, getVariable, insertBefore, invalidate, isChildable, isListenerAvailable, isVisible, onChildAdded, onChildRemoved, onDrawNewChild, onWrongValue, redraw, removeAttribute, removeAttribute, removeChild, response, sessionDidActivate, sessionWillPassivate, setAttribute, setAttribute, setComponentDefinition, setId, setMold, setPage, setParent, setVariable, setVisible, smartUpdate, smartUpdate, smartUpdate, toString, unsetVariable

Methods inherited from class java.lang.Object

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

Field Detail

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.

setLeft

public void setLeft(java.lang.String left)

Sets the left position.

getTop

public java.lang.String getTop()

Returns the top position.

setTop

public void setTop(java.lang.String top)

Sets the top position.

getZIndex

public int getZIndex()

Returns the Z index.

Default: -1 (means system default;

setZIndex

public void setZIndex(int zIndex)

Sets the Z index.

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.

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.

getSclass

public java.lang.String getSclass()

Returns the CSS class. Due to Java's limitation, we cannot use the name called getClas.

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

setSclass

public void setSclass(java.lang.String sclass)

Sets the CSS class.

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.

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", 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 or 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.

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

focus

public void focus()

Sets focus to this element. For element that does not accept focus, this method has no effect.

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

getRealStyle

protected java.lang.String getRealStyle()

Returns the real style after appending 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.

isAsapRequired

protected boolean isAsapRequired(java.lang.String evtnm)

Returns whether to send back the request of the specified event immediately -- i.e., non-deferrable. Returns true if you want the component (on the server) to process the event immediately.

Default: return true if any non-deferable event listener of the specified event is found. In other words, it returns Events.isListened(org.zkoss.zk.ui.Component, java.lang.String, boolean) with asap = true.

appendAsapAttr

protected java.lang.StringBuffer appendAsapAttr(java.lang.StringBuffer sb,
                                                java.lang.String evtnm)

Appends the HTML attribute for the specified event name, say, onChange. It is called by derived's getOuterAttrs().

Parameters:

sb - the string buffer to hold the HTML attribute. If null and isAsapRequired(java.lang.String) is true, a string buffer is created and returned.

Returns:

the string buffer. If sb is null and isAsapRequired(java.lang.String) returns false, null is returned. If the caller passed non-null sb, the returned value must be the same as sb (so it usually ignores the returned value).

addEventListener

public boolean addEventListener(java.lang.String evtnm,
                                EventListener listener)

Description copied from interface: Component

Adds an event listener to specified event for this component. The second registration is ignored and false is returned.

You could register listener to all components in the same page by use of Page.addEventListener(java.lang.String, org.zkoss.zk.ui.event.EventListener).

Specified by:

addEventListener in interface Component

Overrides:

addEventListener in class AbstractComponent

Parameters:

evtnm - what event to listen (never null)

Returns:

whether the listener is added; false if it was added before

See Also:

Page.addEventListener(java.lang.String, org.zkoss.zk.ui.event.EventListener)

removeEventListener

public boolean removeEventListener(java.lang.String evtnm,
                                   EventListener listener)

Description copied from interface: Component

Removes an event listener.

Specified by:

removeEventListener in interface Component

Overrides:

removeEventListener in class AbstractComponent

Returns:

whether the listener is removed; false if it was never added.

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