component.java

ZK 基础介绍 功能操作 模块 结合数据库操作

	 * <p>It is not a good idea to throw an exception in this method, since
	 * it is in the middle of modifying the component tree.
	 *
	 * @param page the previous page (never null)
	 * @since 3.0.0
	 */
	public void onPageDetached(Page page);

	/** Returns the mold for this component.
	 * <p>Default: "default"
	 *
	 * @see org.zkoss.zk.ui.metainfo.ComponentDefinition
	 */
	public String getMold();
	/** Sets the mold for this component.
	 *
	 * @param mold the mold. If null or empty, "default" is assumed.
	 * @see org.zkoss.zk.ui.metainfo.ComponentDefinition
	 */
	public void setMold(String mold);

	//-- event listener --//
	/** Adds an event listener to specified event for this component.
	 * The second registration is ignored and false is returned.
	 *
	 * <p>You could register listener to all components in the same page
	 * by use of {@link Page#addEventListener}.
	 *
	 * @param evtnm what event to listen (never null)
	 * @return whether the listener is added; false if it was added before
	 * @see Page#addEventListener
	 */
	public boolean addEventListener(String evtnm, EventListener listener);
	/** Removes an event listener.
	 * @return whether the listener is removed; false if it was never added.
	 */
	public boolean removeEventListener(String evtnm, EventListener listener);
	/** Returns whether the event listener is available.
	 *
	 * <p>Unlike {@link org.zkoss.zk.ui.event.Events#isListened},
	 * this method checks only the event listener registered by
	 * {@link #addEventListener}.
	 *
	 * @param asap whether to check only non-deferrable listener,
	 * i.e., not implementing {@link org.zkoss.zk.ui.event.Deferrable},
	 * or {@link org.zkoss.zk.ui.event.Deferrable#isDeferrable} is false.
	 * @see org.zkoss.zk.ui.event.Deferrable
	 * @see org.zkoss.zk.ui.event.Events#isListened
	 * @see Component#addEventListener
	 */
	public boolean isListenerAvailable(String evtnm, boolean asap);
	/** Returns an iterator for iterating listener for the specified event.
	 */
	public Iterator getListenerIterator(String evtnm);

	/** Adds a forward condition to forward the event received
	 * by this component to another component.
	 *
	 * <p>Default: no forward condition at all.
	 *
	 * <p>Once the condition is added, a event called <code>targetEvent</code>
	 * is posted to the <code>target</code> compoennt,
	 * when this component receives the <code>orginalEvent</code> event.
	 *
	 * @param originalEvent the original event that was received
	 * by this component. If null, "onClick" is assumed.
	 * @param target the target component to receive the event.
	 * If null, the space owner {@link #getSpaceOwner} is assumed.
	 * If null and the space owner is the page, the root component is assumed.
	 * @param targetEvent the target event that the target component
	 * will receive.
	 * If null, it is the same as the original event.
	 * @return whether it is added successfully.
	 * It returns false if the conditioin was always added before.
	 * @since 3.0.0
	 * @see #removeForward(String, Component, String)
	 */
	public boolean addForward(
	String originalEvent, Component target, String targetEvent);
	/** Adds a forward condition to forward the event received
	 * by this component to another component, specified with a path.
	 *
	 * <p>Note: the target component is retrieved from the path, each time
	 * the event is received. Thus, you can reference to a component
	 * that is created later.
	 *
	 * @param originalEvent the original event that was received
	 * by this component. If null, "onClick" is assumed.
	 * @param targetPath the target component's path related to this component.
	 * If ".", this component is assumed.
	 * If null, the space owner is assumed.
	 * If null and the space owner is the page, the root component is assumed.
	 * @param targetEvent the target event that the target component
	 * will receive.
	 * If null, it is the same as the original event.
	 * @return whether it is added successfully.
	 * It returns false if the conditioin was always added before.
	 * @see #addForward(String, Component, String)
	 * @see #removeForward(String, String, String)
	 * @since 3.0.0
	 */
	public boolean addForward(
	String originalEvent, String targetPath, String targetEvent);
	/** Removes a forward condition that was added by
	 * {@link #addForward(String, Component, String)}.
	 * If no such forward condition exists, nothing happens but return false.
	 *
	 * @param originalEvent the oringal event that was received
	 * by this component.
	 * It must be the same as the one passed to {@link #addForward(String, Component, String)}.
	 * @param target the target component to receive the event.
	 * It must be the same as the one passed to {@link #addForward(String, Component, String)}.
	 * @param targetEvent the target event that the target component will receive.
	 * It must be the same as the one passed to {@link #addForward(String, Component, String)}.
	 * @return whether the forward is removed successfully.
	 * It returns false if the forward condition is not found
	 * @see #addForward(String, Component, String)
	 * @since 3.0.0
	 */
	public boolean removeForward(
	String originalEvent, Component target, String targetEvent);
	/** Removes a forward condition that was added by
	 * {@link #addForward(String, String, String)}.
	 * If no such forward condition exists, nothing happens but return false.
	 *
	 * @param originalEvent the oringal event that was received
	 * by this component.
	 * It must be the same as the one passed to {@link #addForward(String, Component, String)}.
	 * @param targetPath the target component's path related to this component.
	 * If ".", this component is assumed.
	 * If null, the space owner is assumed.
	 * If null and the space owner is the page, the root component is assumed.
	 * @param targetEvent the target event that the target component will receive.
	 * It must be the same as the one passed to {@link #addForward(String, Component, String)}.
	 * @return whether the forward is removed successfully.
	 * It returns false if the forward condition is not found
	 * @see #addForward(String, String, String)
	 * @since 3.0.0
	 */
	public boolean removeForward(
	String originalEvent, String targetPath, String targetEvent);

	//-- drawing --//
	/** Invalidates this component by setting the dirty flag
	 * such that it will be redraw the whole content later.
	 *
	 * <p>It can be called only in the request-processing and event-processing
	 * phases; excluding the redrawing phase.
	 *
	 * <p>There are two ways to draw a component, one is to invoke
	 * {@link #invalidate()}, and the other is {@link #smartUpdate}.
	 * While {@link #invalidate()} causes the whole content to redraw,
	 * {@link #smartUpdate} let component developer control which part
	 * to redraw.
	 *
	 * <p>Once this method is called, all invocations to {@link #smartUpdate}
	 * will then be ignored, and {@link Component#redraw} will be invoked later.
	 */
	public void invalidate();
	/** Smart-updates a property with the specified value.
	 * Called by component developers to do precise-update.
	 *
	 * <p>The second invocation with the same property will replace the previous
	 * call. In other words, the same property will be set only once in
	 * each execution.
	 *
	 * <p>This method has no effect if {@link #invalidate()} is ever invoked
	 * (during this execution).
	 *
	 * <p>It can be called only in the request-processing and event-processing
	 * phases; excluding the redrawing phase.
	 *
	 * <p>There are two ways to draw a component, one is to invoke
	 * {@link #invalidate()}, and the other is {@link #smartUpdate}.
	 * While {@link #invalidate()} causes the whole content to redraw,
	 * {@link #smartUpdate} let component developer control which part
	 * to redraw.
	 *
	 * @param value the new value. If null, it means removing the property.
	 */
	public void smartUpdate(String attr, String value);
	/** Causes a response (aka., a command) to be sent to the client.
	 *
	 * <p>If {@link AuResponse#getDepends} is not null, the response
	 * depends on the existence of the returned componet.
	 * In other words, the response is removed if the component is removed.
	 * If it is null, the response is component-independent and it is
	 * always sent to the client.
	 *
	 * <p>Unlike {@link #smartUpdate}, responses are sent to client if
	 * it is component independent or it is not removed.
	 * In other words, it is sent even if {@link #invalidate()} was called.
	 * Typical examples include setting the focus, selecting the text and so on.
	 *
	 * <p>It can be called only in the request-processing and event-processing
	 * phases; excluding the redrawing phase.
	 *
	 * @param key could be anything.
	 * The second invocation of this method
	 * in the same execution with the same key will override the previous one.
	 * However, if key is null, it won't override any other. All responses
	 * with key == null will be sent.
	 */
	public void response(String key, AuResponse response);

	/** AuRequest this component to render (aka., redraw) itself
	 * and its children.
	 *
	 * <p>It is called in the redrawing phase by the kernel, so it is too late
	 * to call {@link #invalidate()} or {@link #smartUpdate} in this method.
	 */
	public void redraw(Writer out) throws IOException;

	/** Called when a new-created child is about to render.
	 * It gives the parent a chance to fine-tune the output.
	 * Note: it won't be called if the parent is rendered, too.
	 * In other words, it is called only if the child is attached dynamically.
	 *
	 * <p>It is called in the redrawing phase by the kernel, so it is too late
	 * to call {@link #invalidate()} or {@link #smartUpdate} in this method.
	 *
	 * <p>Note: {@link #onChildAdded} is called in the request-processing
	 * phase, while {@link #onDrawNewChild} is called in the redrawing phase.
	 * Component developer might do one of the follows:
	 * <ul>
	 * <li>Nothing, if new child can be inserted directly.</li>
	 * <li>Overwrite {@link #onDrawNewChild} to add special tags, if
	 * new child needs to be added an exterior with some tags before
	 * insertion.<br>
	 * Morever, if you shall add id="${child.uuid}!chdextr" to the added
	 * exterior.</li>
	 * <li>Redraw the parent, if it is too complicated.
	 * How: overwrite {@link #onChildAdded} and calls {@link #invalidate()}</li>
	 * </ul>
	 *
	 * @param child the child being rendered
	 * @param out the rendered result of the child.
	 */
	public void onDrawNewChild(Component child, StringBuffer out)
	throws IOException;

	/** Returns whether this component allows to have any child.
	 */
	public boolean isChildable();

	/** Returns the namespace to store variables and functions belonging
	 * to the ID space of this component.
	 *
	 * <p>Exactly one namespace is allocated for each ID space.
	 * For example, if the space owner of this component is the page, then
	 * the returned namespace is the same as {@link Page#getNamespace}.
	 * Otherwise, it is the same as the namspace returned by the component
	 * owning this ID space.
	 *
	 * <p>Namspace is another part of an ID space. It holds only variables
	 * defined thru {@link #setVariable} (and {@link Namespace#setVariable}.
	 *
	 * <p>Note: The namespace doesn't include any variable defined by
	 * executing zscripts. To retrieve them, use {@link Page#getZScriptVariable}.
	 *
	 * @see #getSpaceOwner
	 */
	public Namespace getNamespace();

	/** Initializes the properties (aka. members) and custom-attributes
	 * based on what are defined in the component definition.
	 *
	 * <p>This method is invoked automatically if a component is created
	 * by evaluating a ZUML page, i.e., if it is specified as an elemnt
	 * of a ZUML page.
	 *
	 * <p>On the other hand, if it is created manually (by program),
	 * developer might choose to invoke this method or not,
	 * depending whether he wants to
	 * initializes the component with the properties and custom-attributes
	 * defined in the ZUML page ({@link org.zkoss.zk.ui.metainfo.PageDefinition})
	 * and the language definition ({@link org.zkoss.zk.ui.metainfo.LanguageDefinition}).
	 */
	public void applyProperties();

	/** Clones the component.
	 * All of its children is cloned.
	 * Notice that the cloned component doesn't belong to any page, nor
	 * desktop. It doesn't have parent, either.
	 */
	public Object clone();
}