Skip to content

Commit ac706b6

Browse files
djoweldjowel
committed
grid documentation
1 parent 8f11431 commit ac706b6

File tree

2 files changed

+214
-13
lines changed

2 files changed

+214
-13
lines changed

‎lib/include/elements/element/flow.hpp

+23-3
Original file line numberDiff line numberDiff line change
@@ -37,9 +37,9 @@ namespace cycfi::elements
3737
virtual float width_of(size_t index, basic_context const& ctx) const;
3838
virtual element_ptr make_row(size_t first, size_t last);
3939

40-
void reflow() { _reflow = true; }
41-
bool needs_reflow() const { return _reflow; }
42-
void reflow_done() { _reflow = false; }
40+
void reflow();
41+
bool needs_reflow() const;
42+
void reflow_done();
4343

4444
private:
4545

@@ -92,6 +92,26 @@ namespace cycfi::elements
9292
{
9393
return flow_element{flowable_};
9494
}
95+
96+
////////////////////////////////////////////////////////////////////////////
97+
// Inlines
98+
////////////////////////////////////////////////////////////////////////////
99+
namespace inlines{}
100+
101+
inline void flowable_container::reflow()
102+
{
103+
_reflow = true;
104+
}
105+
106+
inline bool flowable_container::needs_reflow() const
107+
{
108+
return _reflow;
109+
}
110+
111+
inline void flowable_container::reflow_done()
112+
{
113+
_reflow = false;
114+
}
95115
}
96116

97117
#endif

‎lib/include/elements/element/grid.hpp

+191-10
Original file line numberDiff line numberDiff line change
@@ -11,17 +11,33 @@
1111

1212
namespace cycfi::elements
1313
{
14-
////////////////////////////////////////////////////////////////////////////
15-
// grid_base: Base class for vertical and horizontal grids, supplies grid
16-
// coordinates in the form of a float const*
17-
////////////////////////////////////////////////////////////////////////////
14+
/**
15+
* \struct grid_base
16+
*
17+
* \brief
18+
* Base class for vertical and horizontal grids in a grid layout.
19+
* Provides supplies grid coordinates.
20+
*
21+
* `grid_base` provides the core functionality shared by all grid-like
22+
* structures, such as being able to determine their size, map index to
23+
* a coordinate, and get a number of spans.
24+
*/
1825
struct grid_base : public composite_base
1926
{
2027
virtual std::size_t grid_size() const = 0;
2128
virtual float grid_coord(std::size_t i) const = 0;
2229
virtual std::size_t num_spans() const = 0;
2330
};
2431

32+
/**
33+
* \class equal_grid
34+
*
35+
* \brief
36+
* A specialized grid where grid columns (or rows) have equal size.
37+
*
38+
* \tparam Base
39+
* The base class on which `equal_grid` is derived from.
40+
*/
2541
template <typename Base>
2642
class equal_grid : public Base
2743
{
@@ -34,6 +50,17 @@ namespace cycfi::elements
3450
{ return float(i+1) / this->num_spans(); }
3551
};
3652

53+
/**
54+
* \class range_grid
55+
*
56+
* \brief
57+
* A specialized grid that lays out cells based on a supplied array of
58+
* coordinates in the form of a pointer to a float array (`float
59+
* const*`).
60+
*
61+
* \tparam Base
62+
* The base class on which `range_grid` derived from.
63+
*/
3764
template <typename Base>
3865
class range_grid : public Base
3966
{
@@ -62,6 +89,26 @@ namespace cycfi::elements
6289
};
6390
}
6491

92+
/**
93+
* \class container_grid
94+
*
95+
* \brief
96+
* A specialized grid that lays out cells based on coordinates provided
97+
* by a container.
98+
*
99+
* `container_grid` is a grid where the size and coordinates of cells
100+
* are defined by the elements of a container that is given at
101+
* construction time. `container_grid` does not manage and does not own
102+
* the container.
103+
*
104+
* \tparam Container
105+
* The type of container which provides data for the grid coordinates.
106+
* The Container should satisfy the `GridContainer` concept.
107+
*
108+
* \tparam Base
109+
* The base class on which `container_grid` is derived from. The base
110+
* class should satisfy the `Composite` concept.
111+
*/
65112
template <concepts::GridContainer Container, concepts::Composite Base>
66113
class container_grid : public Base
67114
{
@@ -79,9 +126,13 @@ namespace cycfi::elements
79126
Container const& _container;
80127
};
81128

82-
////////////////////////////////////////////////////////////////////////////
83-
// Vertical Grids
84-
////////////////////////////////////////////////////////////////////////////
129+
/**
130+
* \class vgrid_element
131+
*
132+
* \brief
133+
* A specialized grid class that provides layout features for a
134+
* vertical grid structure.
135+
*/
85136
class vgrid_element : public grid_base
86137
{
87138
public:
@@ -101,6 +152,29 @@ namespace cycfi::elements
101152
container_grid<std::vector<float>, vgrid_element>
102153
>;
103154

155+
/**
156+
* \brief
157+
* Create vertical grid layout, given row coordinates as a C-style
158+
* array.
159+
*
160+
* \tparam N
161+
* The number of rows.
162+
*
163+
* \tparam E
164+
* A parameter pack representing a variadic template parameter. It
165+
* consists of the elements put into grid cells.
166+
*
167+
* \param coords
168+
* C-style array with coordinates for grid cells.
169+
*
170+
* \param elements
171+
* Elements intended to place in grid cells.
172+
*
173+
* \returns
174+
* A vertical grid element represented as an instance of
175+
* `array_composite` that is derived from `range_grid<vgrid_element>`.
176+
* The row coordinates are provided by the `coords` parameter.
177+
*/
104178
template <std::size_t N, typename... E>
105179
inline auto vgrid(float const(&coords)[N], E&&... elements)
106180
{
@@ -111,13 +185,53 @@ namespace cycfi::elements
111185
return r;
112186
}
113187

188+
/**
189+
* \brief
190+
* Create a vertical grid layout, given row coordinates as an
191+
* `std::array`.
192+
*
193+
* \tparam N
194+
* The number of rows.
195+
*
196+
* \tparam E
197+
* A parameter pack representing a variadic template parameter. It
198+
* consists of the elements put into grid cells.
199+
*
200+
* \param coords
201+
* `std::array` with coordinates for grid cells.
202+
*
203+
* \param elements
204+
* Elements intended to place in grid cells.
205+
*
206+
* \returns
207+
* A vertical grid element represented as an instance of
208+
* `array_composite` that is derived from `range_grid<vgrid_element>`.
209+
* The row coordinates are provided by the `coords` parameter.
210+
*/
114211
template <std::size_t N, typename... E>
115212
inline auto vgrid(std::array<float, N> const& coords, E&&... elements)
116213
{
117214
using plain_array = float const (&)[N];
118215
return vgrid(plain_array(*coords.data()), std::forward<E>(elements)...);
119216
}
120217

218+
/**
219+
* \brief
220+
* Create a vertical grid layout, given the elements to place in
221+
* equally sized rows.
222+
*
223+
* \tparam E
224+
* A parameter pack representing a variadic template parameter. It
225+
* consists of the elements put into grid cells.
226+
*
227+
* \param elements
228+
* Elements intended to place in grid cells.
229+
*
230+
* \returns
231+
* A vertical grid element represented as an instance of
232+
* `array_composite` that is derived from `equal_grid<vgrid_element>.
233+
* The rows are equally spaced.
234+
*/
121235
template <typename... E>
122236
inline auto vgrid(E&&... elements)
123237
{
@@ -128,9 +242,13 @@ namespace cycfi::elements
128242
return r;
129243
}
130244

131-
////////////////////////////////////////////////////////////////////////////
132-
// Horizontal Grids
133-
////////////////////////////////////////////////////////////////////////////
245+
/**
246+
* \class hgrid_element
247+
*
248+
* \brief
249+
* A specialized grid class that provides layout features for a
250+
* horizontal grid structure.
251+
*/
134252
class hgrid_element : public grid_base
135253
{
136254
public:
@@ -150,6 +268,29 @@ namespace cycfi::elements
150268
container_grid<std::vector<float>, hgrid_element>
151269
>;
152270

271+
/**
272+
* \brief
273+
* Create horizontal grid layout, given column coordinates as a C-style
274+
* array.
275+
*
276+
* \tparam N
277+
* The number of columns.
278+
*
279+
* \tparam E
280+
* A parameter pack representing a variadic template parameter. It
281+
* consists of the elements put into grid cells.
282+
*
283+
* \param coords
284+
* C-style array with coordinates for grid cells.
285+
*
286+
* \param elements
287+
* Elements intended to place in grid cells.
288+
*
289+
* \returns
290+
* A horizontal grid element represented as an instance of
291+
* `array_composite` that is derived from `range_grid<hgrid_element>`.
292+
* The column coordinates are provided by the `coords` parameter.
293+
*/
153294
template <std::size_t N, typename... E>
154295
inline auto hgrid(float const(&coords)[N], E&&... elements)
155296
{
@@ -160,13 +301,53 @@ namespace cycfi::elements
160301
return r;
161302
}
162303

304+
/**
305+
* \brief
306+
* Create a horizontal grid layout, given column coordinates as an
307+
* `std::array`.
308+
*
309+
* \tparam N
310+
* The number of columns.
311+
*
312+
* \tparam E
313+
* A parameter pack representing a variadic template parameter. It
314+
* consists of the elements put into grid cells.
315+
*
316+
* \param coords
317+
* `std::array` with coordinates for grid cells.
318+
*
319+
* \param elements
320+
* Elements intended to place in grid cells.
321+
*
322+
* \returns
323+
* A horizontal grid element represented as an instance of
324+
* `array_composite` that is derived from `range_grid<hgrid_element>`.
325+
* The column coordinates are provided by the `coords` parameter.
326+
*/
163327
template <std::size_t N, typename... E>
164328
inline auto hgrid(std::array<float, N> const& coords, E&&... elements)
165329
{
166330
using plain_array = float const (&)[N];
167331
return hgrid(plain_array(*coords.data()), std::forward<E>(elements)...);
168332
}
169333

334+
/**
335+
* \brief
336+
* Create a horizontal grid layout, given the elements to place in
337+
* equally sized grid cells.
338+
*
339+
* \tparam E
340+
* A parameter pack representing a variadic template parameter. It
341+
* consists of the elements put into grid cells.
342+
*
343+
* \param elements
344+
* Elements intended to place in grid cells.
345+
*
346+
* \returns
347+
* A horizontal grid element represented as an instance of
348+
* `array_composite` that is derived from `equal_grid<hgrid_element>.
349+
* The columns are equally spaced.
350+
*/
170351
template <typename... E>
171352
inline auto hgrid(E&&... elements)
172353
{

0 commit comments

Comments
 (0)