001    /*
002     * Copyright 2002 - 2007 JEuclid, http://jeuclid.sf.net
003     *
004     * Licensed under the Apache License, Version 2.0 (the "License");
005     * you may not use this file except in compliance with the License.
006     * You may obtain a copy of the License at
007     *
008     *      http://www.apache.org/licenses/LICENSE-2.0
009     *
010     * Unless required by applicable law or agreed to in writing, software
011     * distributed under the License is distributed on an "AS IS" BASIS,
012     * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013     * See the License for the specific language governing permissions and
014     * limitations under the License.
015     */
016    
017    /* $Id: LayoutInfo.java,v 686a662dbcbe 2009/01/28 09:11:26 maxberger $ */
018    
019    package net.sourceforge.jeuclid.layout;
020    
021    import java.util.List;
022    
023    /**
024     * Represented Information about a layouted object.
025     * <p>
026     * 
027     * The completeness of this information depends on the objects
028     * {@link LayoutStage}.
029     * <p>
030     * Each object is described with:
031     * <ul>
032     * <li>Origin: {@link #getPosX(LayoutStage)}, {@link #getPosY(LayoutStage)})
033     * <li>Horizontal Size: {@link #getWidth(LayoutStage)})
034     * <li>Vertical Size: {@link #getAscentHeight(LayoutStage)},
035     * {@link #getDescentHeight(LayoutStage)}
036     * </ul>
037     * <p>
038     * Coordinates are given relative to the baseline. If the object has no
039     * descent, this means the origin of the object is the lower left corner.
040     * <p>
041     * The actual Graphical representation can be retrieved with
042     * {@link #getGraphicObjects()}.
043     * <p>
044     * The stretch information ( {@link #getStretchAscent()},
045     * {@link #getStretchDescent()}, {@link #getStretchWidth()}) is set during the
046     * parents layout and defines the size to which stretchable operators are
047     * scaled to.
048     * 
049     * @version $Revision: 686a662dbcbe $
050     */
051    public interface LayoutInfo {
052    
053        /**
054         * The {@link LayoutStage} this element represents. The information will
055         * not be complete until the final LayoutStage ({@link LayoutStage#STAGE2}
056         * ) has been reached.
057         * 
058         * @return current layout stage.
059         */
060        LayoutStage getLayoutStage();
061    
062        /**
063         * @param newStage
064         *            new Layout Stage.
065         */
066        void setLayoutStage(LayoutStage newStage);
067    
068        /**
069         * Returns the current height of the upper part of this component from the
070         * baseline.
071         * 
072         * @return Height of the upper part
073         * @param stage
074         *            {@link LayoutStage} to get this information for (either
075         *            {@link LayoutStage#STAGE1} or {@link LayoutStage#STAGE2})
076         */
077        float getAscentHeight(LayoutStage stage);
078    
079        /**
080         * Returns the current height of the lower part of this component from the
081         * baseline.
082         * 
083         * @return Height of the lower part.
084         * @param stage
085         *            {@link LayoutStage} to get this information for (either
086         *            {@link LayoutStage#STAGE1} or {@link LayoutStage#STAGE2})
087         */
088        float getDescentHeight(LayoutStage stage);
089    
090        /**
091         * Returns the current width of this element.
092         * 
093         * @return Width of this element.
094         * @param stage
095         *            {@link LayoutStage} to get this information for (either
096         *            {@link LayoutStage#STAGE1} or {@link LayoutStage#STAGE2})
097         */
098        float getWidth(LayoutStage stage);
099    
100        /**
101         * Retrieve the X-position of the horizontal center of the content. In
102         * most cases, this will be width / 2. This does not, however, take extra
103         * borders into account. An element may have different border width on
104         * left and right, in which case the center will be moved.
105         * 
106         * @return X-position of the center of the content
107         * @param stage
108         *            {@link LayoutStage} to get this information for (either
109         *            {@link LayoutStage#STAGE1} or {@link LayoutStage#STAGE2})
110         */
111        float getHorizontalCenterOffset(LayoutStage stage);
112    
113        /**
114         * @param newOffset
115         *            new horizontal offset.
116         * @param stage
117         *            {@link LayoutStage} to get this information for (either
118         *            {@link LayoutStage#STAGE1} or {@link LayoutStage#STAGE2})
119         */
120        void setHorizontalCenterOffset(float newOffset, LayoutStage stage);
121    
122        /**
123         * Retrieve the X position of this element relative to its parent.
124         * 
125         * @return X position
126         * @param stage
127         *            {@link LayoutStage} to get this information for (either
128         *            {@link LayoutStage#STAGE1} or {@link LayoutStage#STAGE2})
129         */
130        float getPosX(LayoutStage stage);
131    
132        /**
133         * Retrieve the Y position of this element relative to its parent.
134         * 
135         * @return Y position
136         * @param stage
137         *            {@link LayoutStage} to get this information for (either
138         *            {@link LayoutStage#STAGE1} or {@link LayoutStage#STAGE2})
139         */
140        float getPosY(LayoutStage stage);
141    
142        /**
143         * Move this element to the given position relative to its parent.
144         * 
145         * @param x
146         *            new X position
147         * @param y
148         *            new Y position
149         * @param stage
150         *            {@link LayoutStage} to get this information for (either
151         *            {@link LayoutStage#STAGE1} or {@link LayoutStage#STAGE2})
152         */
153        void moveTo(float x, float y, LayoutStage stage);
154    
155        /**
156         * Shift vertically by given offset.
157         * 
158         * @param offsetY
159         *            offset to shift.
160         * @param stage
161         *            Stage to manipulate.
162         */
163        void shiftVertically(float offsetY, LayoutStage stage);
164    
165        /**
166         * @param ascentHeight
167         *            new ascentHeight.
168         * @param stage
169         *            {@link LayoutStage} to get this information for (either
170         *            {@link LayoutStage#STAGE1} or {@link LayoutStage#STAGE2})
171         */
172        void setAscentHeight(float ascentHeight, LayoutStage stage);
173    
174        /**
175         * @param descentHeight
176         *            new descentHeight.
177         * @param stage
178         *            {@link LayoutStage} to get this information for (either
179         *            {@link LayoutStage#STAGE1} or {@link LayoutStage#STAGE2})
180         */
181        void setDescentHeight(float descentHeight, LayoutStage stage);
182    
183        /**
184         * @param width
185         *            new width.
186         * @param stage
187         *            {@link LayoutStage} to get this information for (either
188         *            {@link LayoutStage#STAGE1} or {@link LayoutStage#STAGE2})
189         */
190        void setWidth(float width, LayoutStage stage);
191    
192        /**
193         * Set the stretch width for children, or < 0 if children should be
194         * horizontally unstretched.
195         * 
196         * @param stretchWidth
197         *            new stretch width
198         */
199        void setStretchWidth(float stretchWidth);
200    
201        /**
202         * Retrieve the stretch width if set, or STAGE1.width if unset.
203         * 
204         * @return stretch width.
205         */
206        float getStretchWidth();
207    
208        /**
209         * Set the stretch descent for children. Defaults to STAGE1.descent
210         * 
211         * @param stretchDescent
212         *            new stretch descent
213         */
214        void setStretchDescent(float stretchDescent);
215    
216        /**
217         * Retrieve the stretch descent if set, or STAGE1.descent if unset.
218         * 
219         * @return stretch descent.
220         */
221        float getStretchDescent();
222    
223        /**
224         * Set the stretch ascent for children. Defaults to STAGE1.ascent
225         * 
226         * @param stretchAscent
227         *            new stretch ascent
228         */
229        void setStretchAscent(float stretchAscent);
230    
231        /**
232         * Retrieve the stretch ascent if set, or STAGE1.ascent if unset.
233         * 
234         * @return stretch ascent.
235         */
236        float getStretchAscent();
237    
238        /**
239         * @param graphicsObject
240         *            the GraphicsObject to set.
241         */
242        void setGraphicsObject(GraphicsObject graphicsObject);
243    
244        /**
245         * @return Graphic objects associated with this node.
246         */
247        List<GraphicsObject> getGraphicObjects();
248    }