Package ej.mwt

Class 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.

    • Constructor Detail

      • Container

        public Container()
        Creates a container.
      • Container

        public 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:
        java.lang.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:
        java.lang.IllegalArgumentException - if the specified widget is already attached.
        java.lang.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:
        java.lang.IndexOutOfBoundsException - if the index is out of range (index < 0 || index >= getChildrenCount()).
        java.lang.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:
        java.lang.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:
        java.lang.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:
        java.lang.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);
         
        Layout aligned children.

        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​(ej.microui.display.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,
                                   ej.microui.display.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.