mirrors/fltk
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Update documentation with Fl_Flex and Fl_Grid widgets

Browse Source
This commit is contained in:
Albrecht Schlosser 2023-10-17 18:24:14 +02:00
parent 50b04b565b
commit 49900e3710
1 changed files with 99 additions and 11 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

110
documentation/src/coordinates.dox
View File

@ -7,7 +7,7 @@ positioning widgets manually, and some of the basics of FLTK
layout widgets that are used to position widgets automatically.
\section coordinates_coordinates The widget coordinate system
\section coordinates_coordinates The Widget Coordinate System
All widgets have constructors with \p x and \p y parameters to
let the programmer specify the desired initial position of the
@ -43,7 +43,7 @@ In other words, the widget hierarchy and positions can be summarized as:
</pre>
\section coordinate_layout Layout and container widgets
\section coordinate_layout Layout and Container Widgets
There are four main groups of widgets derived from Fl_Group for
a range of different purposes.
@ -58,7 +58,7 @@ new capability. These widgets are Fl_Scroll, Fl_Tabs and Fl_Wizard.
The third group are layout managers that relocate and resize the
child widgets added to them in order to satisfy a particular layout
algorithm. These widgets are Fl_Pack and Fl_Tile.
algorithm. These widgets are Fl_Flex, Fl_Grid, Fl_Pack, and Fl_Tile.
The final group consists of Fl_Window and its derivatives.
Their special capability is that they can be top-level application
@ -70,8 +70,86 @@ the position of top-level windows, and the \p x and \p y
position parameters may be treated as hints, or even ignored.
The Fl_Window class has an extra constructor that omits them.
Descriptions of layout and container widgets follow in alphabetical order.
\subsection coordinates_pack The Fl_Pack layout widget
\subsection coordinates_flex The Fl_Flex Layout Widget
The Fl_Flex widget allows the layout of its direct children as a single row
or column. If its type() is set to give the row or horizontal layout, the
children are all resized to have the same height as the Fl_Flex and are
moved next to each other. If set to give the column or vertical layout,
the children are all resized to have the same width as the Fl_Flex and
are then stacked below each other.
Widget positions (x, y) need not be given by the user because widgets are
positioned inside the Fl_Flex container in the order of its children.
Widget sizes can be set to (0, 0) as in Fl_Pack since they are calculated
by Fl_Flex.
This is similar to Fl_Pack described below and Fl_Flex is designed to
act as a drop-in replacement of Fl_Pack with some minor differences.
Other than Fl_Pack the Fl_Flex widget does \b not resize itself but resizes
its children to fill the entire space of the Fl_Flex container. Single
children of Fl_Flex can be set to fixed sizes to inhibit this resizing
behavior. In this case the remaining space is distributed to all
non-fixed widgets.
Fl_Flex widgets can be nested inside each other and with Fl_Grid in any
combination.
The name Fl_Flex was inspired by the CSS 'flex' container.
\image html Fl_Flex_simple.png "Simple Fl_Flex Layout"
\image latex Fl_Flex_simple.png "Simple Fl_Flex Layout" width=8cm
Fl_Flex was added in FLTK 1.4.0.
\subsection coordinates_grid The Fl_Grid Layout Widget
Fl_Grid is the most flexible layout container in FLTK 1.4. It is based
on a flexible grid of \b cells that can be assigned one widget per cell
which is the \e anchor of the widget. Widgets can span multiple rows
and columns and the cells can constitute a sparse matrix. Widgets can be
aligned inside their cells in several ways (left, right, top, bottom) and
can stretch horizontally, vertically, or both, i.e. fill the entire cell.
Widget positions (x, y) need not be given by the user because widgets are
assigned to a particular grid cell by row and column number. Widget sizes
can be given as their \b minimal sizes and will be resized appropriately
depending on the free space.
Optional margins around all cells inside the widget border and gaps between
rows and cells make the layout even more flexible.
The Fl_Grid widget should be designed with a grid (matrix) and its minimal
size in mind. It is designed to \b enlarge cells and widgets in a flexible
way when the Fl_Grid widget itself is created or resized.
Additional free space inside the Fl_Grid container is distributed to widgets
by considering minimal row heights, column widths, sizes of widgets, and
row and column \e weights. These weights are used to distribute the free
space proportionally according to the row and column weights.
Fl_Grid widgets can be nested inside each other and with Fl_Flex and other
subclasses of Fl_Group in any combination.
\note We don't recommend to use Fl_Pack as child widgets although this
\b may work as well.
The name Fl_Grid was inspired by the CSS 'grid' container but it has
some properties in common with HTML \<table\> containers as well, for
instance row and column spanning.
\image html Fl_Grid.png "Simple Fl_Grid Layout"
\image latex Fl_Grid.png "Simple Fl_Grid Layout" width=8cm
Fl_Grid was added in FLTK 1.4.0.
\subsection coordinates_pack The Fl_Pack Layout Widget
The Fl_Pack widget allows the layout of its direct children as a
single row, or column.
@ -80,9 +158,8 @@ the children are all resized to have the same height as the Fl_Pack
and are moved next to each other.
If set to give the column or vertical layout, the children are all
resized to have the same width as the Fl_Pack and are then stacked
below each other.
The Fl_Pack then resizes itself to shrink-wrap itself around all
of the children.
below each other. The Fl_Pack then resizes itself to shrink-wrap itself
around all of the children.
Fl_Pack widgets are often used inside an Fl_Scroll, as shown in the
diagram below, to avoid having to deal with tricky resize behavior
@ -91,8 +168,19 @@ when used with nested widgets.
\image html pack.png "Fl_Pack test program screenshot"
\image latex pack.png "Fl_Pack test program screenshot" width=8cm
Since FLTK 1.4.0 Fl_Flex (described above) can in many cases be used as
a drop-in replacement for Fl_Pack if this "shrink-wrap" behavior is not
required. Note that the Fl_Pack layout algorithm can cause some issues
because its widget size can change depending on its children and
particularly because this is done late, i.e. during draw() and not
as usual during resize of the window.
\subsection coordinates_scroll The Fl_Scroll container widget
\note We recommend that developers evaluate whether using Fl_Flex or Fl_Grid
instead of Fl_Pack can be a better solution with more predictable and
reliable resizing behavior of the overall program layout.
\subsection coordinates_scroll The Fl_Scroll Container Widget
The Fl_Scroll container widget can hold an assortment of widgets
that may extend beyond its own width and height, in which case
@ -103,7 +191,7 @@ so that you can scroll and view the entire contents.
\image latex Fl_Scroll.png "Fl_Scroll container widget" width=4cm
\subsection coordinates_tabs The Fl_Tabs container widget
\subsection coordinates_tabs The Fl_Tabs Container Widget
The Fl_Tabs widget provides a front-to-back stack of individual
panels which usually contain Fl_Group widgets and their children.
@ -115,7 +203,7 @@ is determined by the child widget's label and related attributes.
\image latex tabs.png "Fl_Tabs container widget" width=8cm
\subsection coordinates_tile The Fl_Tile layout widget
\subsection coordinates_tile The Fl_Tile Layout Widget
The Fl_Tile widget allows the user to resize one or more of its children
by dragging on the border between adjacent child widgets.
@ -132,7 +220,7 @@ For more information see the Fl_Tile widget manual page, and \ref resize.
\image latex Fl_Tile.png "The Fl_Tile layout widget" width=4cm
\subsection coordinates_wizard The Fl_Wizard container widget
\subsection coordinates_wizard The Fl_Wizard Container Widget
The Fl_Wizard widget derives from the Fl_Tabs class, but instead
of having tabs that the user can click to select the corresponding