org.vishia.gral.area9

## Class GralArea9Window

- java.lang.Object
- - org.vishia.gral.area9.GralArea9Window

- All Implemented Interfaces:
    GralArea9_ifc, GralMngApplAdapter_ifc

      public class GralArea9Window
      extends java.lang.Object
      implements GralArea9_ifc

  This class presents a Window appearance with up to 9 areas as base for a user's application with several areas of the main window and some sub windows. The areas of the window can be used in several forms:

       +================================================================================+
       |                |                                                |              +
       |                |                                                |              +
       |                |                                                |              +
       |                |       central working area                     |   other      +
       |     any        |                                                |   list       +
       |     list       |                                                |              +
       |                |                                                |              +
       |                |                                                |              +
       |                +---------------------------------------------------------------+
       |                |                                                               +
       |                |      status or output area                                   +
       |                |                                                               +
       |                |                                                               +
       +================================================================================+

       +================================================================================+
       |                |                                                               +
       |                |                                                               +
       |                |                                                               +
       |                |       central working area                                    +
       |     any        |                                                               +
       |     list       |                                                               +
       |                |                                                               +
       |                |                                                               +
       |                |                                                               +
       |                |                                                               +
       |--------------------------------------------------------------------------------+
       |                       status line                                              +
       +================================================================================+

       +================================================================================+
       |                |                           |                                   +
       |                |     one                   |            other                  +
       |     any        |     panel                 |            panel                  +
       |     list       |                           |                                   +
       |                |                           |                                   +
       |                |                           |                                   +
       |----------------+---------------------------+-----------------------------------+
       |                                                                                +
       |            input area                                                          +
       |----------------+---------------------------------------------------------------+
       |                |                                                               +
       |   info         |      status or output area                                    +
       |   area         |                                                               +
       |                |                                                               +
       +================================================================================+

  or any other partitioning.
  The main window has a menu bar which has some default entries:
  The following sub windows are created:
  - `#infoHelp`: Window will be opened with key [F1] or menu help. initially call `setHelpBase(String)`, then call `setHelpUrl(String)` respectively set `GralWidget.setHtmlHelp(String)` for any widget.
  - `#infoBox`: Window will be opened via menu or on demand if anything should be shown. Fill it with infoBox. `GralInfoBox.setText(CharSequence)`, `GralInfoBox.setText(CharSequence, int)` or `GralInfoBox.append(CharSequence)`. The info box should be used for on demand. it will be overridden and reused if necessary later.
  - `#infoLog`: Window will be opened via menu or on demand if anything should be shown. Fill it with infoLog.`GralInfoBox.append(CharSequence)`.
  - `infoAbout`: Window will be opened with menu about. This box will be filled given with the content from `mainCmd`. `MainCmd.addAboutInfo(String)` from the given MainCmd instance for `GralArea9Window(MainCmd, GralWindow)`.

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `protected class` | `GralArea9Window.GralActionFileOpen` TODO actionFile in user space?

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `private GralUserAction` | `actionAbout`
    `protected GralUserAction` | `actionFile`
    `protected boolean` | `bSetStandardMenus` Set on call of `#setStandardMenus(File)` to add in in the graphic thread.
    `protected GralPanelContent[][]` | `componentFrameArea` All main components of the Display in each FrameArea.
    `protected java.io.File` | `currentDirectory` Current Directory for file choosing.
    `protected byte[][][]` | `dxyFrameArea` spread of each frame area in x direction.
    `private GralInfoBox` | `infoAbout`
    `(package private) GralGraphicTimeOrder` | `initGraphic`
    `MainCmd` | `mainCmd`
    `private GralUserAction` | `mouseAction`
    `protected java.lang.String` | `outputArea` Area settings for output.
    `GralTextBox` | `outputBox` A Text box which is used for common output.
    `protected GralPanelContent` | `outputPanel`
    `protected java.util.Queue<java.lang.String>` | `outputTexts`
    `protected float` | `pixelPerXpercent` Number of pixels per percent unit of size, set if `validateFrameAreas()` was called.
    `protected float` | `pixelPerYpercent` Number of pixels per percent unit of size, set if `validateFrameAreas()` was called.
    `private GralUserAction` | `resizeAction`
    `protected GralTextBox_ifc` | `textAreaOutput` If it is set, the writeInfo is redirected to this.
    `static int` | `version` Version and History 2015-10-26 Hartmut chg Help in now an integral part of the `GralMng`, but invoked here.
    `protected GralWindow` | `window`
    `private GralGraphicTimeOrder` | `writeOutputTextDirectly`
    `private short[]` | `xMaxGralSize` requested maximal size of each window area in GralPos units.
    `private short[]` | `xMinGralSize` requested minimal size of each window area in GralPos units.
    `protected byte[]` | `xpFrameArea` Position of the FrameArea borders in percent
    `private int[]` | `xPixArea` Calculated borders of areas
    `protected java.lang.StringBuffer` | `XXXsbWriteInfo` The id of the thread, which created the display.
    `private short[]` | `yMaxGralSize` requested maximal size of each window area in GralPos units.
    `private short[]` | `yMinGralSize` requested minimal size of each window area in GralPos units.
    `protected byte[]` | `ypFrameArea` Position of the FrameArea borders in percent
    `private int[]` | `yPixArea` Calculated borders of areas

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `GralArea9Window(MainCmd mainCmd, GralWindow window)`

  - ### Method Summary

    All Methods Instance Methods Concrete Methods Deprecated Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `addFrameArea(int xArea, int yArea, int dxArea, int dyArea, GralPanelContent component)` Sets a Component into a defined area.
    `void` | `addFrameArea(java.lang.String sArea, GralPanelContent component)` Sets a Panel into a defined area.
    `void` | `addMenuBarArea9ItemGThread(java.lang.String name, java.lang.String sMenuPath, GralUserAction action)` Deprecated.
    `protected GralPanelContent` | `addOutputFrameArea(java.lang.String area)`
    `private void` | `calcPixSize(int[] zPixArea, byte[] zpFrameArea, short[] zMinGralSize, short[] zMaxGralSize, int zPixUnit, int zSize, float pixelPerZpercent)`
    `protected GralRectangle` | `convertArea(java.lang.String area)` Converts a string given are designation to indices.
    `GralUserAction` | `getActionAbout()` Returns the standard behavior: opens the help window with its constant text.
    `GralUserAction` | `getActionHelp()` Returns the standard behavior: opens the about window with its constant text.
    `GralMng` | `getGralMng()` Gets the graphical frame.
    `MainCmd_ifc` | `getMainCmd()`
    `GralMenu` | `getMenuBar()` Gets the menu bar for the window, see `GralWindow.getMenuBar()`.
    `GralTextBox` | `getOutputBox()` Returns the text box which is used as output box for common messages of the application.
    `GralPanelContent` | `getOutputPanel()` Returns the outputArea, which was created by the graphic thread.
    `void` | `initGraphic(java.lang.String sOutputArea)` Initializes the output area, can be called after construction immediately.
    `GralWindow_ifc` | `mainWindow()`
    `private void` | `setBoundsForFrameArea(int idxArea, int idyArea)` Sets the bounds for the component, which is localized at the given area.
    `void` | `setFrameAreaBorders(int x1p, int x2p, int y1p, int y2p)` Sets the divisions of the frame.
    `void` | `setFullScreen(boolean full)`
    `void` | `setHelpBase(java.lang.String path)` Set a path which is used as help url base path.
    `void` | `setHelpUrl(java.lang.String url)` For context sensitive help, it assigns an URL to the widget which has the focus gained.
    `void` | `setMinMaxSizeArea(java.lang.String sArea, int yMinUnit, int yMaxUnit, int xMinUnit, int xMaxUnit)` Sets the minimal and maximal size.
    `void` | `setStandardMenus(java.io.File openStandardDirectory, GralUserAction actionFile)`
    `void` | `setStandardMenusGThread(java.io.File openStandardDirectory, GralUserAction actionFile)` Adds a Menu for file open and save only.
    `protected void` | `validateFrameAreas()` Set the bounds of all areas.
    `protected void` | `writeDirectly(java.lang.String sInfo, short kind)` Overloads MainCmd.writeDirectly.
    `void` | `XXXsetOutputArea(java.lang.String area)` Sets the output window to a defined area. .

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### version

          public static final int version

      Version and History
      - 2015-10-26 Hartmut chg Help in now an integral part of the `GralMng`, but invoked here. This class in not change in functinality.
      - 2014-02-24 Hartmut new `setHelpBase(String)` used in `setHelpUrl(String)`.
      - 2012-05-17 Hartmut new: `setMinMaxSizeArea(String, int, int, int, int)`: The size can be given with gral units, as min, max or absolute (min, max are equal). The size of a area border can be changed on runtime.
      - 2012-04-22 Hartmut new: `setFullScreen(boolean)`
      - 2011-12-26 Hartmut chg: The help window is a html info box now. New method `setHelpUrl(String)` supports context sensitive help.
      - 2011-11-12 Hartmut new: The SubWindow for Help, About, InfoBox and InfoLog are created here (InfoLog: TODO). This windows can be opened in demand.
      - 2011-11-12 Hartmut chg: All menu items should be prepared in the users application now. The items for help and about are supported with actions by `getActionAbout()` and `getActionAbout()`. This actions are the standard behavior and opens the sub-windows only. But the user can install a more complex functionality for example writing a context sensitive help.
      - 2011-11-12 Harmut chg `initGraphic` was the old initOutputArea, but it does more as only the output area. Now creation of all necessities of Graphic in this functionality.
      Copyright/Copyleft: For this source the LGPL Lesser General Public License, published by the Free Software Foundation is valid. It means:
      1. You can use this source without any restriction for any desired purpose.
      2. You can redistribute copies of this source to everybody.
      3. Every user of this source, also the user of redistribute copies with or without payment, must accept this license for further using.
      4. But the LPGL ist not appropriate for a whole software product, if this source is only a part of them. It means, the user must publish this part of source, but don't need to publish the whole source of the own product.
      5. You can study and modify (improve) this source for own using or for redistribution, but you have to license the modified sources likewise under this LGPL Lesser General Public License. You mustn't delete this Copyright/Copyleft inscription in this source file.
      If you are indent to use this sources without publishing its usage, you can get a second license subscribing a special contract with the author.
      See Also:
        Constant Field Values

    - #### mainCmd

          public final MainCmd mainCmd

    - #### window

          protected final GralWindow window

    - #### outputArea

          protected java.lang.String outputArea

      Area settings for output.

    - #### outputPanel

          protected GralPanelContent outputPanel

    - #### outputBox

          public GralTextBox outputBox

      A Text box which is used for common output. It may be edit-able. This output box is created initially. It can be used to show error messages while starting the application if other GUI-elements are not yet present. It can be used generally to show errors, infos and logs adequate to a console output.

    - #### infoAbout

          private GralInfoBox infoAbout

    - #### currentDirectory

          protected java.io.File currentDirectory

      Current Directory for file choosing.

    - #### actionFile

          protected GralUserAction actionFile

    - #### bSetStandardMenus

          protected boolean bSetStandardMenus

      Set on call of `#setStandardMenus(File)` to add in in the graphic thread.

    - #### outputTexts

          protected java.util.Queue<java.lang.String> outputTexts

    - #### componentFrameArea

          protected GralPanelContent[][] componentFrameArea

      All main components of the Display in each FrameArea.

    - #### xpFrameArea

          protected byte[] xpFrameArea

      Position of the FrameArea borders in percent. [0] is always 0, [1] and [2] are the given borders, [3] is always 100. It is because lower and higher bound should be accessed always without tests. Use area +1, because it is a Off-by-one problem

    - #### ypFrameArea

          protected byte[] ypFrameArea

      Position of the FrameArea borders in percent. [0] is always 0, [1] and [2] are the given borders, [3] is always 100. It is because lower and higher bound should be accessed always without tests. Use area +1, because it is a Off-by-one problem

    - #### dxyFrameArea

          protected byte[][][] dxyFrameArea

      spread of each frame area in x direction. It it is -1, than the area is occupied by another area. If it is 0, the area is free. 1..3 are the number of areas in horizontal direction.

    - #### xMinGralSize

          private final short[] xMinGralSize

      requested minimal size of each window area in GralPos units. If the minimal value is 0, the size is calculated from percent always. If the minimal value of percent calculation is lesser than this value, this value is used. Note that a given minimal value of all areas cannot required if the window's size is lesser. Then the middle area will

    - #### yMinGralSize

          private final short[] yMinGralSize

      requested minimal size of each window area in GralPos units. If the minimal value is 0, the size is calculated from percent always. If the minimal value of percent calculation is lesser than this value, this value is used. Note that a given minimal value of all areas cannot required if the window's size is lesser. Then the middle area will

    - #### xMaxGralSize

          private final short[] xMaxGralSize

      requested maximal size of each window area in GralPos units. If the maximal value is greater than the size calculated from percent always, the percent value is used. Note that a given maximal value of all areas cannot regarded if the window's size is greater. Then the middle area will be presented

    - #### yMaxGralSize

          private final short[] yMaxGralSize

      requested maximal size of each window area in GralPos units. If the maximal value is greater than the size calculated from percent always, the percent value is used. Note that a given maximal value of all areas cannot regarded if the window's size is greater. Then the middle area will be presented

    - #### xPixArea

          private final int[] xPixArea

      Calculated borders of areas. [0] is always 0, [1] and [2] are the given borders, [3] is always 100. It is because lower and higher bound should be accessed always without tests. Use area +1, because it is a Off-by-one problem

    - #### yPixArea

          private final int[] yPixArea

      Calculated borders of areas. [0] is always 0, [1] and [2] are the given borders, [3] is always 100. It is because lower and higher bound should be accessed always without tests. Use area +1, because it is a Off-by-one problem

    - #### pixelPerXpercent

          protected float pixelPerXpercent

      Number of pixels per percent unit of size, set if `validateFrameAreas()` was called.

    - #### pixelPerYpercent

          protected float pixelPerYpercent

      Number of pixels per percent unit of size, set if `validateFrameAreas()` was called.

    - #### XXXsbWriteInfo

          protected final java.lang.StringBuffer XXXsbWriteInfo

      The id of the thread, which created the display. It is to check whether gui-commands should be queued or not.

    - #### textAreaOutput

          protected GralTextBox_ifc textAreaOutput

      If it is set, the writeInfo is redirected to this.

    - #### initGraphic

          GralGraphicTimeOrder initGraphic

    - #### writeOutputTextDirectly

          private final GralGraphicTimeOrder writeOutputTextDirectly

    - #### mouseAction

          private final GralUserAction mouseAction

    - #### resizeAction

          private final GralUserAction resizeAction

    - #### actionAbout

          private final GralUserAction actionAbout

  - ### Constructor Detail

    - #### GralArea9Window

          public GralArea9Window(MainCmd mainCmd,
                                 GralWindow window)

      Parameters:
        `mainCmd` - Aggregation to a MainCmd implemenation.
        `guiDevice` - The window manager
        `window` - The window itself. It doesn't be the primary window but a sub window too.

  - ### Method Detail

    - #### XXXsetOutputArea

          public void XXXsetOutputArea(java.lang.String area)

      Sets the output window to a defined area. . Adds the edit-menu too.
      Parameters:
        `xArea` - 1 to 3 for left, middle, right, See `setFrameAreaBorders(int, int, int, int)`
        `yArea` - 1 to 3 for top, middle, bottom
        `dxArea` - 1 to 3 for 1 field to 3 fields to right.
        `dyArea` - 1 to 3 for 1 field to 3 field to bottom

    - #### initGraphic

          public void initGraphic(java.lang.String sOutputArea)

      Initializes the output area, can be called after construction immediately.
      Specified by:
        `initGraphic` in interface `GralArea9_ifc`
      Parameters:
        `sOutputArea` - String for example "A3C3". The letter character is the column. The digit is the row. It is fromTo. The example means the whole bottom area.

    - #### getMainCmd

          public MainCmd_ifc getMainCmd()

      Specified by:
        `getMainCmd` in interface `GralArea9_ifc`

    - #### mainWindow

          public GralWindow_ifc mainWindow()

      Specified by:
        `mainWindow` in interface `GralArea9_ifc`

    - #### getOutputPanel

          public GralPanelContent getOutputPanel()

      Description copied from interface: `GralArea9_ifc`
      Returns the outputArea, which was created by the graphic thread.
      Specified by:
        `getOutputPanel` in interface `GralArea9_ifc`

    - #### getOutputBox

          public GralTextBox getOutputBox()

      Description copied from interface: `GralArea9_ifc`
      Returns the text box which is used as output box for common messages of the application.
      Specified by:
        `getOutputBox` in interface `GralArea9_ifc`
      Returns:
        null if no output window is given.

    - #### setFrameAreaBorders

          public void setFrameAreaBorders(int x1p,
                                          int x2p,
                                          int y1p,
                                          int y2p)

      Sets the divisions of the frame. The frame is divide into 9 parts, where two horizontal and two vertical lines built them:

           +=======+===============+===========+
           |       |               |           |
           +-------+---------------+-----------+
           |       |               |           |
           |       |               |           |
           +-------+---------------+-----------+
           |       |               |           |
           |       |               |           |
           +=======+===============+===========+

      Specified by:
        `setFrameAreaBorders` in interface `GralArea9_ifc`
      Parameters:
        `x1p` - percent from left for first vertical divide line.
        `x2p` - percent from left for second vertical divide line.
        `y1p` - percent from left for first horizontal divide line.
        `y2p` - percent from left for first horizontal divide line.

    - #### addFrameArea

          public void addFrameArea(java.lang.String sArea,
                                   GralPanelContent component)
                            throws java.lang.IndexOutOfBoundsException

      Description copied from interface: `GralArea9_ifc`
      Sets a Panel into a defined area. See `GralArea9_ifc.setFrameAreaBorders(int, int, int, int)`. It should be called only in the GUI-Thread.
      Specified by:
        `addFrameArea` in interface `GralArea9_ifc`
      Parameters:
        `sArea` - Area identifcation, e.g. "B3C3" where alpha-char A..C is column, numeric char 1..3 is row. If a range is given, the whole area of that areas is used.
        `component` - The component.
      Throws:
        `java.lang.IndexOutOfBoundsException` - if the arguments are false or the area is occupied already.

    - #### addFrameArea

          public final void addFrameArea(int xArea,
                                         int yArea,
                                         int dxArea,
                                         int dyArea,
                                         GralPanelContent component)
                                  throws java.lang.IndexOutOfBoundsException

      Sets a Component into a defined area. See `setFrameAreaBorders(int, int, int, int)`. It should be called only in the GUI-Thread.
      Specified by:
        `addFrameArea` in interface `GralArea9_ifc`
      Parameters:
        `xArea` - 1 to 3 for left, middle, right
        `yArea` - 1 to 3 for top, middle, bottom
        `dxArea` - 1 to 3 for 1 field to 3 fields to right.
        `dyArea` - 1 to 3 for 1 field to 3 field to bottom
        `component` - The component.
      Throws:
        `java.lang.IndexOutOfBoundsException` - if the arguments are false or the area is occupied already.

    - #### setMinMaxSizeArea

          public void setMinMaxSizeArea(java.lang.String sArea,
                                        int yMinUnit,
                                        int yMaxUnit,
                                        int xMinUnit,
                                        int xMaxUnit)
                                 throws java.lang.IndexOutOfBoundsException

      Description copied from interface: `GralArea9_ifc`
      Sets the minimal and maximal size.
      Specified by:
        `setMinMaxSizeArea` in interface `GralArea9_ifc`
      Throws:
        `java.lang.IndexOutOfBoundsException` - if the arguments sArea are false.

    - #### validateFrameAreas

          protected void validateFrameAreas()

      Set the bounds of all areas. Calls `GralWindow.getPixelPositionSize()` to get the size of working area of the whole window

    - #### calcPixSize

          private void calcPixSize(int[] zPixArea,
                                   byte[] zpFrameArea,
                                   short[] zMinGralSize,
                                   short[] zMaxGralSize,
                                   int zPixUnit,
                                   int zSize,
                                   float pixelPerZpercent)

    - #### setBoundsForFrameArea

          private void setBoundsForFrameArea(int idxArea,
                                             int idyArea)

      Sets the bounds for the component, which is localized at the given area.
      Parameters:
        `idxArea` -
        `idyArea` -

    - #### convertArea

          protected GralRectangle convertArea(java.lang.String area)

      Converts a string given are designation to indices.
      Parameters:
        `area` - A, B , C for column, 1, 2, 3 for row.
      Returns:

    - #### setStandardMenus

          public final void setStandardMenus(java.io.File openStandardDirectory,
                                             GralUserAction actionFile)

    - #### setStandardMenusGThread

          public final void setStandardMenusGThread(java.io.File openStandardDirectory,
                                                    GralUserAction actionFile)

      Description copied from interface: `GralArea9_ifc`
      Adds a Menu for file open and save only. All other menu items are not set because the order of menus.
      Specified by:
        `setStandardMenusGThread` in interface `GralArea9_ifc`

    - #### addMenuBarArea9ItemGThread

          @Deprecated
          public void addMenuBarArea9ItemGThread(java.lang.String name,
                                                              java.lang.String sMenuPath,
                                                              GralUserAction action)

      Deprecated.
      Description copied from interface: `GralArea9_ifc`
      It is like `GralWindow_ifc.addMenuBarItemGThread(String, String, GralUserAction)`.
      Specified by:
        `addMenuBarArea9ItemGThread` in interface `GralArea9_ifc`

    - #### getMenuBar

          public GralMenu getMenuBar()

      Description copied from interface: `GralArea9_ifc`
      Gets the menu bar for the window, see `GralWindow.getMenuBar()`.
      Specified by:
        `getMenuBar` in interface `GralArea9_ifc`
      Returns:
        The menu bar of the window.

    - #### setFullScreen

          public void setFullScreen(boolean full)

      Specified by:
        `setFullScreen` in interface `GralArea9_ifc`

    - #### addOutputFrameArea

          protected GralPanelContent addOutputFrameArea(java.lang.String area)

    - #### writeDirectly

          protected void writeDirectly(java.lang.String sInfo,
                                       short kind)

      Overloads MainCmd.writeDirectly. This method may be overloaded by the user if it has a better way to show infos.

    - #### setHelpBase

          public void setHelpBase(java.lang.String path)

      Description copied from interface: `GralArea9_ifc`
      Set a path which is used as help url base path.
      Specified by:
        `setHelpBase` in interface `GralArea9_ifc`
      Parameters:
        `path` - An absolute given path on a local file system, or html page in internet.

    - #### setHelpUrl

          public void setHelpUrl(java.lang.String url)

      Description copied from interface: `GralMngApplAdapter_ifc`
      For context sensitive help, it assigns an URL to the widget which has the focus gained.
      Specified by:
        `setHelpUrl` in interface `GralMngApplAdapter_ifc`
      Parameters:
        `url` - A "file#html.label" or "localdir/file.html#label" which describes the html help url in an local context. The origin of the url is given with a global context of the help window. See `setHelpBase(String)` deprecated: It is often an absolute path. may be a relative path?? deprecated: If it starts with "+", a base path is used as prefix.

    - #### getGralMng

          public GralMng getGralMng()

      Gets the graphical frame.
      Specified by:
        `getGralMng` in interface `GralArea9_ifc`

    - #### getActionAbout

          public GralUserAction getActionAbout()

      Returns the standard behavior: opens the help window with its constant text.
      Specified by:
        `getActionAbout` in interface `GralArea9_ifc`
      See Also:
        `GralArea9_ifc.getActionAbout()`

    - #### getActionHelp

          public GralUserAction getActionHelp()

      Returns the standard behavior: opens the about window with its constant text.
      Specified by:
        `getActionHelp` in interface `GralArea9_ifc`
      See Also:
        `GralArea9_ifc.getActionAbout()`