perso
/
finalcut
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

markdown formatting

This commit is contained in:
Markus Gans 2020-01-14 20:27:19 +01:00
parent 815562173f
commit 3e3076838f
1 changed files with 77 additions and 16 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

93
doc/first-steps.md
View File

@ -741,13 +741,30 @@ Widget layout
### Coordinates ### ### Coordinates ###
The positioning of a widget in the terminal works via a coordinate system. It consists of x characters in the horizontal and y characters in the vertical. The upper left corner has the coordinates (1, 1). With the commands getDesktopWidth() and getDesktopHeight(), the width and height of the terminal get retrieved. These two values result in the position of the lower right terminal corner. The position of a widget is retrievable with getX(), getY(), and getPos() or is definable with setX(), setY(), and setPos(). The data type for each coordinate is an int. All positions represent an FPoint() object. The positioning of the widget is always relative to its parent widget. The top parent widget in a chain of children contains the terminal desktop. There the absolute terminal positions are still identical to the relative positions (getPos == get_Term_Pos). In the case of a child widget, the positioning is corresponding to the upper left corner of the parent widget plus a possible padding space (can be determined with getLeftPadding() and getTopPadding()). If you want to ignore padding spaces, you must force this with the ignorePadding() method. The positioning of a widget in the terminal works via a coordinate
system. It consists of _x_ characters in the horizontal and _y_
characters in the vertical. The upper left corner has the coordinates
(1, 1). With the commands `getDesktopWidth()` and `getDesktopHeight()`,
the width and height of the terminal get retrieved. These two values
result in the position of the lower right terminal corner. The position
of a widget is retrievable with `getX()`, `getY()`, and `getPos()` or
is definable with `setX()`, `setY()`, and `setPos()`. The data type for
each coordinate is an `int`. All positions represent an `FPoint`
object. The positioning of the widget is always relative to its parent
widget. The top parent widget in a chain of children contains the
terminal desktop. There the absolute terminal positions are still
identical to the relative positions (`getPos()` = `getTermPos()`). In
the case of a child widget, the positioning is corresponding to the
upper left corner of the parent widget plus a possible padding space
(can be determined with `getLeftPadding()` and `getTopPadding()`).
If you want to ignore padding spaces, you must force this with the
`ignorePadding()` method.
<figure class="image"> <figure class="image">
<img src="widget-coordinates.svg" alt="widget-coordinates"> <img src="widget-coordinates.svg" alt="widget-coordinates">
<figcaption>Figure 1. Widget coordinates</figcaption> <figcaption>Figure 1. Widget coordinates</figcaption>
</figure> </figure>
<br /><br />
```cpp ```cpp
int getX() const; int getX() const;
@ -761,23 +778,43 @@ virtual void setY (int y, bool adjust = true);
virtual void setPos (const Fpoint& p, bool adjust = true); virtual void setPos (const Fpoint& p, bool adjust = true);
``` ```
If you set the value of adjust to false when calling setX(), setY(), or setPos(), this will prevent the explicit call of adjustSize() afterward. This is important to avoid adjustSize() loops or to block the adjustSize() call from being repeated unnecessarily often. If you set the value of `adjust` to `false` when calling `setX()`,
`setY()`, or `setPos()`, this will prevent the explicit call of
`adjustSize()` afterward. This is important to avoid `adjustSize()`
loops or to block the `adjustSize()` call from being repeated
unnecessarily often.
### Lengths ### ### Lengths ###
The dimensions of a widget can be retrieved and defined separately in width and height. The methods getWidth() and getHeight() respectively setWidth() and setHeight() are used for this. Because a length cannot be negative, all lengths are of type std::size_t. The dimensions of a widget can be retrieved and defined separately in
The maximum size of a child widget automatically results from the size of the parent widget, which is retrievable with getClientWidth() and getClientHeight(). Some widgets have a border, a title bar, or both, which can reduce the maximum size of the child widget. width and height. The methods `getWidth()` and `getHeight()`
widget width >= client widget width respectively `setWidth()` and `setHeight()` are used for this. Because
widget height >= client widget height a length cannot be negative, all lengths are of type `std::size_t`.
Corresponding padding space ensures the correct distance here. The padding space can be retrieved separately for all four sides with the widget methods getTopPadding(), getLeftPadding(), getBottomPadding(), and getRightPadding(). You can set the required padding space for the widget using the setTopPadding(), setLeftPadding(), setBottomPadding() and setRightPadding() methods. The maximum size of a child widget automatically results from the size
widget width = left padding + client width + right padding of the parent widget, which is retrievable with `getClientWidth()` and
widget height = top padding + client height + bottom padding `getClientHeight()`. Some widgets have a border, a title bar, or both,
which can reduce the maximum size of the child widget.
&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;widget width ≥ client widget width<br />
&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;widget height ≥ client widget height
Corresponding padding space ensures the correct distance here. The
padding space can be retrieved separately for all four sides with
the widget methods `getTopPadding()`, `getLeftPadding()`,
`getBottomPadding()`, and `getRightPadding()`. You can set the
required padding space for the widget using the `setTopPadding()`,
`setLeftPadding()`, `setBottomPadding()` and `setRightPadding()`
methods.
&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;widget width = left padding + client width + right padding<br />
&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;widget height = top padding + client height + bottom padding
<figure class="image"> <figure class="image">
<img src="widget-lengths.svg" alt="widget-lengths"> <img src="widget-lengths.svg" alt="widget-lengths">
<figcaption>Figure 2. Width and height of a widget</figcaption> <figcaption>Figure 2. Width and height of a widget</figcaption>
</figure> </figure>
<br /><br />
```cpp ```cpp
@ -797,20 +834,40 @@ void setBottomPadding (int bottom, bool adjust = true);
void setRightPadding (int right, bool adjust = true); void setRightPadding (int right, bool adjust = true);
``` ```
If the value of adjust is set to false for setWidth(), setHeight(), setTopPadding(), setLeftPadding(), setBottomPadding() or setRightPadding(), then adjustSize() is not explicitly called afterwards. This is important to prevent adjustSize() loops or to avoid that adjustSize() is called unnecessarily often. If the value of `adjust` is set to `false` for `setWidth()`,
`setHeight()`, `setTopPadding()`, `setLeftPadding()`,
`setBottomPadding()` or `setRightPadding()`, then `adjustSize()` is
not explicitly called afterward. This is important to prevent
`adjustSize()` loops or to avoid that `adjustSize()` is called
unnecessarily often.
### Areas ### ### Areas ###
The terminal area in which a widget appears determines its geometry. The geometry of a widget is composed of its position and its size. A widget position is always of object type FPoint() and a widget size of type FSize(). The widget geometry can get as FRect object via the widget method getGeometry() and set with the method setGeometry(). The getTermGeometry() method gets the total values of the terminal geometry. The terminal area in which a widget appears determines its geometry.
If you are only interested in the size of a widget, you can also use the method getSize(). To set the widget size, you can use the method setSize(). The geometry of a widget is composed of its position and its size.
The position of a shadow is outside the widget. The shadow size itself as FSize() object is retrievable via the getShadow() method. You can set the widget shadow size with the setShadowSize() method. If you want to get the geometry values of a widget, including its shadow, you can use the method getGeometryWithShadow() from the FWidget class. If you want to have the entire geometry with shadow for the absolute geometry values as a FRect object, you can call the method getTermGeometryWithShadow(). A widget position is always of object type `FPoint` and a widget
size of type `FSize`. The widget geometry can get as `FRect` object
via the widget method `getGeometry()` and set with the method
`setGeometry()`. The `getTermGeometry()` method gets the total values
of the terminal geometry.
If you are only interested in the size of a widget, you can also use
the method `getSize()`. To set the widget size, you can use the method
`setSize()`.
The position of a shadow is outside the widget. The shadow size itself
as `FSize` object is retrievable via the `getShadow()` method. You
can set the widget shadow size with the `setShadowSize()` method. If
you want to get the geometry values of a widget, including its shadow,
you can use the method `getGeometryWithShadow()` from the FWidget
class. If you want to have the entire geometry with shadow for the
absolute geometry values as a `FRect` object, you can call the method
`getTermGeometryWithShadow()`.
<figure class="image"> <figure class="image">
<img src="widget-geometry.svg" alt="widget-geometry"> <img src="widget-geometry.svg" alt="widget-geometry">
<figcaption>Figure 3. Geometry of widgets</figcaption> <figcaption>Figure 3. Geometry of widgets</figcaption>
</figure> </figure>
<br /><br />
```cpp ```cpp
const FSize getSize() const; const FSize getSize() const;
@ -825,7 +882,11 @@ virtual void setGeometry (const Fpoint& p, const FSize& s, bool adjust = true)
virtual void setShadowSize (const FSize& size); virtual void setShadowSize (const FSize& size);
``` ```
If you explicitly set the value of adjust to false when using the setSize(), setGeometry() or setShadowSize() mutators, the adjustSize() method is no longer called automatically. This can be used to prevent recursive adjustSize() calls or to avoid unnecessary adjustSize() calls. If you explicitly set the value of `adjust` to `false` when
using the `setSize()`, `setGeometry()` or `setShadowSize()`
mutators, the `adjustSize()` method is no longer called automatically.
This can be used to prevent recursive `adjustSize()` calls or to
avoid unnecessary `adjustSize()` calls.
### Dynamic layout ### ### Dynamic layout ###