From 3183e376bbe52283969f104976ba710e75ac52ab Mon Sep 17 00:00:00 2001 From: Markus Gans Date: Sun, 12 Jan 2020 20:10:34 +0100 Subject: [PATCH] Add a "widget layout" chapter to the first steps document --- ChangeLog | 3 ++ doc/first-steps.md | 101 +++++++++++++++++++++++++++++++++++++++++++-- 2 files changed, 101 insertions(+), 3 deletions(-) diff --git a/ChangeLog b/ChangeLog index 76cf0011..79cf3ae3 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,6 @@ +2020-01-12 Markus Gans + * Add a "widget layout" chapter to the first steps document + 2020-01-09 Markus Gans * With setText() and clearText() the text in the edit line can be changed without changing the content of the combo box diff --git a/doc/first-steps.md b/doc/first-steps.md index a47e60b4..07ebd9d5 100644 --- a/doc/first-steps.md +++ b/doc/first-steps.md @@ -16,7 +16,11 @@ Table of Contents - [Callback lambda expression](#example-of-an-lambda-expression-callback) - [Callback method](#example-of-a-callback-function) - [Custom signals](#send-custom-signals) -- [Dynamic layout](#dynamic-layout) +- [Widget layout](#widget-layout) + - [Coordinates](#coordinates) + - [Lengths](#lengths) + - [Areas](#areas) + - [Dynamic layout](#dynamic-layout) - [Scroll view](#scroll-view) @@ -732,8 +736,99 @@ g++ -O2 -lfinal -std=c++11 emit-signal.cpp -o emit-signal ``` -Dynamic layout --------------- +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. + +
+ widget-coordinates +
Figure 1. Widget coordinates
+
+ + +```cpp +int getX() const; +int getY() const; +const FPoint getPos() const; +int getTermX() const; +int getTermY() const; +const FPoint getTermPos() const; +virtual void setX (int x, bool adjust = true); +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. + + +### 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 + +
+ widget-lengths +
Figure 2. Width and height of a widget
+
+ + +```cpp +std::size_t getWidth() const; +std::size_t getHeight() const; +std::size_t getClientWidth() const; +std::size_t getClientHeight() const; +int getTopPadding() const; +int getLeftPadding() const; +int getBottomPadding() const; +int getRightPadding() const; +virtual void setWidth (std::size_t width, bool adjust = true); +virtual void setHeight (std::size_t height, bool adjust = true); +void setTopPadding (int top, bool adjust = true); +void setLeftPadding (int left, bool adjust = true); +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. + + +### 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(). + +
+ widget-geometry +
Figure 3. Geometry of widgets
+
+ + +```cpp +const FSize getSize() const; +const FRect& getGeometry() const; +const FRect& getTermGeometry(); +const FSize& getShadow() const; +const FRect& getGeometryWithShadow(); +const FRect& getTermGeometryWithShadow(); +virtual void setSize (const FSize& size, bool adjust = true); +virtual void setGeometry (const FRect& box, bool adjust = true); +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. + + +### Dynamic layout ### A modern terminal emulation like xterm has no fixed resolution. They offer the possibility to change the height and width of the