From 257aeb50ebdaf81938ddbc2687925ea0fda96977 Mon Sep 17 00:00:00 2001 From: Noah Dayan Date: Mon, 20 Nov 2017 15:10:52 +0000 Subject: [PATCH] Added documentation for juce_Grid.h and juce_GridItem.h --- modules/juce_gui_basics/layout/juce_Grid.h | 100 +++++++++++++----- .../juce_gui_basics/layout/juce_GridItem.h | 74 ++++++++----- 2 files changed, 120 insertions(+), 54 deletions(-) diff --git a/modules/juce_gui_basics/layout/juce_Grid.h b/modules/juce_gui_basics/layout/juce_Grid.h index 6e11c99a04..6170ed99b7 100644 --- a/modules/juce_gui_basics/layout/juce_Grid.h +++ b/modules/juce_gui_basics/layout/juce_Grid.h @@ -60,7 +60,7 @@ public: }; //============================================================================== - /** */ + /** Represents a track. */ struct TrackInfo final { /** Creates a track with auto dimension. */ @@ -97,74 +97,118 @@ public: }; //============================================================================== - /** */ - enum class JustifyItems : int { start = 0, end, center, stretch }; - /** */ - enum class AlignItems : int { start = 0, end, center, stretch }; - /** */ - enum class JustifyContent { start, end, center, stretch, spaceAround, spaceBetween, spaceEvenly }; - /** */ - enum class AlignContent { start, end, center, stretch, spaceAround, spaceBetween, spaceEvenly }; - /** */ - enum class AutoFlow { row, column, rowDense, columnDense }; + /** Possible values for the justifyItems property. */ + enum class JustifyItems : int + { + start = 0, /**< Content inside the item is justified towards the left. */ + end, /**< Content inside the item is justified towards the right. */ + center, /**< Content inside the item is justified towards the center. */ + stretch /**< Content inside the item is stretched from left to right. */ + }; + + /** Possible values for the alignItems property. */ + enum class AlignItems : int + { + start = 0, /**< Content inside the item is aligned towards the top. */ + end, /**< Content inside the item is aligned towards the bottom. */ + center, /**< Content inside the item is aligned towards the center. */ + stretch /**< Content inside the item is stretched from top to bottom. */ + }; + + /** Possible values for the justifyContent property. */ + enum class JustifyContent + { + start, /**< Items are justified towards the left of the container. */ + end, /**< Items are justified towards the right of the container. */ + center, /**< Items are justified towards the center of the container. */ + stretch, /**< Items are stretched from left to right of the container. */ + spaceAround, /**< Items are evenly spaced along the row with spaces between them. */ + spaceBetween, /**< Items are evenly spaced along the row with spaces around them. */ + spaceEvenly /**< Items are evenly spaced along the row with even amount of spaces between them. */ + }; + + /** Possible values for the alignContent property. */ + enum class AlignContent + { + start, /**< Items are aligned towards the top of the container. */ + end, /**< Items are aligned towards the bottom of the container. */ + center, /**< Items are aligned towards the center of the container. */ + stretch, /**< Items are stretched from top to bottom of the container. */ + spaceAround, /**< Items are evenly spaced along the column with spaces between them. */ + spaceBetween, /**< Items are evenly spaced along the column with spaces around them. */ + spaceEvenly /**< Items are evenly spaced along the column with even amount of spaces between them. */ + }; + + /** Possible values for the autoFlow property. */ + enum class AutoFlow + { + row, /**< Fills the grid by adding rows of items. */ + column, /**< Fills the grid by adding columns of items. */ + rowDense, /**< Fills the grid by adding rows of items and attempts to fill in gaps. */ + columnDense /**< Fills the grid by adding columns of items and attempts to fill in gaps. */ + }; //============================================================================== - /** */ + /** Creates an empty Grid container with default parameters. */ Grid() noexcept; /** Destructor */ ~Grid() noexcept; //============================================================================== - /** */ + /** Specifies the alignment of content inside the items along the rows. */ JustifyItems justifyItems = JustifyItems::stretch; - /** */ + + /** Specifies the alignment of content inside the items along the columns. */ AlignItems alignItems = AlignItems::stretch; - /** */ + + /** Specifies the alignment of items along the rows. */ JustifyContent justifyContent = JustifyContent::stretch; - /** */ + + /** Specifies the alignment of items along the columns. */ AlignContent alignContent = AlignContent::stretch; - /** */ + + /** Specifies how the auto-placement algorithm places items. */ AutoFlow autoFlow = AutoFlow::row; //============================================================================== - /** */ + /** The set of column tracks to lay out. */ juce::Array templateColumns; - /** */ + /** The set of row tracks to lay out. */ juce::Array templateRows; /** Template areas */ juce::StringArray templateAreas; - /** */ + /** The row track for auto dimension. */ TrackInfo autoRows; - /** */ + /** The column track for auto dimension. */ TrackInfo autoColumns; - /** */ + /** The gap in pixels between columns. */ Px columnGap { 0 }; - /** */ + /** The gap in pixels between rows. */ Px rowGap { 0 }; - /** */ + /** Sets the gap between rows and columns in pixels. */ void setGap (Px sizeInPixels) noexcept { rowGap = columnGap = sizeInPixels; } //============================================================================== - /** */ + /** The set of items to lay-out. */ juce::Array items; //============================================================================== - /** */ + /** Lays-out the grid's items within the given rectangle. */ void performLayout (juce::Rectangle); //============================================================================== - /** */ + /** Returns the number of columns. */ int getNumberOfColumns() const noexcept { return templateColumns.size(); } - /** */ + /** Returns the number of rows. */ int getNumberOfRows() const noexcept { return templateRows.size(); } private: diff --git a/modules/juce_gui_basics/layout/juce_GridItem.h b/modules/juce_gui_basics/layout/juce_GridItem.h index f57ab79810..748fe1c43c 100644 --- a/modules/juce_gui_basics/layout/juce_GridItem.h +++ b/modules/juce_gui_basics/layout/juce_GridItem.h @@ -37,7 +37,7 @@ public: enum class Keyword { autoValue }; //============================================================================== - /** */ + /** Represents a span. */ struct Span { explicit Span (int numberToUse) noexcept : number (numberToUse) @@ -64,7 +64,7 @@ public: }; //============================================================================== - /** */ + /** Represents a property. */ struct Property { /** */ @@ -103,41 +103,62 @@ public: }; //============================================================================== - /** */ + /** Represents start and end properties. */ struct StartAndEndProperty { Property start, end; }; //============================================================================== - /** */ - enum class JustifySelf : int { start = 0, end, center, stretch, autoValue }; - /** */ - enum class AlignSelf : int { start = 0, end, center, stretch, autoValue }; + /** Possible values for the justifySelf property. */ + enum class JustifySelf : int + { + start = 0, /**< Content inside the item is justified towards the left. */ + end, /**< Content inside the item is justified towards the right. */ + center, /**< Content inside the item is justified towards the center. */ + stretch, /**< Content inside the item is stretched from left to right. */ + autoValue /**< Follows the Grid container's justifyItems property. */ + }; - /** */ + /** Possible values for the alignSelf property. */ + enum class AlignSelf : int + { + start = 0, /**< Content inside the item is aligned towards the top. */ + end, /**< Content inside the item is aligned towards the bottom. */ + center, /**< Content inside the item is aligned towards the center. */ + stretch, /**< Content inside the item is stretched from top to bottom. */ + autoValue /**< Follows the Grid container's alignItems property. */ + }; + + /** Creates an item with default parameters. */ GridItem() noexcept; - /** */ + /** Creates an item with a given Component to use. */ GridItem (juce::Component& componentToUse) noexcept; - /** */ + /** Creates an item with a given Component to use. */ GridItem (juce::Component* componentToUse) noexcept; /** Destructor. */ ~GridItem() noexcept; //============================================================================== - /** */ + /** If this is non-null, it represents a Component whose bounds are controlled by this item. */ juce::Component* associatedComponent = nullptr; //============================================================================== - /** */ + /** Determines the order used to lay out items in their grid container. */ int order = 0; - /** */ + /** This is the justify-self property of the item. + This determines the alignment of the item along the row. + */ JustifySelf justifySelf = JustifySelf::autoValue; - /** */ + + /** This is the align-self property of the item. + This determines the alignment of the item along the column. + */ AlignSelf alignSelf = AlignSelf::autoValue; - /** */ + /** These are the start and end properties of the column. */ StartAndEndProperty column = { Keyword::autoValue, Keyword::autoValue }; - /** */ + + /** These are the start and end properties of the row. */ StartAndEndProperty row = { Keyword::autoValue, Keyword::autoValue }; /** */ @@ -159,6 +180,7 @@ public: float minHeight = 0; float maxHeight = notAssigned; + /** Represents a margin. */ struct Margin { Margin() noexcept; @@ -172,10 +194,10 @@ public: float bottom; }; - /** */ + /** The margin to leave around this item. */ Margin margin; - /** */ + /** The item's current bounds. */ juce::Rectangle currentBounds; /** Short-hand */ @@ -196,28 +218,28 @@ public: /** Short-hand */ GridItem withArea (const juce::String& areaName) const noexcept; - /** */ + /** Returns a copy of this object with a new row property. */ GridItem withRow (StartAndEndProperty row) const noexcept; - /** */ + /** Returns a copy of this object with a new column property. */ GridItem withColumn (StartAndEndProperty column) const noexcept; - /** */ + /** Returns a copy of this object with a new alignSelf property. */ GridItem withAlignSelf (AlignSelf newAlignSelf) const noexcept; - /** */ + /** Returns a copy of this object with a new justifySelf property. */ GridItem withJustifySelf (JustifySelf newJustifySelf) const noexcept; - /** */ + /** Returns a copy of this object with a new width. */ GridItem withWidth (float newWidth) const noexcept; - /** */ + /** Returns a copy of this object with a new height. */ GridItem withHeight (float newHeight) const noexcept; - /** */ + /** Returns a copy of this object with a new size. */ GridItem withSize (float newWidth, float newHeight) const noexcept; - /** */ + /** Returns a copy of this object with a new margin. */ GridItem withMargin (Margin newMargin) const noexcept; /** Returns a copy of this object with a new order. */