htmlbasedcomponent.java

非常接近C/S操作方式的Java Ajax框架－ZK 用ZK框架使你的B/S应用程序更漂亮更易操作。 官网：www.zkoss.org

	 * @param 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).
	 */
	public void setDroppable(String droppable) {
		if (droppable != null
		&& (droppable.length() == 0 || "false".equals(droppable)))
			droppable = null;

		if (!Objects.equals(_droppable, droppable)) {
			_droppable = droppable;
			smartUpdate("z.drop", _droppable);
		}
	}
	/** Returns the identifier of a droppable type of objects, or "false"
	 * if not droppable (never null or empty).
	 */
	public final String getDroppable() {
		return _droppable != null ? _droppable: "false";
	}

	/** Sets focus to this element. For element that does not accept focus,
	 * this method has no effect.
	 */
	public void focus() {
		response("focus", new AuFocus(this));
	}

	//-- component developer only --//
	/** Returns the exterior attributes for generating the enclosing
	 * HTML tag; never return null.
	 *
	 * <p>Used only by component developers.
	 *
	 * <p>Default: Generates the tooltip text, style, sclass, draggable
	 * and droppable attribute if necessary.
	 * In other words, the corresponding attribute is generated if
	 * {@link #getTooltiptext}, {@link #getRealStyle},
	 * {@link #getSclass}, {@link #getDraggable}, {@link #getDroppable}
	 * are defined.
	 *
	 * <p>You have to call both {@link #getOuterAttrs} and
	 * {@link #getInnerAttrs} to generate complete attributes.
	 *
	 * <p>For simple components that all attributes are put on
	 * the outest HTML element, all you need is as follows.
	 *
	 * <pre><code>&lt;xx id="${self.uuid}"${self.outerAttrs}${self.innerAttrs}&gt;</code></pre>
	 *
	 * <p>If you want to put attributes in a nested HTML element, you
	 * shall use the following pattern. Notice: if {@link #getInnerAttrs}
	 * in a different tag, the tag must be named with "${self.uuid}!real".
	 *
	 * <pre><code>&lt;xx id="${self.uuid}"${self.outerAttrs}&gt;
	 * &lt;yy id="${self.uuid}!real"${self.innerAttrs}&gt;...
	 *</code></pre>
	 *
	 * <p>Note: This class handles ASAP event listeners (i.e., event listeners
	 * whose {@link EventListener#isAsap} return true) automatically.
	 * However, you have to invoke {@link #appendAsapAttr} for each event
	 * the component handles in {@link #getOuterAttrs} as follows.
	 *<pre><code>
	 *	appendAsapAttr(sb, Events.ON_OPEN);
	 *  appendAsapAttr(sb, Events.ON_CHANGE);
	 *</code></pre>
	 *
	 * <p>Theorectically, you could put any attributes in either
	 * {@link #getInnerAttrs} or {@link #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).
	 */
	public String getOuterAttrs() {
		final StringBuffer sb = new StringBuffer(64);
		HTMLs.appendAttribute(sb, "class", getSclass());
		HTMLs.appendAttribute(sb, "style", getRealStyle());
		HTMLs.appendAttribute(sb, "title", getTooltiptext());
		HTMLs.appendAttribute(sb, "z.drag", _draggable);
		HTMLs.appendAttribute(sb, "z.drop", _droppable);

		final Object xc = getExtraCtrl();
		if ((xc instanceof ZidRequired) && ((ZidRequired)xc).isZidRequired()) {
			final String id = getId();
	 		if (!ComponentsCtrl.isAutoId(id))
				HTMLs.appendAttribute(sb, "z.zid", id);
		}
		return sb.toString();
	}
	/** Returns the interior attributes for generating the inner HTML tag;
	 * never return null.
	 *
	 * <p>Used only by component developers.
	 *
	 * <p>Default: empty string.
	 * Refer to {@link #getOuterAttrs} for more details.
	 */
	public String getInnerAttrs() {
		return "";
	}

	/** Returns the real style after appending width, height and others
	 * to {@link #setStyle} (never null).
	 * <p>Use {@link #getRealStyleFlags} to control what attributes to
	 * exclude.
	 */
	protected String getRealStyle() {
		final int flags = getRealStyleFlags();
		final StringBuffer sb = new StringBuffer(32);

		if ((flags & RS_NO_WIDTH) == 0)
			HTMLs.appendStyle(sb, "width", getWidth());
		if ((flags & RS_NO_HEIGHT) == 0)
			HTMLs.appendStyle(sb, "height", getHeight());

		HTMLs.appendStyle(sb, "left", getLeft());
		HTMLs.appendStyle(sb, "top", getTop());

		final int zIndex = getZIndex();
		if (zIndex > 0)
			HTMLs.appendStyle(sb, "z-index", Integer.toString(zIndex));

		String style = getStyle();
		if (style != null && style.length() > 0) {
			sb.append(style);
			if (!style.endsWith(";")) sb.append(';');
		}
		if ((flags & RS_NO_DISPLAY) == 0 && !isVisible()) {
			if (sb.length() == 0)
				return "display:none;";
			sb.append("display:none;");
		}
		return sb.toString();
	}
	/** Used by {@link #getRealStyleFlags} to denote that {@link #getRealStyle}
	 * shall not generate the width style.
	 */
	protected static final int RS_NO_WIDTH = 0x0001;
	/** Used by {@link #getRealStyleFlags} to denote that {@link #getRealStyle}
	 * shall not generate the height style.
	 */
	protected static final int RS_NO_HEIGHT = 0x0002;
	/** Used by {@link #getRealStyleFlags} to denote that {@link #getRealStyle}
	 * shall not generate the display style.
	 */
	protected static final int RS_NO_DISPLAY = 0x0004;
	/** Returns a combination of {@link #RS_NO_WIDTH} and {@link #RS_NO_HEIGHT}.
	 * <p>Default: return 0.
	 */
	protected int getRealStyleFlags() {
		return 0;
	}

	/** Returns whether to send back the request of the specified event
	 * immediately (ASAP). Returns true if you want the component (on the server)
	 * to process the event immediately.
	 *
	 * <p>Default: return true if any ASAP event handler or listener of
	 * the specified event is found. In other words, it returns
	 * {@link Events#isListenerAvailable}.
	 */
	protected boolean isAsapRequired(String evtnm) {
		return Events.isListenerAvailable(this, evtnm, true);
	}
	/** Appends the HTML attribute for the specified event name, say, onChange.
	 * It is called by derived's {@link #getOuterAttrs}.
	 *
	 * @param sb the string buffer to hold the HTML attribute. If null and
	 * {@link #isAsapRequired} is true, a string buffer is created and returned.
	 * @return the string buffer. If sb is null and {@link #isAsapRequired}
	 * 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).
	 */
	protected StringBuffer appendAsapAttr(StringBuffer sb, String evtnm) {
		if (isAsapRequired(evtnm)) {
			if (sb == null) sb = new StringBuffer(80);
			HTMLs.appendAttribute(sb, getAttrOfEvent(evtnm), true);
		}
		return sb;
	}
	private static String getAttrOfEvent(String evtnm) {
		return Events.ON_CLICK.equals(evtnm) ? "z.lfclk":
			Events.ON_RIGHT_CLICK.equals(evtnm) ? "z.rtclk":
			Events.ON_DOUBLE_CLICK.equals(evtnm) ? "z.dbclk":
				"z." + evtnm;
	}

	//-- Component --//
	public boolean addEventListener(String evtnm, EventListener listener) {
		if (isTransparent(this))
			return super.addEventListener(evtnm, listener);
			//Deriver has to handle it

		final boolean asap = isAsapRequired(evtnm);
		final boolean ret = super.addEventListener(evtnm, listener);
		if (ret && !asap && isAsapRequired(evtnm))
			smartUpdate(getAttrOfEvent(evtnm), "true");
		return ret;
	}
	public boolean removeEventListener(String evtnm, EventListener listener) {
		if (isTransparent(this))
			return super.removeEventListener(evtnm, listener);

		final boolean asap = isAsapRequired(evtnm);
		final boolean ret = super.removeEventListener(evtnm, listener);
		if (ret && asap && !isAsapRequired(evtnm))
			smartUpdate(getAttrOfEvent(evtnm), null);
		return ret;
	}
	private static boolean isTransparent(Component comp) {
		final Object xc = ((ComponentCtrl)comp).getExtraCtrl();
		return (xc instanceof Transparent) && ((Transparent)xc).isTransparent();
	}

	//--ComponentCtrl--//
	/** Used by {@link #getExtraCtrl} to create a client control.
	 * It is used only by component developers.
	 *
	 * <p>Defaut: creates an instance of {@link HtmlBasedComponent.ExtraCtrl}.
	 */
	protected Object newExtraCtrl() {
		return new ExtraCtrl();
	}
	/** A utility class to implement {@link #getExtraCtrl}.
	 * It is used only by component developers.
	 *
	 * <p>If a component requires more client controls, it is suggested to
	 * override {@link #newExtraCtrl} to return an instance that extends from
	 * this interface.
	 */
	protected class ExtraCtrl implements Movable, Sizable, ZIndexed {
		//-- Movable --//
		public void setLeftByClient(String left) {
			_left =left;
		}
		public void setTopByClient(String top) {
			_top = top;
		}
		//-- Sizable --//
		public void setWidthByClient(String width) {
			_width = width;
		}
		public void setHeightByClient(String height) {
			_height = height;
		}
		//-- ZIndexed --//
		public void setZIndexByClient(int zIndex) {
			_zIndex = zIndex;
		}
	}
}