001 /*
002 * This file is part of the Echo Point Project. This project is a collection
003 * of Components that have extended the Echo Web Application Framework.
004 *
005 * Version: MPL 1.1/GPL 2.0/LGPL 2.1
006 *
007 * The contents of this file are subject to the Mozilla Public License Version
008 * 1.1 (the "License"); you may not use this file except in compliance with
009 * the License. You may obtain a copy of the License at
010 * http://www.mozilla.org/MPL/
011 *
012 * Software distributed under the License is distributed on an "AS IS" basis,
013 * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
014 * for the specific language governing rights and limitations under the
015 * License.
016 *
017 * Alternatively, the contents of this file may be used under the terms of
018 * either the GNU General Public License Version 2 or later (the "GPL"), or
019 * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
020 * in which case the provisions of the GPL or the LGPL are applicable instead
021 * of those above. If you wish to allow use of your version of this file only
022 * under the terms of either the GPL or the LGPL, and not to allow others to
023 * use your version of this file under the terms of the MPL, indicate your
024 * decision by deleting the provisions above and replace them with the notice
025 * and other provisions required by the GPL or the LGPL. If you do not delete
026 * the provisions above, a recipient may use your version of this file under
027 * the terms of any one of the MPL, the GPL or the LGPL.
028 */
029 package echopoint.able;
030
031 import nextapp.echo.app.Extent;
032
033 /**
034 * A <code>Positionable</code> is one that can be postioned anywhere on the
035 * screen, regardless of the flow layout of other components.
036 * <p>
037 * By default the it acts like a normal component, and will be rendered with the
038 * flow of its parent and siblings. The component has its Positioning property
039 * set to POSITIONING_FLOW.
040 * <p>
041 * <h3>POSITIONING</h3>
042 *
043 * However if the Positioning property is POSITIONING_ABSOLUTE or
044 * POSITIONING_RELATIVE then the component will break out of the normal flow
045 * layout and position themselves directly on the screen.
046 * <p>
047 * If the Positioning is POSITIONING_RELATIVE, then the component is positioned
048 * at an at a point on the screen relative to its first positioned parent
049 * component. If it has no parents that are positioned, then it will be
050 * positioned relative to the origins of the client window.
051 * <p>
052 * If the Positioning is POSITIONING_ABSOLUTE, then the component is positioned
053 * at an absolute point outside the normal flow of layout. The left, top, right
054 * and bottom properties can be used to position the component.
055 * <p>
056 * If the Positioning is POSITIONING_FIXED, then the component is positioned at
057 * an absolute point from the origin of the client window. The left, top, right
058 * and bottom properties can be used to position the component.
059 * <p>
060 * <h3>Left, Top, Right, Bottom</h3>
061 * Typically you would set the Left and Top properties in order to get a
062 * Positionable to a specified location. However you can also use the Right and
063 * Bottom properties.
064 * <p>
065 * For example you could position a component to 100 pixels in from the bottom
066 * and 10 pixels if from the right by only settting the bottom and right
067 * properties to 100 and 10 respectively. The width of the component will be
068 * determined by the content.
069 * <p>
070 * A convenience method called <i>clearPositioning() </i> is provided to clear
071 * all positioning and have the component acts like a normal flow component.
072 * <p>
073 * <h3>Z-INDEX</h3>
074 *
075 * A <code>Positionable</code> also supports a z-idex, which controls how it
076 * is layered over other components, especially other <code>Positionable</code>
077 * 's.
078 * <p>
079 * If no zIndex is to apply then the Integer.MIN_VALUE can be used in which case
080 * no zIndex will be set.
081 */
082 public interface Positionable extends Delegateable {
083 /**
084 * The Positionable is a normal Positionable, laid out according to the
085 * normal flow.
086 */
087 public static final int STATIC = 1;
088
089 /**
090 * The Positionable's position (and possibly size) is specified with the
091 * 'top', 'right', 'bottom', and 'left' properties. These properties specify
092 * offsets with respect to the Positionable's containing Positionable.
093 * Absolutely positioned Positionables are taken out of the normal flow.
094 * This means they have no impact on the layout of later siblings.
095 */
096 public static final int ABSOLUTE = 2;
097
098 /**
099 * The Positionable's position is calculated according to the normal flow.
100 * Then the Positionable is offset relative to its normal position.
101 */
102 public static final int RELATIVE = 4;
103
104 /**
105 * The Positionable's position is calculated according to the 'absolute'
106 * model, but in addition, the Positionable is fixed with respect to the
107 * viewport and doesn't move when scrolled.
108 */
109 public static final int FIXED = 8;
110
111 public static final String PROPERTY_BOTTOM = "bottom";
112
113 public static final String PROPERTY_LEFT = "left";
114
115 public static final String PROPERTY_POSITION = "position";
116
117 public static final String PROPERTY_RIGHT = "right";
118
119 public static final String PROPERTY_TOP = "top";
120
121 public static final String PROPERTY_Z_INDEX = "zIndex";
122
123 /**
124 * This sets all the positioning attributes (left,top,right,bottom,z-index)
125 * to null or zero.
126 */
127 public void clear();
128
129 /**
130 * Returns the bottom Y position of the component
131 */
132 public Extent getBottom();
133
134 /**
135 * Returns the left X position of the component
136 */
137 public Extent getLeft();
138
139 /**
140 * This can be one of :
141 * <ul>
142 * <li>POSITIONING_STATIC</li>
143 * <li>POSITIONING_RELATIVE</li>
144 * <li>POSITIONING_ABSOLUTE</li>
145 * <li>POSITIONING_FIXED</li>
146 * </ul>
147 */
148 public int getPosition();
149
150 /**
151 * Returns the right X position of the component
152 */
153 public Extent getRight();
154
155 /**
156 * Returns the top Y position of the component
157 */
158 public Extent getTop();
159
160 /**
161 * Returns the z-index of the component
162 */
163 public int getZIndex();
164
165 /**
166 * This returns true if any positioning is in place other than
167 * normal flow ie. STATIC.
168 *
169 */
170 public boolean isPositioned();
171
172 /**
173 * Sets the bottom Y position of the component
174 */
175 public void setBottom(Extent newValue);
176
177 /**
178 * Set the left X position of the component
179 */
180 public void setLeft(Extent newValue);
181
182 /**
183 * Sets the position of the component
184 *
185 * This can be one of :
186 * <ul>
187 * <li>POSITIONING_STATIC</li>
188 * <li>POSITIONING_RELATIVE</li>
189 * <li>POSITIONING_ABSOLUTE</li>
190 * <li>POSITIONING_FIXED</li>
191 * </ul>
192 */
193 public void setPosition(int newPositioning);
194
195 /**
196 * Sets the right X position of the component
197 */
198 public void setRight(Extent newValue);
199
200 /**
201 * Sets the top Y position of the component
202 */
203 public void setTop(Extent newValue);
204
205 /**
206 * Sets the z-index of the component
207 */
208 public void setZIndex(int newValue);
209 }