001package org.vishia.gral.area9;
002
003import java.io.File;
004
005import org.vishia.gral.base.GralGraphicTimeOrder;
006import org.vishia.gral.base.GralMenu;
007import org.vishia.gral.base.GralMng;
008import org.vishia.gral.base.GralPanelContent;
009import org.vishia.gral.base.GralTextBox;
010import org.vishia.gral.ifc.GralMngApplAdapter_ifc;
011import org.vishia.gral.ifc.GralPrimaryWindow_ifc;
012import org.vishia.gral.ifc.GralUserAction;
013import org.vishia.gral.ifc.GralWidget_ifc;
014import org.vishia.gral.ifc.GralTextBox_ifc;
015import org.vishia.gral.ifc.GralWindow_ifc;
016import org.vishia.mainCmd.MainCmd_ifc;
017
018
019
020/**This interface supports the usage of a window which is divide into 9 areas. 
021 * The 2 horizontal and 2 vertical separation lines may able to move in the implementation class.
022 * In that kind the areas are adjustable in size. Some of the 9 areas in a rectangle can be combined
023 * to build a greater area. In that kind a proper user-adequate dividing of the window is possible.
024 * In opposite to some other graphic systems the user have fix positions for some input or output areas,
025 * which can only adjusted in size. This may be an advantage in opposite to a free changeable 
026 * window layout.
027 * <br><br>
028 * The 9 areas:
029 * <pre>
030 * +---------+-------------------+--------------+
031 * |         |                   |              |   
032 * +---------+-------------------+--------------+   
033 * |         |                   |              |   
034 * |         |                   |              |   
035 * +---------+-------------------+--------------+   
036 * |         |                   |              |   
037 * +---------+-------------------+--------------+  
038 * </pre>
039 * Example for combined areas:
040 * <pre>
041 * +---------+-------------------+--------------+
042 * | select  |                                  |   
043 * +---------+     edit area                    |   
044 * |         |                                  |   
045 * | broswing|                                  |   
046 * +         +-------------------+--------------+   
047 * |         |    output area    | status       |   
048 * +---------+-------------------+--------------+  
049 * </pre>
050 * Usual an application needs only a few but stable areas. 
051 * @author Hartmut Schorrig
052 *
053 */
054public interface GralArea9_ifc extends GralMngApplAdapter_ifc
055{
056  /**Version history:
057   * <ul>
058   * <li>2012-05-17 Hartmut new: {@link #setMinMaxSizeArea(String, int, int, int, int)}: The size can be given 
059   *   with gral units, as min, max or absolute (min, max are equal). The size of a area border can be changed on runtime.
060   * <li>2012-03-25 Hartmut new/chg: {@link #addFrameArea(String, GralPanelContent)} now with String designation of area.
061   *   It should be used instead designation with 4 integers in range 1..3.
062   * <li>2011-12-26 Hartmut new extends {@link GralMngApplAdapter_ifc}
063   * <li>2011-11-12 Hartmut chg: {@link #initGraphic(String)} instead initOutputArea().
064   * <li>2011-11-12 Hartmut new: {@link #getActionAbout()} and {@link #getActionAbout()} to support menu setting by user
065   * <li>2011-08-06 Hartmut chg: This interface is based on MainCmd_ifc. It is a non-side-effect change
066   *   because the implementation classes {@link MainCmdSwt} and maybe the adequate Swing class base on {@link MainCmd}.
067   *   Using this change only this interface is necessary for applications to use {@link MainCmdSwt} or adequate Swing 
068   * <li>2011-05-03 Hartmut created: The idea is a common GUI interface independent of Swing or SWT graphics.
069   *     The classes {@link org.vishia.mainGuiSwt.MainCmdSwt} and {@link MainCmdSwing} exists.
070   *     The interface should combine the usage of both.
071   *     Second approach is the documentation of the concept of the 9 areas in a non-implementing class.
072   * <li>All other changes from 2010 and in the past
073   * </ul>
074   * 
075   * <b>Copyright/Copyleft</b>:
076   * For this source the LGPL Lesser General Public License,
077   * published by the Free Software Foundation is valid.
078   * It means:
079   * <ol>
080   * <li> You can use this source without any restriction for any desired purpose.
081   * <li> You can redistribute copies of this source to everybody.
082   * <li> Every user of this source, also the user of redistribute copies
083   *    with or without payment, must accept this license for further using.
084   * <li> But the LPGL ist not appropriate for a whole software product,
085   *    if this source is only a part of them. It means, the user
086   *    must publish this part of source,
087   *    but don't need to publish the whole source of the own product.
088   * <li> You can study and modify (improve) this source
089   *    for own using or for redistribution, but you have to license the
090   *    modified sources likewise under this LGPL Lesser General Public License.
091   *    You mustn't delete this Copyright/Copyleft inscription in this source file.
092   * </ol>
093   * If you are indent to use this sources without publishing its usage, you can get
094   * a second license subscribing a special contract with the author. 
095   * 
096   * @author Hartmut Schorrig = hartmut.schorrig@vishia.de
097   * 
098   */
099  final static int version = 0x20111227;
100
101  
102  /**Initializes the graphic of the Area9-Window. It sets the Output window to a defined area
103   * and creates Windows for Help, About and InfoBoxes.
104   * This method can be invoked after construction immediately in any thread. 
105   * <br><br>
106   * In the implementation class {@link org.vishia.gral.area9.GralArea9Window}
107   * the working is done in the graphic thread. The caller thread waits for success in this method.
108   * The following actions are done:
109   * <ul>
110   * <li>Creation of all sub windows for InfoBox, InfoLog, Help and About.
111   * <li>Creation of the output Area.
112   * <li>
113   * <li>Adding the {@link org.vishia.gral.base.GralGraphicTimeOrder}
114   *   {@link org.vishia.gral.area9.GralArea9Window#writeOutputTextDirectly} which transfers
115   *   text lines stored in {@link org.vishia.gral.area9.GralArea9Window#outputTexts} to the output area.
116   * </ul>
117   * @param outputArea Two letter combination A1..C3 for horizontal and vertical area. 
118   *        A..C is left to right, 1..3 is top to bottom.
119   *        The first combination is the top left area for output, 
120   *        the second combination is the bottom right area. 
121   *        The output area can use more as one basic areas.
122   *        For example "A3C3" means that the output area uses the full bottom part of window.
123   *        For example "B2C3" means an area consist of 4 basic areas right bottom.  
124   */
125  void initGraphic(String outputArea);
126
127  
128  /**It is like {@link GralWindow_ifc#addMenuBarItemGThread(String, String, GralUserAction)}.
129   * @deprecated use {@link #getMenuBar()} and then {@link GralMenu#addMenuItem(String, String, GralUserAction)}
130   */
131  @Deprecated
132  void addMenuBarArea9ItemGThread(String nameWidg, String sMenuPath, GralUserAction action);
133
134  
135  /**Gets the menu bar for the window, see {@link org.vishia.gral.base.GralWindow#getMenuBar()}.
136   * @return The menu bar of the window.
137   */
138  GralMenu getMenuBar();
139  
140  /**Adds a Menu for file open and save only. All other menu items are not set because the order of menus. 
141   * @param openStandardDirectory
142   * @param actionFile
143   */
144  void setStandardMenusGThread(File openStandardDirectory, GralUserAction actionFile);
145  
146  /**Returns the outputArea, which was created by the graphic thread. 
147   */
148  GralPanelContent getOutputPanel();
149  
150  /**Sets the divisions of the frame. The frame is divide into 9 parts,
151   * where two horizontal and two vertical lines built them:
152   * <pre>
153   * +=======+===============+===========+
154   * |       |               |           | 
155   * +-------+---------------+-----------+ 
156   * |       |               |           | 
157   * |       |               |           | 
158   * +-------+---------------+-----------+ 
159   * |       |               |           | 
160   * |       |               |           | 
161   * +=======+===============+===========+
162   * </pre>
163   * 
164   * @param x1p percent from left for first vertical divide line.
165   * @param x2p percent from left for second vertical divide line.
166   * @param y1p percent from left for first horizontal divide line.
167   * @param y2p percent from left for first horizontal divide line.
168   */
169  void setFrameAreaBorders(int x1p, int x2p, int y1p, int y2p);
170  
171  
172  /**Sets a Panel into a defined area. See {@link #setFrameAreaBorders(int, int, int, int)}.
173   * It should be called only in the GUI-Thread.
174   * @param sArea Area identifcation, e.g. "B3C3" where alpha-char A..C is column, numeric char 1..3 is row.
175   *   If a range is given, the whole area of that areas is used. 
176   * @param component The component.
177   * @throws IndexOutOfBoundsException if the arguments are false or the area is occupied already.
178   */
179  void addFrameArea(String sArea, GralPanelContent component)
180  throws IndexOutOfBoundsException;
181  
182  
183  
184  /**Sets the minimal and maximal size.
185   * @throws IndexOutOfBoundsException if the arguments sArea are false.
186   */
187  void setMinMaxSizeArea(String sArea, int yMinUnit, int yMaxUnit, int xMinUnit, int xMaxUnit)
188  throws IndexOutOfBoundsException;
189  
190  
191  /**Sets a Panel into a defined area. See {@link #setFrameAreaBorders(int, int, int, int)}.
192   * It should be called only in the GUI-Thread.
193   * @param xArea 1 to 3 for left, middle, right
194   * @param yArea 1 to 3 for top, middle, bottom
195   * @param dxArea 1 to 3 for 1 field to 3 fields to right.
196   * @param dyArea 1 to 3 for 1 field to 3 field to bottom
197   * @param component The component.
198   * @throws IndexOutOfBoundsException if the arguments are false or the area is occupied already.
199   * @deprecated use {@link #addFrameArea(String, GralPanelContent)}.
200   */
201  @Deprecated
202  void addFrameArea(int xArea, int yArea, int dxArea, int dyArea, GralPanelContent component)
203  throws IndexOutOfBoundsException;
204  
205  
206  /**Returns the text box which is used as output box for common messages of the application.
207   * @return null if no output window is given.
208   */
209  GralTextBox getOutputBox();
210  
211  void setFullScreen(boolean full);
212
213  GralMng getGralMng();
214  
215  /**Returns the prepared action help which opens the help window.
216   * It should be used for the users call of {@link #addMenuBarArea9ItemGThread(String, String, GralUserAction) }
217   * to install the help menu.  */
218  GralUserAction getActionHelp();
219  
220  /**Returns the prepared action about which opens the help window.
221   * It should be used for the users call of {@link #addMenuBarArea9ItemGThread(String, String, GralUserAction) }
222   * to install the help menu.  */
223  GralUserAction getActionAbout();
224  
225  GralWindow_ifc mainWindow();
226  
227  MainCmd_ifc getMainCmd();
228
229
230  /**Set a path which is used as help url base path.
231   * @param path An absolute given path on a local file system, or html page in internet.
232   */
233  void setHelpBase(String path);
234  
235}