001: /* PageCtrl.java
002:
003: {{IS_NOTE
004: Purpose:
005:
006: Description:
007:
008: History:
009: Wed Jun 8 13:55:09 2005, Created by tomyeh
010: }}IS_NOTE
011:
012: Copyright (C) 2005 Potix Corporation. All Rights Reserved.
013:
014: {{IS_RIGHT
015: This program is distributed under GPL Version 2.0 in the hope that
016: it will be useful, but WITHOUT ANY WARRANTY.
017: }}IS_RIGHT
018: */
019: package org.zkoss.zk.ui.sys;
020:
021: import java.util.Collection;
022: import java.io.Writer;
023: import java.io.IOException;
024:
025: import org.zkoss.zk.ui.Desktop;
026: import org.zkoss.zk.ui.Component;
027: import org.zkoss.zk.ui.Execution;
028: import org.zkoss.zk.ui.UiException;
029: import org.zkoss.zk.ui.metainfo.ZScript;
030:
031: /**
032: * Addition interface to {@link org.zkoss.zk.ui.Page} for implementation
033: * purpose.
034: *
035: * <p>Application developers shall never access any of this methods.
036: *
037: * @author tomyeh
038: */
039: public interface PageCtrl {
040: /** The execution attribute used to control {@link #redraw} to use
041: * include instead of forward to redraw the page
042: */
043: public static final String ATTR_REDRAW_BY_INCLUDE = "org.zkoss.zk.ui.redrawByInclude";
044:
045: /** Initializes this page by assigning the info provided by
046: * the specified {@link PageConfig}, and then adds it
047: * to a desktop (by use of {@link Execution#getDesktop}).
048: *
049: * <p>This method shall be called only after the current execution
050: * is activated.
051: *
052: * @param config the info about how to initialize this page
053: * @since 3.0.0
054: */
055: public void init(PageConfig config);
056:
057: /** Called when this page is about to be detroyed.
058: * It is called by desktop, after removing it from the desktop.
059: */
060: public void destroy();
061:
062: /** Returns the header elements declared in this page (never null).
063: * An empty string is returned if special header is defined.
064: * <p>For HTML, the header element is the HEAD element.
065: */
066: public String getHeaders();
067:
068: /** Returns the attributes of the root element declared in this page
069: * (never null).
070: * An empty string is returned if no special attribute is declared.
071: *
072: * <p>For HTML, the root element is the HTML element.
073: * @since 3.0.0
074: */
075: public String getRootAttributes();
076:
077: /** Set the attributes of the root element declared in this page
078: *
079: * <p>Default: "".
080: */
081: public void setRootAttributes(String rootAttributes);
082:
083: /** Returns the doc type (<!DOCTYPE>),
084: * or null to use the device default.
085: *
086: * @since 3.0.0
087: */
088: public String getDocType();
089:
090: /** Sets the doc type (<!DOCTYPE>).
091: *
092: * <p>Default: null (i.e., the device default)
093: * @since 3.0.0
094: */
095: public void setDocType(String docType);
096:
097: /** Returns the first line to be generated to the output,
098: * or null if nothing to generate.
099: *
100: * <p>For XML devices, it is usually the xml processing instruction:<br/>
101: * <code><?xml version="1.0" encoding="UTF-8"?>
102: *
103: * @since 3.0.0
104: */
105: public String getFirstLine();
106:
107: /** Sets the first line to be generated to the output.
108: *
109: * <p>Default: null (i.e., nothing generated)
110: * @since 3.0.0
111: */
112: public void setFirstLine(String firstLine);
113:
114: /** Returns the content type, or null to use the device default.
115: *
116: * @since 3.0.0
117: */
118: public String getContentType();
119:
120: /** Sets the content type.
121: *
122: * @since 3.0.0
123: */
124: public void setContentType(String contentType);
125:
126: /** Returns if the client can cache the rendered result, or null
127: * to use the device default.
128: *
129: * @since 3.0.0
130: */
131: public Boolean getCacheable();
132:
133: /** Sets if the client can cache the rendered result.
134: *
135: * <p>Default: null (use the device default).
136: * @since 3.0.0
137: */
138: public void setCacheable(Boolean cacheable);
139:
140: /** Returns the owner of this page, or null if it is not owned by
141: * any component.
142: * A page is included by a component. We say it is owned by the component.
143: */
144: public Component getOwner();
145:
146: /** Sets the owner of this page.
147: * <p>Used only internally.
148: */
149: public void setOwner(Component comp);
150:
151: /** Redraws the whole page into the specified output.
152: *
153: * <p>You could use {@link #ATTR_REDRAW_BY_INCLUDE} to control
154: * whether to include, instead of forward, the page content.
155: * By default, {@link Execution#forward } is used if possible.
156: *
157: * @param responses a list of responses that the page has to generate
158: * corresponding javascript to process them; or null if no such responses.
159: * The responses is not null, if and only if the page is creating
160: */
161: public void redraw(Collection responses, Writer out)
162: throws IOException;
163:
164: //-- Used for component implementation --//
165: /** Adds a root component to a page.
166: * <p>It is used internally and developers shall not invoke it
167: * explicityly.
168: * @see Component#setPage
169: */
170: public void addRoot(Component comp);
171:
172: /** Detaches a root component from this page.
173: * <p>It is used internally and developers shall not invoke it
174: * explicitly
175: * @see Component#setPage
176: */
177: public void removeRoot(Component comp);
178:
179: /** Moves a root component before the reference component.
180: *
181: * <p>Note: it assumes removeRoot was called before for comp.
182: * Otherwise, nothing happens.
183: *
184: * <p>It is used internally and developers shall not invoke it
185: * explicitly
186: *
187: * @since 3.0.0
188: * @see Component#setPageBefore
189: */
190: public void moveRoot(Component comp, Component refRoot);
191:
192: /** Adds a fellow. */
193: public void addFellow(Component comp);
194:
195: /** Removes a fellow. */
196: public void removeFellow(Component comp);
197:
198: /** Returns whether a fellow exists with the specified component ID.
199: */
200: public boolean hasFellow(String compId);
201:
202: /** Adds a deferred zscript.
203: *
204: * @param parent the component that is the parent of zscript (in
205: * the ZUML page), or null if it belongs to the page.
206: * @param zscript the zscript that shall be evaluated as late as
207: * when the interpreter of the same language is being loaded.
208: */
209: public void addDeferredZScript(Component parent, ZScript zscript);
210:
211: /** Returns the default parent, or null if no such parent.
212: * If a default parent is defined (by use of {@link #setDefaultParent}),
213: * {@link org.zkoss.zk.ui.Executions#createComponents(String, Component, java.util.Map)} will
214: * use it as the default parent, if developers didn't specify one.
215: */
216: public Component getDefaultParent();
217:
218: /** Sets the default parent.
219: *
220: * <p>It is rarely used by application developers. Rather, it is used
221: * by ZHTML's body to make sure new created compnents are placed
222: * correctly.
223: *
224: * <p>Caller has to ensure the comp is part of the page. Otherwise,
225: * the result is unpreditable.
226: *
227: * @see #getDefaultParent
228: */
229: public void setDefaultParent(Component comp);
230:
231: /** Notification that the session, which owns this page,
232: * is about to be passivated (aka., serialized).
233: */
234: public void sessionWillPassivate(Desktop desktop);
235:
236: /** Notification that the session, which owns this page,
237: * has just been activated (aka., deserialized).
238: */
239: public void sessionDidActivate(Desktop desktop);
240: }
|