Package ej.mwt

## Class Container

- java.lang.Object
- - ej.mwt.Widget
  - - ej.mwt.Container

-     public abstract class Container
      extends Widget

  A container is a widget that can contain other `Widget` instances, following the composite pattern.

  The children are stored in a list. The order of the list defines the front-to-back stacking order of the widgets within the container. The first widget in the list is at the back of the stacking order.

  A widget cannot be added two times in a hierarchy.

- - ### Field Summary

    - ### Fields inherited from class ej.mwt.Widget

      `NO_CONSTRAINT`

  - ### Constructor Summary

    Constructors
    Modifier | Constructor | Description
    --- | --- | ---
    `protected` | `Container()` | Creates a container.
    `protected` | `Container​(boolean enabled)` | Creates a container specifying if its enabled or not.

  - ### Method Summary

    All Methods Instance Methods Abstract Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `protected void` | `addChild​(Widget child)` | Adds the specified widget to the end of the list of children of this container.
    `protected void` | `changeChildIndex​(Widget child, int index)` | Changes the position of the specified widget in the list of children of this container.
    `protected void` | `computeChildOptimalSize​(Widget child, int availableWidth, int availableHeight)` | Computes the optimal size of a child of this container.
    `Widget` | `getChild​(int index)` | Gets the widget at the specified index in this container.
    `int` | `getChildIndex​(Widget child)` | Gets the index of the specified widget in the list of children of this container.
    `protected Widget[]` | `getChildren()` | Gets the list of children in this container.
    `int` | `getChildrenCount()` | Gets the number of children in this container.
    `Rectangle` | `getContentBounds()` | Gets the content bounds of this widget (the bounds minus the outlines).
    `int` | `getContentHeight()` | Gets the content height of this container.
    `int` | `getContentWidth()` | Gets the content width of this container.
    `int` | `getContentX()` | Gets the content x of this container.
    `int` | `getContentY()` | Gets the content y of this container.
    `Widget` | `getWidgetAt​(int x, int y)` | Returns the child widget that is at the specified position.
    `protected void` | `insertChild​(Widget child, int index)` | Inserts the specified widget at the specified index in the list of children of this container.
    `protected void` | `layOutAlignedChild​(Widget child, int horizontalPosition, int verticalPosition, int horizontalAlignment, int verticalAlignment, int contentWidth, int contentHeight)` | Lays out a child of this container in a similar fashion to CSS absolute position.
    `protected void` | `layOutChild​(Widget child, int x, int y, int width, int height)` | Lays out a child of this container.
    `protected abstract void` | `layOutChildren​(int contentWidth, int contentHeight)` | Lays out the children of this container.
    `protected void` | `removeAllChildren()` | Removes all the children of this container.
    `protected void` | `removeChild​(Widget child)` | Removes the specified widget from the list of children of this container.
    `protected void` | `renderChild​(Widget child, GraphicsContext g)` | Renders a child of this container.
    `protected void` | `renderContent​(GraphicsContext g, int contentWidth, int contentHeight)` | Renders the content of the widget without the border, margin and padding specified in the style.
    `protected void` | `replaceChild​(int index, Widget child)` | Replaces the child at the specified index in the list of children of this container by the specified widget.
    `protected void` | `setHiddenChild​(Widget child)` | Sets a child as hidden.
    `protected void` | `setHiddenChildren()` | Automatically declares children as hidden when this container is hidden.
    `protected void` | `setShownChild​(Widget child)` | Sets a child as shown.
    `protected void` | `setShownChildren()` | Automatically declares children as shown when this container is shown.
    `void` | `updateStyle()` | Updates the style of this widget.

    - ### Methods inherited from class ej.mwt.Widget

      `addClassSelector, computeContentOptimalSize, contains, containsWidget, getAbsoluteX, getAbsoluteY, getDesktop, getHeight, getParent, getStyle, getWidth, getX, getY, handleEvent, hasClassSelector, isAttached, isEnabled, isInState, isShown, isTransparent, onAttached, onDetached, onHidden, onLaidOut, onShown, removeAllClassSelectors, removeClassSelector, render, requestLayOut, requestRender, requestRender, setClassSelectors, setEnabled, setPosition, setStyle`

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

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

- - ### Constructor Detail

    - #### Container

          protected Container()

      Creates a container.

    - #### Container

          protected Container​(boolean enabled)

      Creates a container specifying if its enabled or not.
      Parameters:
        `enabled` - `true` if this container is to be enabled, `false` otherwise.

  - ### Method Detail

    - #### addChild

          protected void addChild​(Widget child)

      Adds the specified widget to the end of the list of children of this container.

      The container needs to be laid out again.

      Should be called in the display thread to avoid concurrency issues.

      Parameters:
        `child` - the widget to add.
      Throws:
        `IllegalArgumentException` - if the specified widget is already attached.
      See Also:
        `Widget.requestLayOut()`, `Widget.isAttached()`

    - #### removeChild

          protected void removeChild​(Widget child)

      Removes the specified widget from the list of children of this container.

      The container needs to be laid out again.

      If the widget is not in the list of children of the container, nothing is done.

      Should be called in the display thread to avoid concurrency issues.

      Parameters:
        `child` - the widget to remove.
      See Also:
        `Widget.requestLayOut()`

    - #### insertChild

          protected void insertChild​(Widget child,
                                     int index)

      Inserts the specified widget at the specified index in the list of children of this container.

      The container needs to be laid out again.

      Should be called in the display thread to avoid concurrency issues.

      Parameters:
        `child` - the widget to add.
        `index` - the index at which the widget should be inserted.
      Throws:
        `IllegalArgumentException` - if the specified widget is already attached.
        `IndexOutOfBoundsException` - if the index is out of range (`index < 0 || index > getChildrenCount()`).
      See Also:
        `Widget.requestLayOut()`, `Widget.isAttached()`

    - #### replaceChild

          protected void replaceChild​(int index,
                                      Widget child)

      Replaces the child at the specified index in the list of children of this container by the specified widget.

      If the specified widget is already the child at the specified index of the list of children, nothing is done.

      The container needs to be laid out again.

      Should be called in the display thread to avoid concurrency issues.

      Parameters:
        `index` - the index of the child to replace.
        `child` - the widget to add.
      Throws:
        `IndexOutOfBoundsException` - if the index is out of range (`index < 0 || index >= getChildrenCount()`).
        `IllegalArgumentException` - if the specified widget is already attached, unless it is already the child at the specified index.
      See Also:
        `Widget.requestLayOut()`, `Widget.isAttached()`

    - #### removeAllChildren

          protected void removeAllChildren()

      Removes all the children of this container.

      The container needs to be laid out again.

      Should be called in the display thread to avoid concurrency issues.

      See Also:
        `Widget.requestLayOut()`

    - #### changeChildIndex

          protected void changeChildIndex​(Widget child,
                                          int index)

      Changes the position of the specified widget in the list of children of this container.
      Parameters:
        `child` - the child to move.
        `index` - the index at which the widget should be moved.
      Throws:
        `IllegalArgumentException` - if the given widget is not a child of this container.

    - #### setShownChildren

          protected void setShownChildren()

      Automatically declares children as shown when this container is shown.

      A container may decide to keep some children as hidden by subclassing this method. It is then responsible of drawing only its shown children in `renderContent(GraphicsContext, int, int)`.

      See Also:
        `Widget.onShown()`

    - #### setHiddenChildren

          protected void setHiddenChildren()

      Automatically declares children as hidden when this container is hidden.

      It is not necessary to override this method, except for optimization. If this method is overridden, it should always make sure that every child is hidden before returning.

      See Also:
        `Widget.onHidden()`

    - #### setShownChild

          protected void setShownChild​(Widget child)

      Sets a child as shown.

      An assertion checks that the given widget is actually a child of this container.

      Parameters:
        `child` - the child to notify.
      See Also:
        `Widget.onShown()`

    - #### setHiddenChild

          protected void setHiddenChild​(Widget child)

      Sets a child as hidden.

      An assertion checks that the given widget is actually a child of this container.

      Parameters:
        `child` - the child to notify.
      See Also:
        `Widget.onHidden()`

    - #### getWidgetAt

          @Nullable
          public Widget getWidgetAt​(int x,
                                    int y)

      Returns the child widget that is at the specified position.

      If `Widget.contains(int, int)` is `false` for this container, `null` is returned. Otherwise, if there is a child for which `Widget.contains(int, int)` returns `true` then the result of invoking `Widget.getWidgetAt(int, int)` on that widget is returned. Otherwise this container is returned.

      The position is relative to the position of this container's parent.

      Overrides:
        `getWidgetAt` in class `Widget`
      Parameters:
        `x` - x coordinate
        `y` - y coordinate
      Returns:
        the child at the position, `null` if no child is found in this container hierarchy.

    - #### getChild

          public Widget getChild​(int index)

      Gets the widget at the specified index in this container.
      Parameters:
        `index` - the index of the widget to return.
      Returns:
        the widget at the specified index in this container.
      Throws:
        `IndexOutOfBoundsException` - if the index is out of range (`index < 0 || index >= getChildrenCount()`).

    - #### getChildIndex

          public int getChildIndex​(Widget child)

      Gets the index of the specified widget in the list of children of this container.
      Parameters:
        `child` - the child.
      Returns:
        the index of the given child.
      Throws:
        `IllegalArgumentException` - if the specified widget is not a child of this container.

    - #### getChildren

          protected Widget[] getChildren()

      Gets the list of children in this container.

      Beware, the returned array is the field, it should not be modified.

      Returns:
        the list of children.

    - #### getChildrenCount

          public int getChildrenCount()

      Gets the number of children in this container.
      Returns:
        the number of children.

    - #### computeChildOptimalSize

          protected void computeChildOptimalSize​(Widget child,
                                                 int availableWidth,
                                                 int availableHeight)

      Computes the optimal size of a child of this container.

      An assertion checks that the given widget is actually a child of this container.

      Parameters:
        `child` - the child.
        `availableWidth` - the width available for this child or `Widget.NO_CONSTRAINT`.
        `availableHeight` - the height available for this child or `Widget.NO_CONSTRAINT`.
      See Also:
        `Desktop.requestLayOut()`, `Widget.requestLayOut()`

    - #### layOutChildren

          protected abstract void layOutChildren​(int contentWidth,
                                                 int contentHeight)

      Lays out the children of this container.

      The given size is the size of this container minus the border, margin and padding specified in the style.

      When this method returns the children of this container have been lay out using `layOutChild(Widget, int, int, int, int)`.

      Parameters:
        `contentWidth` - the width available for the content.
        `contentHeight` - the height available for the content.

    - #### layOutChild

          protected void layOutChild​(Widget child,
                                     int x,
                                     int y,
                                     int width,
                                     int height)

      Lays out a child of this container.

      The bounds of a widget can only be set by its parent during the lay out.

      An assertion checks that the given widget is actually a child of this container.

      Parameters:
        `child` - the child to set the bounds to.
        `x` - the x coordinate.
        `y` - the y coordinate.
        `width` - the width.
        `height` - the height.
      See Also:
        `Desktop.requestLayOut()`, `Widget.requestLayOut()`

    - #### layOutAlignedChild

          protected void layOutAlignedChild​(Widget child,
                                            int horizontalPosition,
                                            int verticalPosition,
                                            int horizontalAlignment,
                                            int verticalAlignment,
                                            int contentWidth,
                                            int contentHeight)

      Lays out a child of this container in a similar fashion to CSS absolute position.

      The child is positioned relatively to this container using given alignment with no size constraint.

      Examples:

           layOutAlignedChild(child1, left, top, Alignment.LEFT, Alignment.TOP, contentWidth, contentHeight);
           layOutAlignedChild(child2, 0, top, Alignment.HCENTER, Alignment.TOP, contentWidth, contentHeight);
           layOutAlignedChild(child3, right, top, Alignment.RIGHT, Alignment.TOP, contentWidth, contentHeight);
           layOutAlignedChild(child4, left, 0, Alignment.LEFT, Alignment.VCENTER, contentWidth, contentHeight);
           layOutAlignedChild(child5, 0, 0, Alignment.HCENTER, Alignment.VCENTER, contentWidth, contentHeight);
           layOutAlignedChild(child6, right, 0, Alignment.RIGHT, Alignment.VCENTER, contentWidth, contentHeight);
           layOutAlignedChild(child7, left, bottom, Alignment.LEFT, Alignment.BOTTOM, contentWidth, contentHeight);
           layOutAlignedChild(child8, 0, bottom, Alignment.HCENTER, Alignment.BOTTOM, contentWidth, contentHeight);
           layOutAlignedChild(child9, right, bottom, Alignment.RIGHT, Alignment.BOTTOM, contentWidth, contentHeight);

      An assertion checks that the given widget is actually a child of this container.

      Parameters:
        `child` - the child to set the bounds to.
        `horizontalPosition` - the right position if `horizontalAlignment` is `Alignment.RIGHT`, the left position if `horizontalAlignment` is `Alignment.LEFT`, ignored otherwise.
        `verticalPosition` - the top position if `verticalAlignment` is `Alignment.TOP`, the bottom position if `verticalAlignment` is `Alignment.BOTTOM`, ignored otherwise.
        `horizontalAlignment` - the horizontal alignment.
        `verticalAlignment` - the vertical alignment.
        `contentWidth` - this container content width.
        `contentHeight` - this container content height.
      See Also:
        `Desktop.requestLayOut()`, `Widget.requestLayOut()`, `Alignment`

    - #### getContentX

          public int getContentX()

      Gets the content x of this container. That means the sum of the different outlines on the left.

      The content bounds of a container are computed when the bounds of the container are set. (Otherwise, the content bounds will be zeros.)

      Returns:
        the content x.

    - #### getContentY

          public int getContentY()

      Gets the content y of this container. That means the sum of the different outlines on the top.

      The content bounds of a container are computed when the bounds of the container are set. (Otherwise, the content bounds will be zeros.)

      Returns:
        the content y.

    - #### getContentWidth

          public int getContentWidth()

      Gets the content width of this container. That means the width minus the sum of the different outlines horizontally (left and right).

      The content bounds of a container are computed when the bounds of the container are set. (Otherwise, the content bounds will be zeros.)

      Returns:
        the content width.

    - #### getContentHeight

          public int getContentHeight()

      Gets the content height of this container. That means the height minus the sum of the different outlines vertically (top and bottom).

      The content bounds of a container are computed when the bounds of the container are set. (Otherwise, the content bounds will be zeros.)

      Returns:
        the content height.

    - #### renderContent

          protected void renderContent​(GraphicsContext g,
                                       int contentWidth,
                                       int contentHeight)

      Renders the content of the widget without the border, margin and padding specified in the style.

      The given graphics context is translated and clipped according to the given bounds (the border, margin and padding are applied on this graphics context before).

      Renders the children of this container.

      Specified by:
        `renderContent` in class `Widget`
      Parameters:
        `g` - the graphics context where to render the content of the widget.
        `contentWidth` - the width of the content area.
        `contentHeight` - the height of the content area.

    - #### renderChild

          protected void renderChild​(Widget child,
                                     GraphicsContext g)

      Renders a child of this container.

      The given graphics context is translated and clipped to the parent content area. The child is then responsible of translating to its location and clipping to its size.

      If the child is not shown, nothing is done.

      An assertion checks that the given widget is actually a child of this container.

      Parameters:
        `child` - the child to render.
        `g` - the graphics context where to render the content of the child.

    - #### updateStyle

          public void updateStyle()

      Updates the style of this widget.

      If the widget is not in a desktop, nothing is done.

      The style of each child of this container is also updated.

      Overrides:
        `updateStyle` in class `Widget`

    - #### getContentBounds

          public Rectangle getContentBounds()

      Description copied from class: `Widget`
      Gets the content bounds of this widget (the bounds minus the outlines).
      Overrides:
        `getContentBounds` in class `Widget`
      Returns:
        the content bounds of this widget.