diff --git a/doc/first-steps.md b/doc/first-steps.md index 07ebd9d5..5fec9a6d 100644 --- a/doc/first-steps.md +++ b/doc/first-steps.md @@ -741,13 +741,30 @@ Widget layout ### 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.
widget-coordinates
Figure 1. Widget coordinates
- +

```cpp int getX() const; @@ -761,23 +778,43 @@ virtual void setY (int y, 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 ### -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 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. - widget width >= client widget width - 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. - widget width = left padding + client width + right padding - widget height = top padding + client height + bottom padding +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 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. + +        widget width ≥ client widget width
+        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. + +        widget width = left padding + client width + right padding
+        widget height = top padding + client height + bottom padding
widget-lengths
Figure 2. Width and height of a widget
+

```cpp @@ -797,20 +834,40 @@ void setBottomPadding (int bottom, 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 ### -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. -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(). +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. +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()`.
widget-geometry
Figure 3. Geometry of widgets
- +

```cpp 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); ``` -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 ###