source/modules/juce_gui_basics/positioning/juce_RelativeCoordinate.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 /**
  31     Expresses a coordinate as a dynamically evaluated expression.
  32
  33     When using relative coordinates to position components, the following symbols are available:
  34      - "left", "right", "top", "bottom" refer to the position of those edges in this component, so
  35        e.g. for a component whose width is always 100, you might set the right edge to the "left + 100".
  36      - "[id].left", "[id].right", "[id].top", "[id].bottom", "[id].width", "[id].height", where [id] is
  37        the identifier of one of this component's siblings. A component's identifier is set with
  38        Component::setComponentID(). So for example if you want your component to always be 50 pixels to the
  39        right of the one called "xyz", you could set your left edge to be "xyz.right + 50".
  40      - Instead of an [id], you can use the name "parent" to refer to this component's parent. Like
  41        any other component, these values are relative to their component's parent, so "parent.right" won't be
  42        very useful for positioning a component because it refers to a position with the parent's parent.. but
  43        "parent.width" can be used for setting positions relative to the parent's size. E.g. to make a 10x10
  44        component which remains 1 pixel away from its parent's bottom-right, you could use
  45        "right - 10, bottom - 10, parent.width - 1, parent.height - 1".
  46      - The name of one of the parent component's markers can also be used as a symbol. For markers to be
  47        used, the parent component must implement its Component::getMarkers() method, and return at least one
  48        valid MarkerList. So if you want your component's top edge to be 10 pixels below the
  49        marker called "foobar", you'd set it to "foobar + 10".
  50
  51     See the Expression class for details about the operators that are supported, but for example
  52     if you wanted to make your component remains centred within its parent with a size of 100, 100,
  53     you could express it as:
  54     @code myComp.setBounds (RelativeBounds ("parent.width / 2 - 50, parent.height / 2 - 50, left + 100, top + 100"));
  55     @endcode
  56     ..or an alternative way to achieve the same thing:
  57     @code myComp.setBounds (RelativeBounds ("right - 100, bottom - 100, parent.width / 2 + 50, parent.height / 2 + 50"));
  58     @endcode
  59
  60     Or if you wanted a 100x100 component whose top edge is lined up to a marker called "topMarker" and
  61     which is positioned 50 pixels to the right of another component called "otherComp", you could write:
  62     @code myComp.setBounds (RelativeBounds ("otherComp.right + 50, topMarker, left + 100, top + 100"));
  63     @endcode
  64
  65     Be careful not to make your coordinate expressions recursive, though, or exceptions and assertions will
  66     be thrown!
  67
  68     @see RelativePoint, RelativeRectangle
  69
  70     @tags{GUI}
  71 */
  72 class JUCE_API  RelativeCoordinate
  73 {
  74 public:
  75     //==============================================================================
  76     /** Creates a zero coordinate. */
  77     RelativeCoordinate();
  78     RelativeCoordinate (const Expression& expression);
  79     RelativeCoordinate (const RelativeCoordinate&);
  80     RelativeCoordinate& operator= (const RelativeCoordinate&);
  81     RelativeCoordinate (RelativeCoordinate&&) noexcept;
  82     RelativeCoordinate& operator= (RelativeCoordinate&&) noexcept;
  83
  84     /** Creates an absolute position from the parent origin on either the X or Y axis.
  85
  86         @param absoluteDistanceFromOrigin   the distance from the origin
  87     */
  88     RelativeCoordinate (double absoluteDistanceFromOrigin);
  89
  90     /** Recreates a coordinate from a string description.
  91         The string will be parsed by ExpressionParser::parse().
  92         @param stringVersion    the expression to use
  93         @see toString
  94     */
  95     RelativeCoordinate (const String& stringVersion);
  96
  97     /** Destructor. */
  98     ~RelativeCoordinate();
  99
 100     bool operator== (const RelativeCoordinate&) const noexcept;
 101     bool operator!= (const RelativeCoordinate&) const noexcept;
 102
 103     //==============================================================================
 104     /** Calculates the absolute position of this coordinate.
 105
 106         You'll need to provide a suitable Expression::Scope for looking up any coordinates that may
 107         be needed to calculate the result.
 108     */
 109     double resolve (const Expression::Scope* evaluationScope) const;
 110
 111     /** Returns true if this coordinate uses the specified coord name at any level in its evaluation.
 112         This will recursively check any coordinates upon which this one depends.
 113     */
 114     bool references (const String& coordName, const Expression::Scope* evaluationScope) const;
 115
 116     /** Returns true if there's a recursive loop when trying to resolve this coordinate's position. */
 117     bool isRecursive (const Expression::Scope* evaluationScope) const;
 118
 119     /** Returns true if this coordinate depends on any other coordinates for its position. */
 120     bool isDynamic() const;
 121
 122     //==============================================================================
 123     /** Changes the value of this coord to make it resolve to the specified position.
 124
 125         Calling this will leave the anchor points unchanged, but will set this coordinate's absolute
 126         or relative position to whatever value is necessary to make its resultant position
 127         match the position that is provided.
 128     */
 129     void moveToAbsolute (double absoluteTargetPosition, const Expression::Scope* evaluationScope);
 130
 131     /** Returns the expression that defines this coordinate. */
 132     const Expression& getExpression() const         { return term; }
 133
 134
 135     //==============================================================================
 136     /** Returns a string which represents this coordinate.
 137         For details of the string syntax, see the constructor notes.
 138     */
 139     String toString() const;
 140
 141     //==============================================================================
 142     /** A set of static strings that are commonly used by the RelativeCoordinate class.
 143
 144         As well as avoiding using string literals in your code, using these preset values
 145         has the advantage that all instances of the same string will share the same, reference-counted
 146         String object, so if you have thousands of points which all refer to the same
 147         anchor points, this can save a significant amount of memory allocation.
 148     */
 149     struct Strings
 150     {
 151         static const String parent;         /**< "parent" */
 152         static const String left;           /**< "left" */
 153         static const String right;          /**< "right" */
 154         static const String top;            /**< "top" */
 155         static const String bottom;         /**< "bottom" */
 156         static const String x;              /**< "x" */
 157         static const String y;              /**< "y" */
 158         static const String width;          /**< "width" */
 159         static const String height;         /**< "height" */
 160     };
 161
 162     /** @internal */
 163     struct StandardStrings
 164     {
 165         enum Type
 166         {
 167             left, right, top, bottom,
 168             x, y, width, height,
 169             parent,
 170             unknown
 171         };
 172
 173         static Type getTypeOf (const String& s) noexcept;
 174     };
 175
 176 private:
 177     //==============================================================================
 178     Expression term;
 179 };
 180
 181 } // namespace juce