component.java

来自「非常接近C/S操作方式的Java Ajax框架－ZK 用ZK框架使你的B/S应」· Java 代码 · 共 616 行 · 第 1/2 页

	/** Sets a variable that both the interpreter and EL can see it.
	 * The variable is defined in the scope of the ID space containing
	 * this component ({@link #getSpaceOwner}).
	 * In other words, all components in the same ID space share the same
	 * set of variables (and functions).
	 *
	 * <p>The other scope to set a variable is {@link Page#setVariable}.
	 * If this component doesn't belong to any ID space, this method
	 * is the same as {@link Page#setVariable}.
	 *
	 * <p>Since variables (and functions) are associated with the ID space,
	 * the child ID space could see the variable in the parent
	 * ID space.
	 *
	 * <h3>When to use setVariable and setAttribute?</h3>
	 *
	 * First, setVariable supports only the ID space. Second, the variable is
	 * easy to reference in zsript and EL (such type the variable name directly),
	 * while attribute needs to specify the scope first, such as spaceScope.
	 * On the other hand, using attributes causes less name popultion.
	 * In general, if you could use attributes, don't use variable.
	 *
	 * @param local whether not to search any of the ancestor ID space defines
	 * the variable. If local is false and an ancesotor has defined a variable
	 * with the same name, the variable in the ancestor is changed directly.
	 * Otherwise, a new variable is created in the ID space containing
	 * this component.
	 */
	public void setVariable(String name, Object val, boolean local);
	/** Returns the value of a variable defined in the interpreter.
	 * The variable is defined in the ID space containing this component
	 *  ({@link #getSpaceOwner}).
	 * In other words, all components in the same ID space share the same
	 * set of variables.
	 *
	 * @param local whether not to search its ancestor.
	 * If false and the current ID space doen't define the variable,
	 * it searches up its ancestor (via {@link #getParent}) to see
	 * any of them has defined the specified variable.
	 */
	public Object getVariable(String name, boolean local);
	/** Unsets a variable from the current ID space.
	 * <p>Unlike {@link #setVariable}, this method removed only
	 * the variable defined in the ID space cotnaining this component.
	 */
	public void unsetVariable(String name);

	/** Returns the parent component, or null if this is the root component.
	 */
	public Component getParent();
	/** Sets the parent component.
	 */
	public void setParent(Component parent);
	/** Returns a live list of children.
	 * You could add or remove a child by manipulating the returned list directly.
	 */
	public List getChildren();
	/** Returns the root of this component.
	 */
	public Component getRoot();

	/** Returns whether this component is visible.
	 * @see Components#isRealVisible
	 */
	public boolean isVisible();
	/** Sets whether this component is visible.
	 * If this component is transaprent ({@link org.zkoss.zk.ui.ext.render.Transparent#isTransparent}), no
	* {@link #smartUpdate} is caleld, so transparent compoents usually have
	* to override this method for detail control.
	 *
	 * @return the previous visibility
	 */
	public boolean setVisible(boolean visible);

	/** Inserts a child before the reference child.
	 *
	 * <p>You could use {@link #setParent} or {@link #appendChild}
	 * instead of this method, unless
	 * you want to control where to put the child.
	 *
	 * @param newChild the new child to be inserted.
	 * @param refChild the child before which you want the new child
	 * being inserted. If null, the new child is append to the end.
	 * @return true if newChild is added successfully or moved;
	 * false if it already has the specified child and the order doesn't
	 * change.
	 */
	public boolean insertBefore(Component newChild, Component refChild);
	/** Appends a child.
	 * A shortcut to insertBefore(child, null).
	 *
	 * @see #insertBefore
	 */
	public boolean appendChild(Component child);

	/** Removes a child. The child is not actually removed.
	 * Rather, it is detached (see {@link #detach}) and it will be removed
	 * if it is no longer used.
	 *
	 * <p>You could use {@link #setParent} with null instead of this method.
	 * @return true if child is removed successfully; false if it doesn't
	 * have the specified child
	 */
	public boolean removeChild(Component child);

	/** Detaches this component such that it won't belong to any page.
	 * If you don't call {@link #setParent} or {@link #setPage} to
	 * attach it to any page, it will be removed automatically
	 * (from the client) after the current event is processed.
	 */
	public void detach();

	/** Called when a child is added.
	 * If a component want to optimize the update, it might do something
	 * different. Otherwise, it does nothing.
	 *
	 * <p>Note: {@link #onChildAdded} is called in the request-processing
	 * phase, while {@link #onDrawNewChild} is called in the redrawing phase.
	 * See {@link #onDrawNewChild} for more details.
	 */
	 public void onChildAdded(Component child);
	/** Called when a child is removed.
	 * If a component want to optimize the update, it might do something
	 * different. Otherwise, it simply does nothing.
	 */
	 public void onChildRemoved(Component child);

	/** 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.
	 * @param asap whether to check only ASAP listener.
	 * See {@link Component#addEventListener} for more description.
	 */
	public boolean isListenerAvailable(String evtnm, boolean asap);
	/** Returns an iterator for iterating listener for the specified event.
	 */
	public Iterator getListenerIterator(String evtnm);

	//-- 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 drawn. It gives the parent
	 * a chance to fine-tune the output.
	 *
	 * <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 class of the specified name.
	 * It's a shortcut to {@link Namespace#getClass} (of {@link #getNamespace}.
	 * Before delegating to the thread class loader, it also looks for
	 * the classes defined in the name space (part of the interpretor).
	 *
	 * <p>Note: a namespace per ID space.
	 *
	 * @exception ClassNotFoundException if not found.
	 */
	public Class getClass(String clsnm) throws ClassNotFoundException;
	/** Returns the namespace to store variables and functions belonging
	 * to the ID space of this component.
	 *
	 * <p>Note: a namespace per ID space.
	 */
	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();
}