From: Marc Englund Date: Fri, 11 Dec 2009 14:50:39 +0000 (+0000) Subject: Added some javadoc, for #3763 X-Git-Tag: 6.7.0.beta1~2174 X-Git-Url: https://source.dussan.org/?a=commitdiff_plain;h=8e34bda615bfcd97e738b78c6bd48dff50cc660a;p=vaadin-framework.git Added some javadoc, for #3763 svn changeset:10262/svn branch:6.2 --- diff --git a/src/com/vaadin/terminal/gwt/client/ApplicationConnection.java b/src/com/vaadin/terminal/gwt/client/ApplicationConnection.java index 5b6d094474..8060edfe74 100755 --- a/src/com/vaadin/terminal/gwt/client/ApplicationConnection.java +++ b/src/com/vaadin/terminal/gwt/client/ApplicationConnection.java @@ -59,6 +59,9 @@ import com.vaadin.terminal.gwt.server.AbstractCommunicationManager; * Entry point classes (widgetsets) define onModuleLoad(). */ public class ApplicationConnection { + // This indicates the whole page is generated by us (not embedded) + public static final String GENERATED_BODY_CLASSNAME = "v-generated-body"; + private static final String MODIFIED_CLASSNAME = "v-modified"; private static final String REQUIRED_CLASSNAME_EXT = "-required"; @@ -75,9 +78,6 @@ public class ApplicationConnection { public static final String UIDL_SECURITY_TOKEN_ID = "Vaadin-Security-Key"; - // This indicates the whole page is generated by us (not embedded) - public static final String GENERATED_BODY_CLASSNAME = "v-generated-body"; - /** * @deprecated use UIDL_SECURITY_TOKEN_ID instead */ @@ -89,6 +89,7 @@ public class ApplicationConnection { public static final String ATTRIBUTE_DESCRIPTION = "description"; public static final String ATTRIBUTE_ERROR = "error"; + // will hold the UIDL security key (for XSS protection) once received private String uidl_security_key = "init"; private final HashMap resourcesMap = new HashMap(); @@ -279,6 +280,12 @@ public class ApplicationConnection { } }-*/; + /** + * Get the active Console for writing debug messages. May return an actual + * logging console, or the NullConsole if debugging is not turned on. + * + * @return the active Console + */ public static Console getConsole() { return console; } @@ -317,6 +324,12 @@ public class ApplicationConnection { return configuration.getApplicationUri(); }; + /** + * Indicates whether or not there are currently active UIDL requests. Used + * internally to squence requests properly, seldom needed in Widgets. + * + * @return true if there are active requests + */ public boolean hasActiveRequest() { return (activeRequests > 0); } @@ -640,6 +653,11 @@ public class ApplicationConnection { } } + /** + * Determines whether or not the loading indicator is showing. + * + * @return true if the loading indicator is visible + */ public boolean isLoadingIndicatorVisible() { if (loadElement == null) { return false; @@ -893,19 +911,55 @@ public class ApplicationConnection { el.tkPid = pid; }-*/; + /** + * Gets the paintableId for a specific paintable (a.k.a Vaadin Widget). + *

+ * The paintableId is used in the UIDL to identify a specific widget + * instance, effectively linking the widget with it's server side Component. + *

+ * + * @param paintable + * the paintable who's id is needed + * @return the id for the given paintable + */ public String getPid(Paintable paintable) { return getPid(((Widget) paintable).getElement()); } + /** + * Gets the paintableId using a DOM element - the element should be the main + * element for a paintable otherwise no id will be found. Use + * {@link #getPid(Paintable)} instead whenever possible. + * + * @see #getPid(Paintable) + * @param el + * element of the paintable whose pid is desired + * @return the pid of the element's paintable, if it's a paintable + */ public native String getPid(Element el) /*-{ return el.tkPid; }-*/; + /** + * Gets the main element for the paintable with the given id. The revers of + * {@link #getPid(Element)}. + * + * @param pid + * the pid of the widget whose element is desired + * @return the element for the paintable corresponding to the pid + */ public Element getElementByPid(String pid) { return ((Widget) getPaintable(pid)).getElement(); } + /** + * Unregisters the given paintable; always use after removing a paintable. + * Does not actually remove the paintable from the DOM. + * + * @param p + * the paintable to remove + */ public void unregisterPaintable(Paintable p) { if (p == null) { ApplicationConnection.getConsole().error( @@ -919,6 +973,15 @@ public class ApplicationConnection { } } + /** + * Unregisters a paintable and all it's child paintables recursively. Use + * when after removing a paintable that contains other paintables. Does not + * unregister the given container itself. Does not actually remove the + * paintable from the DOM. + * + * @see #unregisterPaintable(Paintable) + * @param container + */ public void unregisterChildPaintables(HasWidgets container) { final Iterator it = container.iterator(); while (it.hasNext()) { @@ -1031,47 +1094,189 @@ public class ApplicationConnection { makeUidlRequest(req.toString(), false, forceSync, false); } + /** + * Sends a new value for the given paintables given variable to the server. + *

+ * The update is actually queued to be sent at a suitable time. If immediate + * is true, the update is sent as soon as possible. If immediate is false, + * the update will be sent along with the next immediate update. + *

+ * + * @param paintableId + * the id of the paintable that owns the variable + * @param variableName + * the name of the variable + * @param newValue + * the new value to be sent + * @param immediate + * true if the update is to be sent as suun as possible + */ public void updateVariable(String paintableId, String variableName, Paintable newValue, boolean immediate) { String pid = (newValue != null) ? getPid(newValue) : null; addVariableToQueue(paintableId, variableName, pid, immediate, 'p'); } + /** + * Sends a new value for the given paintables given variable to the server. + *

+ * The update is actually queued to be sent at a suitable time. If immediate + * is true, the update is sent as soon as possible. If immediate is false, + * the update will be sent along with the next immediate update. + *

+ * + * @param paintableId + * the id of the paintable that owns the variable + * @param variableName + * the name of the variable + * @param newValue + * the new value to be sent + * @param immediate + * true if the update is to be sent as suun as possible + */ + public void updateVariable(String paintableId, String variableName, String newValue, boolean immediate) { addVariableToQueue(paintableId, variableName, newValue, immediate, 's'); } + /** + * Sends a new value for the given paintables given variable to the server. + *

+ * The update is actually queued to be sent at a suitable time. If immediate + * is true, the update is sent as soon as possible. If immediate is false, + * the update will be sent along with the next immediate update. + *

+ * + * @param paintableId + * the id of the paintable that owns the variable + * @param variableName + * the name of the variable + * @param newValue + * the new value to be sent + * @param immediate + * true if the update is to be sent as suun as possible + */ + public void updateVariable(String paintableId, String variableName, int newValue, boolean immediate) { addVariableToQueue(paintableId, variableName, "" + newValue, immediate, 'i'); } + /** + * Sends a new value for the given paintables given variable to the server. + *

+ * The update is actually queued to be sent at a suitable time. If immediate + * is true, the update is sent as soon as possible. If immediate is false, + * the update will be sent along with the next immediate update. + *

+ * + * @param paintableId + * the id of the paintable that owns the variable + * @param variableName + * the name of the variable + * @param newValue + * the new value to be sent + * @param immediate + * true if the update is to be sent as suun as possible + */ + public void updateVariable(String paintableId, String variableName, long newValue, boolean immediate) { addVariableToQueue(paintableId, variableName, "" + newValue, immediate, 'l'); } + /** + * Sends a new value for the given paintables given variable to the server. + *

+ * The update is actually queued to be sent at a suitable time. If immediate + * is true, the update is sent as soon as possible. If immediate is false, + * the update will be sent along with the next immediate update. + *

+ * + * @param paintableId + * the id of the paintable that owns the variable + * @param variableName + * the name of the variable + * @param newValue + * the new value to be sent + * @param immediate + * true if the update is to be sent as suun as possible + */ + public void updateVariable(String paintableId, String variableName, float newValue, boolean immediate) { addVariableToQueue(paintableId, variableName, "" + newValue, immediate, 'f'); } + /** + * Sends a new value for the given paintables given variable to the server. + *

+ * The update is actually queued to be sent at a suitable time. If immediate + * is true, the update is sent as soon as possible. If immediate is false, + * the update will be sent along with the next immediate update. + *

+ * + * @param paintableId + * the id of the paintable that owns the variable + * @param variableName + * the name of the variable + * @param newValue + * the new value to be sent + * @param immediate + * true if the update is to be sent as suun as possible + */ + public void updateVariable(String paintableId, String variableName, double newValue, boolean immediate) { addVariableToQueue(paintableId, variableName, "" + newValue, immediate, 'd'); } + /** + * Sends a new value for the given paintables given variable to the server. + *

+ * The update is actually queued to be sent at a suitable time. If immediate + * is true, the update is sent as soon as possible. If immediate is false, + * the update will be sent along with the next immediate update. + *

+ * + * @param paintableId + * the id of the paintable that owns the variable + * @param variableName + * the name of the variable + * @param newValue + * the new value to be sent + * @param immediate + * true if the update is to be sent as suun as possible + */ + public void updateVariable(String paintableId, String variableName, boolean newValue, boolean immediate) { addVariableToQueue(paintableId, variableName, newValue ? "true" : "false", immediate, 'b'); } + /** + * Sends a new value for the given paintables given variable to the server. + *

+ * The update is actually queued to be sent at a suitable time. If immediate + * is true, the update is sent as soon as possible. If immediate is false, + * the update will be sent along with the next immediate update. + *

+ * + * @param paintableId + * the id of the paintable that owns the variable + * @param variableName + * the name of the variable + * @param newValue + * the new value to be sent + * @param immediate + * true if the update is to be sent as suun as possible + */ public void updateVariable(String paintableId, String variableName, Map map, boolean immediate) { final StringBuffer buf = new StringBuffer(); @@ -1117,6 +1322,23 @@ public class ApplicationConnection { return 'u'; } + /** + * Sends a new value for the given paintables given variable to the server. + *

+ * The update is actually queued to be sent at a suitable time. If immediate + * is true, the update is sent as soon as possible. If immediate is false, + * the update will be sent along with the next immediate update. + *

+ * + * @param paintableId + * the id of the paintable that owns the variable + * @param variableName + * the name of the variable + * @param newValue + * the new value to be sent + * @param immediate + * true if the update is to be sent as suun as possible + */ public void updateVariable(String paintableId, String variableName, String[] values, boolean immediate) { final StringBuffer buf = new StringBuffer(); @@ -1130,6 +1352,23 @@ public class ApplicationConnection { immediate, 'c'); } + /** + * Sends a new value for the given paintables given variable to the server. + *

+ * The update is actually queued to be sent at a suitable time. If immediate + * is true, the update is sent as soon as possible. If immediate is false, + * the update will be sent along with the next immediate update. + *

+ * + * @param paintableId + * the id of the paintable that owns the variable + * @param variableName + * the name of the variable + * @param newValue + * the new value to be sent + * @param immediate + * true if the update is to be sent as suun as possible + */ public void updateVariable(String paintableId, String variableName, Object[] values, boolean immediate) { final StringBuffer buf = new StringBuffer(); @@ -1405,11 +1644,13 @@ public class ApplicationConnection { */ private boolean runningLayout = false; + /** + * Causes a re-calculation/re-layout of all paintables in a container. + * + * @param container + */ public void runDescendentsLayout(HasWidgets container) { if (runningLayout) { - // getConsole().log( - // "Already running descendents layout. Not running again for " - // + Util.getSimpleName(container)); return; } runningLayout = true; @@ -1620,6 +1861,13 @@ public class ApplicationConnection { } + /** + * Gets the specified Paintables relative size (percent). + * + * @param widget + * the paintable whose size is needed + * @return the the size if the paintable is relatively sized, -1 otherwise + */ public FloatSize getRelativeSize(Widget widget) { return idToPaintableDetail.get(getPid(widget.getElement())) .getRelativeSize(); @@ -1660,6 +1908,14 @@ public class ApplicationConnection { return getPaintable(getPid(element)); } + /** + * Gets a recource that has been pre-loaded via UIDL, such as custom + * layouts. + * + * @param name + * identifier of the resource to get + * @return the resource + */ public String getResource(String name) { return resourcesMap.get(name); } @@ -1703,6 +1959,12 @@ public class ApplicationConnection { return uidlUri; } + /** + * Gets the URI for the current theme. Can be used to reference theme + * resources. + * + * @return URI to the current theme + */ public String getThemeUri() { return configuration.getThemeUri(); } @@ -1841,14 +2103,30 @@ public class ApplicationConnection { windowName = newName; } + /** + * Use to notify that the given component's caption has changed; layouts may + * have to be recalculated. + * + * @param component + * the Paintable whose caption has changed + */ public void captionSizeUpdated(Paintable component) { componentCaptionSizeChanges.add(component); } + /** + * Requests an analyze of layouts, to find inconsistensies. Exclusively used + * for debugging during develpoment. + */ public void analyzeLayouts() { makeUidlRequest("", true, false, true); } + /** + * Gets the main view, a.k.a top-level window. + * + * @return the main view + */ public VView getView() { return view; } @@ -1882,6 +2160,12 @@ public class ApplicationConnection { componentDetail.putAdditionalTooltip(key, tooltip); } + /** + * Gets the {@link ApplicationConfiguration} for the current application. + * + * @see ApplicationConfiguration + * @return the configuration for this application + */ public ApplicationConfiguration getConfiguration() { return configuration; }