    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}