source/modules/juce_gui_basics/layout/juce_FlexItem.h

   1 /*
   2   ==============================================================================
   3
   4    This file is part of the JUCE library.
   5    Copyright (c) 2022 - Raw Material Software Limited
   6
   7    JUCE is an open source library subject to commercial or open-source
   8    licensing.
   9
  10    By using JUCE, you agree to the terms of both the JUCE 7 End-User License
  11    Agreement and JUCE Privacy Policy.
  12
  13    End User License Agreement: www.juce.com/juce-7-licence
  14    Privacy Policy: www.juce.com/juce-privacy-policy
  15
  16    Or: You may also use this code under the terms of the GPL v3 (see
  17    www.gnu.org/licenses).
  18
  19    JUCE IS PROVIDED "AS IS" WITHOUT ANY WARRANTY, AND ALL WARRANTIES, WHETHER
  20    EXPRESSED OR IMPLIED, INCLUDING MERCHANTABILITY AND FITNESS FOR PURPOSE, ARE
  21    DISCLAIMED.
  22
  23   ==============================================================================
  24 */
  25
  26 namespace juce
  27 {
  28
  29 /**
  30     Describes the properties of an item inside a FlexBox container.
  31
  32     @see FlexBox
  33
  34     @tags{GUI}
  35 */
  36 class JUCE_API  FlexItem  final
  37 {
  38 public:
  39     //==============================================================================
  40     /** Creates an item with default parameters, and zero size. */
  41     FlexItem() noexcept;
  42
  43     /** Creates an item with the given size. */
  44     FlexItem (float width, float height) noexcept;
  45
  46     /** Creates an item with the given size and target Component. */
  47     FlexItem (float width, float height, Component& targetComponent) noexcept;
  48
  49     /** Creates an item that represents an embedded FlexBox with a given size. */
  50     FlexItem (float width, float height, FlexBox& flexBoxToControl) noexcept;
  51
  52     /** Creates an item with a given target Component. */
  53     FlexItem (Component& componentToControl) noexcept;
  54
  55     /** Creates an item that represents an embedded FlexBox. This class will not
  56         create a copy of the supplied flex box. You need to ensure that the
  57         life-time of flexBoxToControl is longer than the FlexItem. */
  58     FlexItem (FlexBox& flexBoxToControl) noexcept;
  59
  60     //==============================================================================
  61     /** The item's current bounds. */
  62     Rectangle<float> currentBounds;
  63
  64     /** If this is non-null, it represents a Component whose bounds are controlled by this item. */
  65     Component* associatedComponent = nullptr;
  66
  67     /** If this is non-null, it represents a FlexBox whose bounds are controlled by this item. */
  68     FlexBox* associatedFlexBox = nullptr;
  69
  70     /** Determines the order used to lay out items in their flex container.
  71         Elements are laid out in ascending order of thus order value. Elements with the same order value
  72         are laid out in the order in which they appear in the array.
  73     */
  74     int order = 0;
  75
  76     /** Specifies the flex grow factor of this item.
  77         This indicates the amount of space inside the flex container the item should take up.
  78     */
  79     float flexGrow = 0.0f;
  80
  81     /** Specifies the flex shrink factor of the item.
  82         This indicates the rate at which the item shrinks if there is insufficient space in
  83         the container.
  84     */
  85     float flexShrink = 1.0f;
  86
  87     /** Specifies the flex-basis of the item.
  88         This is the initial main size of a flex item in the direction of flow. It determines the size
  89         of the content-box unless specified otherwise using box-sizing.
  90     */
  91     float flexBasis = 0.0f;
  92
  93     /** Possible value for the alignSelf property */
  94     enum class AlignSelf
  95     {
  96         autoAlign,       /**< Follows the FlexBox container's alignItems property. */
  97         flexStart,       /**< Item is aligned towards the start of the cross axis. */
  98         flexEnd,         /**< Item is aligned towards the end of the cross axis. */
  99         center,          /**< Item is aligned towards the center of the cross axis. */
 100         stretch          /**< Item is stretched from start to end of the cross axis. */
 101     };
 102
 103     /** This is the align-self property of the item.
 104         This determines the alignment of the item along the cross-axis (perpendicular to the direction
 105         of flow).
 106     */
 107     AlignSelf alignSelf = AlignSelf::autoAlign;
 108
 109     //==============================================================================
 110     /** This constant can be used for sizes to indicate that 'auto' mode should be used. */
 111     static const int autoValue    = -2;
 112     /** This constant can be used for sizes to indicate that no value has been set. */
 113     static const int notAssigned  = -1;
 114
 115     float width     = (float) notAssigned;  /**< The item's width. */
 116     float minWidth  = 0.0f;                 /**< The item's minimum width */
 117     float maxWidth  = (float) notAssigned;  /**< The item's maximum width */
 118
 119     float height    = (float) notAssigned;  /**< The item's height */
 120     float minHeight = 0.0f;                 /**< The item's minimum height */
 121     float maxHeight = (float) notAssigned;  /**< The item's maximum height */
 122
 123     /** Represents a margin. */
 124     struct Margin  final
 125     {
 126         Margin() noexcept;              /**< Creates a margin of size zero. */
 127         Margin (float size) noexcept;   /**< Creates a margin with this size on all sides. */
 128         Margin (float top, float right, float bottom, float left) noexcept;   /**< Creates a margin with these sizes. */
 129
 130         float left;   /**< Left margin size */
 131         float right;  /**< Right margin size */
 132         float top;    /**< Top margin size */
 133         float bottom; /**< Bottom margin size */
 134     };
 135
 136     /** The margin to leave around this item. */
 137     Margin margin;
 138
 139     //==============================================================================
 140     /** Returns a copy of this object with a new flex-grow value. */
 141     FlexItem withFlex (float newFlexGrow) const noexcept;
 142
 143     /** Returns a copy of this object with new flex-grow and flex-shrink values. */
 144     FlexItem withFlex (float newFlexGrow, float newFlexShrink) const noexcept;
 145
 146     /** Returns a copy of this object with new flex-grow, flex-shrink and flex-basis values. */
 147     FlexItem withFlex (float newFlexGrow, float newFlexShrink, float newFlexBasis) const noexcept;
 148
 149     /** Returns a copy of this object with a new width. */
 150     FlexItem withWidth (float newWidth) const noexcept;
 151
 152     /** Returns a copy of this object with a new minimum width. */
 153     FlexItem withMinWidth (float newMinWidth) const noexcept;
 154
 155     /** Returns a copy of this object with a new maximum width. */
 156     FlexItem withMaxWidth (float newMaxWidth) const noexcept;
 157
 158     /** Returns a copy of this object with a new height. */
 159     FlexItem withHeight (float newHeight) const noexcept;
 160
 161     /** Returns a copy of this object with a new minimum height. */
 162     FlexItem withMinHeight (float newMinHeight) const noexcept;
 163
 164     /** Returns a copy of this object with a new maximum height. */
 165     FlexItem withMaxHeight (float newMaxHeight) const noexcept;
 166
 167     /** Returns a copy of this object with a new margin. */
 168     FlexItem withMargin (Margin) const noexcept;
 169
 170     /** Returns a copy of this object with a new order. */
 171     FlexItem withOrder (int newOrder) const noexcept;
 172
 173     /** Returns a copy of this object with a new alignSelf value. */
 174     FlexItem withAlignSelf (AlignSelf newAlignSelf) const noexcept;
 175 };
 176
 177 } // namespace juce