Package org.zkoss.zk.ui

Class HtmlShadowElement

java.lang.Object

org.zkoss.zk.ui.AbstractComponent

org.zkoss.zk.ui.HtmlShadowElement

All Implemented Interfaces:

Serializable, Cloneable, Component, AfterCompose, Scope, ShadowElement, ShadowElementCtrl, ComponentCtrl

public abstract class HtmlShadowElement
extends AbstractComponent
implements ShadowElement, ShadowElementCtrl

A skeleton of shadow element that represents as a shadow tree.

Since:

8.0.0

Author:

jumperchen

See Also:

• Serialized Form

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static enum	HtmlShadowElement.Direction	A help class for an insertion direction.

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

AbstractComponent.Children, AbstractComponent.ForwardInfo, AbstractComponent.TargetInfo

Field Summary

Fields

Modifier and Type	Field	Description
protected boolean	_afterComposed
protected Boolean	_dynamicValue
protected static final String	BIND_ANNO
protected static final String	BINDER
static String	FOREACH_IN_RENDER	internal used only
protected static final String	INIT_ANNO
protected static final String	LOAD_ANNO
protected static String	ON_REBUILD_SHADOW_TREE_LATER
protected static final String	REFERENCE_ANNO
protected static final String	SAVE_ANNO
static String	SKIP_DISTRIBUTED_CHILDREN_PROPERTY_CHANGE	internal used only

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

AFTER_CHILD_ADDED, AFTER_CHILD_REMOVED, AFTER_CLONED, AFTER_PAGE_ATTACHED, AFTER_PAGE_DETACHED, AFTER_PARENT_CHANGED, CE_BUSY_IGNORE, CE_DUPLICATE_IGNORE, CE_IMPORTANT, CE_NON_DEFERRABLE, CE_REPEAT_IGNORE

Constructor Summary

Constructors

Constructor	Description
HtmlShadowElement()

Method Summary

Modifier and Type	Method	Description
void	afterCompose()	Creates the distributed children after apply dynamic properties
void	afterHostChildAdded(Component child, int indexOfChild)	Called when a child is added to the host.
void	afterHostChildRemoved(Component child)	Called when a child is removed to the host.
protected static <T extends HtmlShadowElement> T	asShadow(Object o)
void	beforeChildAdded(Component child, Component refChild)	Default: does nothing.
void	beforeHostChildAdded(Component child, Component insertBefore, int indexOfInsertBefore)	Called before the host adding a child.
void	beforeHostChildRemoved(Component child, int indexOfChild)	Called before the host removing a child.
void	beforeHostParentChanged(Component parent)	Called before the host changing the parent.
void	beforeParentChanged(Component parent)	Default: If parent is null, execute the @Destroy method if any.
void	clearChildren()
Object	clone()	Clones the component.
protected abstract void	compose(Component host)	Composes the shadow element.
void	destroyIndexCacheMap(Component host)	Internal use
void	detach()	Removes the relation points between shadow host and this shadow element.
<T extends Component> List<T>	getDistributedChildren()	Returns a list of distributed components of the shadow tree, including its descendant.
Component	getFirstInsertion()	Returns the first component of its insertion range.
static int	getIndex(ShadowElement owner, Component insertion, Map<Component,Integer> cacheMap)
Map<Component,Integer>	getIndexCacheMap(Component host)	Internal use
Component	getLastInsertion()	Returns the last component of its insertion range.
Component	getNextInsertion()	Returns the next insertion point, it may be a component, a shadow element, or null.
Component	getNextInsertionComponentIfAny()	Returns the next component before this shadow, if any.
Component	getPreviousInsertion()	Returns the previous insertion point, it may be a component, a shadow element, or null.
Component	getPreviousInsertionComponentIfAny()	Returns the first component before this shadow, if any.
Component	getShadowHost()	Returns the owner component that hosts this shadow element.
Component	getShadowHostIfAny()	Return the shadow host from it or its ancestor, if any.
protected void	initClone(AbstractComponent cloneHost)
Map<Component,Integer>	initIndexCacheMap(Component host)	Internal use
static HtmlShadowElement.Direction	inRange(HtmlShadowElement se, Component target)	Returns the direction of the target component according to the given shadow element.
void	invalidate()	Invalidates this component by setting the dirty flag such that it will be redraw the whole content of this component and its dependencies later.
boolean	isDynamicValue()	Returns whether the shadow element contains a dynamic value, it means the shadow element cannot be destroyed after evaluated.
protected boolean	isDynamicValue(String propName)	Returns whether the property name contains with a dynamic value.
protected abstract boolean	isEffective()	Returns whether the shadow element is effective
protected void	mergeSubTree()	Merge the all sub-tree into the parent's insertions, unlike AbstractComponent.appendChild(Component)
boolean	mergeToHost(Component host)	Merge the host into the current shadow, unlike setShadowHost(Component, Component)
void	onChildAdded(Component child)	Default: handles special event listeners.
protected void	onHostAttached(Component host)
void	onHostChildAdded(Component child)	Default: does nothing.
void	onHostChildRemoved(Component child)	Default: does nothing.
protected void	onHostDetached(Component host)
protected void	rebuildSubShadowTree()	Rebuilds the shadow tree if the shadow element contains a dynamic value, it should be alive, otherwise, it will be detached.
void	recreate()	Detaches all child components and then recreate them by use of compose(org.zkoss.zk.ui.Component).
protected void	removeFromParent()
Object	resolveVariable(Component child, String name, boolean recurse)	Returns the variable associated with this base component or null if not found.
void	setDynamicValue(boolean dynamicValue)	Sets whether the shadow element contains a dynamic value, if true means the shadow element cannot be destroyed after evaluated, if false it will detect its attribute automatically.
void	setParent(Component parent)	Sets the parent component.
protected static void	setPrevInsertion(Component target, Component prevInsertion)
void	setShadowHost(Component host, Component insertBefore)	Sets the owner component that hosts this shadow element.
protected void	shrinkRange(Component firstChild, Component lastChild)
protected void	stretchRange(Component firstChild, Component lastChild)
String	toString()
void	updateFirstInsertion(Component newFirstInsertion)	Updates the given first insertion to this shadow element.
void	updateLastInsertion(Component newLastInsertion)	Updates the given last insertion to this shadow element.
void	updateNextInsertion(Component newNextInsertion)	Updates the given next insertion to this shadow element.
void	updatePreviousInsertion(Component newPreviousInsertion)	Updates the given previous insertion to this shadow element.
protected void	updateSubBindingAnnotationCount(int diff)

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

addAnnotation, addCallback, addClientEvent, addEventHandler, addEventListener, addEventListener, addForward, addForward, addForward, addForward, addMoved, addRedrawCallback, addScopeListener, addShadowRoot, addShadowRootBefore, addSharedEventHandlerMap, appendChild, applyProperties, beforeChildRemoved, didActivate, didActivate, didDeserialize, didDeserialize, disableBindingAnnotation, disableClientUpdate, disableHostChanged, enableBindingAnnotation, enableHostChanged, getAnnotatedProperties, getAnnotatedPropertiesBy, getAnnotation, getAnnotations, getAnnotations, getAttribute, getAttribute, getAttribute, getAttributeOrFellow, getAttributes, getAttributes, getAuService, getAutag, getCallback, getChildren, getClientAttribute, getClientDataAttribute, getClientEvents, getDefaultMold, getDefinition, getDesktop, getEventHandler, getEventHandlerNames, getEventListenerMap, getEventListeners, getExtraCtrl, getFellow, getFellow, getFellowIfAny, getFellowIfAny, getFellows, getFirstChild, getForwards, getId, getLastChild, getMold, getNextSibling, getPage, getParent, getPreviousSibling, getPropertyAccess, getRedrawCallback, getRoot, getShadowFellowIfAny, getShadowRoots, getShadowVariable, getShadowVariable, getShadowVariable0, getSpaceOwner, getSpecialRendererOutput, getStubonly, getStubonlyDescendants, getSubBindingAnnotationCount, getTemplate, getTemplateNames, getUuid, getWidgetAttributeNames, getWidgetClass, getWidgetListener, getWidgetListenerNames, getWidgetOverride, getWidgetOverrideNames, hasAttribute, hasAttribute, hasAttribute, hasAttributeOrFellow, hasBindingAnnotation, hasFellow, hasFellow, hasSubBindingAnnotation, insertBefore, isChildable, isDisabledHostChanged, isInitialized, isInvalidated, isListenerAvailable, isVisible, onChildRemoved, onPageAttached, onPageDetached, onParentChanged, onWrongValue, query, queryAll, redraw, redrawChildren, removeAttribute, removeAttribute, removeAttribute, removeCallback, removeChild, removeEventListener, removeForward, removeForward, removeRedrawCallback, removeScopeListener, removeShadowRoot, render, render, render, renderProperties, renderPropertiesOnly, replace, response, response, response, service, service, sessionDidActivate, sessionWillPassivate, setAttribute, setAttribute, setAttribute, setAuService, setAutag, setClientAttribute, setClientDataAttribute, setDefinition, setDefinition, setId, setMold, setPage, setPageBefore, setStubonly, setStubonly, setStubonlyDescendants, setSubBindingAnnotationCount, setTemplate, setVisible, setVisibleDirectly, setWidgetClass, setWidgetListener, setWidgetOverride, smartUpdate, smartUpdate, smartUpdate, smartUpdate, smartUpdate, smartUpdate, smartUpdate, smartUpdate, smartUpdate, smartUpdateWidgetListener, smartUpdateWidgetOverride, updateByClient, willPassivate, willPassivate, willSerialize, willSerialize

Methods inherited from class java.lang.Object

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

Field Details

_afterComposed

protected boolean _afterComposed

ON_REBUILD_SHADOW_TREE_LATER

protected static String ON_REBUILD_SHADOW_TREE_LATER

FOREACH_IN_RENDER

public static String FOREACH_IN_RENDER

internal used only

SKIP_DISTRIBUTED_CHILDREN_PROPERTY_CHANGE

public static String SKIP_DISTRIBUTED_CHILDREN_PROPERTY_CHANGE

internal used only

INIT_ANNO

protected static final String INIT_ANNO

See Also:

• Constant Field Values

BIND_ANNO

protected static final String BIND_ANNO

See Also:

• Constant Field Values

LOAD_ANNO

protected static final String LOAD_ANNO

See Also:

• Constant Field Values

SAVE_ANNO

protected static final String SAVE_ANNO

See Also:

• Constant Field Values

REFERENCE_ANNO

protected static final String REFERENCE_ANNO

See Also:

• Constant Field Values

BINDER

protected static final String BINDER

See Also:

• Constant Field Values

_dynamicValue

protected Boolean _dynamicValue

Constructor Details

HtmlShadowElement

public HtmlShadowElement()

Method Details

resolveVariable

public Object resolveVariable(Component child,
 String name,
 boolean recurse)

Description copied from interface: ShadowElementCtrl

Returns the variable associated with this base component or null if not found.

Notice that it doesn't check any variable defined in VariableResolver (of Page.addVariableResolver(org.zkoss.xel.VariableResolver)).

Specified by:

resolveVariable in interface ShadowElementCtrl

Parameters:

child - the child component of the shadow host

recurse - whether to look up the parent shadow for the existence of the variable.
If recurse is true, it will look up all parents until found.

getNextInsertionComponentIfAny

public Component getNextInsertionComponentIfAny()

Returns the next component before this shadow, if any. (it will invoke recursively from its parent.)

getPreviousInsertionComponentIfAny

public Component getPreviousInsertionComponentIfAny()

Returns the first component before this shadow, if any. (it will invoke recursively from its parent.)

onHostAttached

protected void onHostAttached(Component host)

onHostDetached

protected void onHostDetached(Component host)

getNextInsertion

public Component getNextInsertion()

Returns the next insertion point, it may be a component, a shadow element, or null.

Specified by:

getNextInsertion in interface ShadowElement

Specified by:

getNextInsertion in interface ShadowElementCtrl

getPreviousInsertion

public Component getPreviousInsertion()

Returns the previous insertion point, it may be a component, a shadow element, or null.

Specified by:

getPreviousInsertion in interface ShadowElement

Specified by:

getPreviousInsertion in interface ShadowElementCtrl

updatePreviousInsertion

public void updatePreviousInsertion(Component newPreviousInsertion)

Updates the given previous insertion to this shadow element. (Internal use only)

Since:

10.0.0

updateFirstInsertion

public void updateFirstInsertion(Component newFirstInsertion)

Updates the given first insertion to this shadow element. (Internal use only)

Since:

10.0.0

updateNextInsertion

public void updateNextInsertion(Component newNextInsertion)

Updates the given next insertion to this shadow element. (Internal use only)

Since:

10.0.0

updateLastInsertion

public void updateLastInsertion(Component newLastInsertion)

Updates the given last insertion to this shadow element. (Internal use only)

Since:

10.0.0

getFirstInsertion

public Component getFirstInsertion()

Returns the first component of its insertion range.

Specified by:

getFirstInsertion in interface ShadowElement

Specified by:

getFirstInsertion in interface ShadowElementCtrl

getLastInsertion

public Component getLastInsertion()

Returns the last component of its insertion range.

Specified by:

getLastInsertion in interface ShadowElement

Specified by:

getLastInsertion in interface ShadowElementCtrl

setShadowHost

public void setShadowHost(Component host,
 Component insertBefore)

Description copied from interface: ShadowElementCtrl

Sets the owner component that hosts this shadow element.

Specified by:

setShadowHost in interface ShadowElementCtrl

Parameters:

host - the host of the shadow element

insertBefore - a component or a shadow element to indicate where the shadow's insertion point is added.

detach

public void detach()

Removes the relation points between shadow host and this shadow element.

Specified by:

detach in interface Component

Specified by:

detach in interface ShadowElement

Overrides:

detach in class AbstractComponent

setParent

public void setParent(Component parent)

Description copied from interface: Component

Sets the parent component.

Note: Component.setParent(org.zkoss.zk.ui.Component) always calls back Component.insertBefore(org.zkoss.zk.ui.Component, org.zkoss.zk.ui.Component) and/or Component.removeChild(org.zkoss.zk.ui.Component), while Component.insertBefore(org.zkoss.zk.ui.Component, org.zkoss.zk.ui.Component) and Component.removeChild(org.zkoss.zk.ui.Component) always calls back Component.setParent(org.zkoss.zk.ui.Component), if the parent is changed. Thus, you don't need to override both Component.insertBefore(org.zkoss.zk.ui.Component, org.zkoss.zk.ui.Component) and Component.setParent(org.zkoss.zk.ui.Component), if you want to customize the behavior.

Specified by:

setParent in interface Component

Overrides:

setParent in class AbstractComponent

beforeParentChanged

public void beforeParentChanged(Component parent)

Description copied from class: AbstractComponent

Default: If parent is null, execute the @Destroy method if any.

Specified by:

beforeParentChanged in interface ComponentCtrl

Overrides:

beforeParentChanged in class AbstractComponent

Parameters:

parent - the new parent. If null, it means detachment.

See Also:

• ComponentCtrl.beforeParentChanged(org.zkoss.zk.ui.Component)

beforeChildAdded

public void beforeChildAdded(Component child,
 Component refChild)

Description copied from class: AbstractComponent

Default: does nothing.

Specified by:

beforeChildAdded in interface ComponentCtrl

Overrides:

beforeChildAdded in class AbstractComponent

Parameters:

child - the child to be added (never null).

refChild - another child component that the new child will be inserted before it. If null, the new child will be the last child.

See Also:

• ComponentCtrl.beforeChildAdded(org.zkoss.zk.ui.Component, org.zkoss.zk.ui.Component)

onChildAdded

public void onChildAdded(Component child)

Description copied from class: AbstractComponent

Default: handles special event listeners.

Specified by:

onChildAdded in interface ComponentCtrl

Overrides:

onChildAdded in class AbstractComponent

See Also:

• ComponentCtrl.onChildAdded(org.zkoss.zk.ui.Component)

invalidate

public void invalidate()

Description copied from interface: Component

Invalidates this component by setting the dirty flag such that it will be redraw the whole content of this component and its dependencies later. And, the widget associated with this component and all its descendant at the client will be deleted and recreated, too.

If the application is totally controlled by the server side (i.e., you don't write client codes), you rarely need to access this method.

It can be called only in the request-processing and event-processing phases. However, it is NOT allowed in the rendering phase.

Specified by:

invalidate in interface Component

Overrides:

invalidate in class AbstractComponent

stretchRange

protected void stretchRange(Component firstChild,
 Component lastChild)

shrinkRange

protected void shrinkRange(Component firstChild,
 Component lastChild)

clone

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

initClone

protected void initClone(AbstractComponent cloneHost)

getShadowHost

public Component getShadowHost()

Description copied from interface: ShadowElement

Returns the owner component that hosts this shadow element.

Specified by:

getShadowHost in interface ShadowElement

afterCompose

public void afterCompose()

Creates the distributed children after apply dynamic properties

If a shadow element is created by ZK loader, this method is invoked automatically. Developers rarely need to invoke this method.

Default: it invokes compose(org.zkoss.zk.ui.Component) to compose the shadow element.

The method will invoke the following methods in order.

1. Check if isEffective() to be true.
2. If true, invokes compose(org.zkoss.zk.ui.Component) method to create the distributed children, otherwise, nothing happened.

Instead of overriding this method, it is suggested to override compose(org.zkoss.zk.ui.Component), since all other methods depend on compose(org.zkoss.zk.ui.Component) (rather than afterCompose()).

Specified by:

afterCompose in interface AfterCompose

setPrevInsertion

protected static void setPrevInsertion(Component target,
 Component prevInsertion)

mergeSubTree

protected void mergeSubTree()

Merge the all sub-tree into the parent's insertions, unlike AbstractComponent.appendChild(Component)

mergeToHost

public boolean mergeToHost(Component host)

Merge the host into the current shadow, unlike setShadowHost(Component, Component)

Parameters:

host -

rebuildSubShadowTree

protected void rebuildSubShadowTree()

Rebuilds the shadow tree if the shadow element contains a dynamic value, it should be alive, otherwise, it will be detached.

Throws:

ConcurrentModificationException - if caller use the same collection, it may throw this exception when merging sub-tree.

isEffective

protected abstract boolean isEffective()

Returns whether the shadow element is effective

compose

protected abstract void compose(Component host)

Composes the shadow element. It is called by afterCompose() if the shadow host is not null. Otherwise, it will skip this method call.

The second invocation is ignored. If you want to recreate child components, use recreate() instead.

Parameters:

host - the shadow host component, never null.

beforeHostChildRemoved

public void beforeHostChildRemoved(Component child,
 int indexOfChild)

Description copied from interface: ShadowElementCtrl

Called before the host removing a child.

Specified by:

beforeHostChildRemoved in interface ShadowElementCtrl

Parameters:

child - the child to be removed (never null)

indexOfChild - the index of the removed child

onHostChildRemoved

public void onHostChildRemoved(Component child)

Default: does nothing.

Specified by:

onHostChildRemoved in interface ShadowElementCtrl

See Also:

• ComponentCtrl.onChildAdded(org.zkoss.zk.ui.Component)

onHostChildAdded

public void onHostChildAdded(Component child)

Default: does nothing.

Specified by:

onHostChildAdded in interface ShadowElementCtrl

See Also:

• ComponentCtrl.onChildAdded(org.zkoss.zk.ui.Component)

beforeHostParentChanged

public void beforeHostParentChanged(Component parent)

Description copied from interface: ShadowElementCtrl

Called before the host changing the parent.

Specified by:

beforeHostParentChanged in interface ShadowElementCtrl

Parameters:

parent - the new parent. If null, it means detachment.

beforeHostChildAdded

public void beforeHostChildAdded(Component child,
 Component insertBefore,
 int indexOfInsertBefore)

Description copied from interface: ShadowElementCtrl

Called before the host adding a child.

Specified by:

beforeHostChildAdded in interface ShadowElementCtrl

Parameters:

child - the child to be added (never null).

insertBefore - another child component that the new child will be inserted before it. If null, the new child will be the last child.

indexOfInsertBefore - the index of the insertBefore, if any. Otherwise -1 is assumed.

asShadow

protected static <T extends HtmlShadowElement> T asShadow(Object o)

getIndex

public static int getIndex(ShadowElement owner,
 Component insertion,
 Map<Component,Integer> cacheMap)

inRange

public static HtmlShadowElement.Direction inRange(HtmlShadowElement se,
 Component target)

Returns the direction of the target component according to the given shadow element.

Parameters:

se - the shadow element

target - the target to check.

afterHostChildAdded

public void afterHostChildAdded(Component child,
 int indexOfChild)

Description copied from interface: ShadowElementCtrl

Called when a child is added to the host.

Specified by:

afterHostChildAdded in interface ShadowElementCtrl

Parameters:

child - the child has been added (never null).

indexOfChild - the index of the added child.

afterHostChildRemoved

public void afterHostChildRemoved(Component child)

Description copied from interface: ShadowElementCtrl

Called when a child is removed to the host.

Specified by:

afterHostChildRemoved in interface ShadowElementCtrl

Parameters:

child - the child has been added (never null).

recreate

public void recreate()

Detaches all child components and then recreate them by use of compose(org.zkoss.zk.ui.Component).

Specified by:

recreate in interface ShadowElement

clearChildren

public void clearChildren()

removeFromParent

protected void removeFromParent()

getShadowHostIfAny

public Component getShadowHostIfAny()

Description copied from interface: ShadowElementCtrl

Return the shadow host from it or its ancestor, if any.

Specified by:

getShadowHostIfAny in interface ShadowElementCtrl

Returns:

null or a host component

getDistributedChildren

public <T extends Component> List<T> getDistributedChildren()

Description copied from interface: ShadowElement

Returns a list of distributed components of the shadow tree, including its descendant.

It's better to manipulate with the component children from the host component.

Specified by:

getDistributedChildren in interface ShadowElement

Returns:

a list of distributed components (removeable only)

isDynamicValue

protected boolean isDynamicValue(String propName)

Returns whether the property name contains with a dynamic value.

isDynamicValue

public boolean isDynamicValue()

Description copied from interface: ShadowElementCtrl

Returns whether the shadow element contains a dynamic value, it means the shadow element cannot be destroyed after evaluated.

Specified by:

isDynamicValue in interface ShadowElementCtrl

setDynamicValue

public void setDynamicValue(boolean dynamicValue)

Sets whether the shadow element contains a dynamic value, if true means the shadow element cannot be destroyed after evaluated, if false it will detect its attribute automatically.

Default: false (auto detection)

Specified by:

setDynamicValue in interface ShadowElementCtrl

Since:

8.0.1

toString

public String toString()

Overrides:

toString in class AbstractComponent

updateSubBindingAnnotationCount

protected void updateSubBindingAnnotationCount(int diff)

Overrides:

updateSubBindingAnnotationCount in class AbstractComponent

initIndexCacheMap

public Map<Component,Integer> initIndexCacheMap(Component host)

Internal use

Overrides:

initIndexCacheMap in class AbstractComponent

Since:

10.0.0

getIndexCacheMap

public Map<Component,Integer> getIndexCacheMap(Component host)

Internal use

Overrides:

getIndexCacheMap in class AbstractComponent

Since:

10.0.0

destroyIndexCacheMap

public void destroyIndexCacheMap(Component host)

Internal use

Overrides:

destroyIndexCacheMap in class AbstractComponent

Since:

10.0.0