diff --git a/ChangeLog b/ChangeLog index e0fd1576..e9c1575f 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,7 @@ +2020-09-27 Markus Gans + * An explanation of the widget tree was added to the document + of the first steps + 2020-09-26 Markus Gans * FData improvements * The number of FObject children can now be limited with diff --git a/doc/final-cut-widget tree.svg b/doc/final-cut-widget tree.svg new file mode 100644 index 00000000..e96d08d4 --- /dev/null +++ b/doc/final-cut-widget tree.svg @@ -0,0 +1,361 @@ + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + FApplication + + + + + + FDialog + + + + + + FDialog + + + + + + FLabel + + + + + + FButton + + + + etc. + + + + + + + + + Parent: + + + Child: + + + Subchild: + + + Sub-subchild: + + + + + Application widget (= 1) + + + Main widget (= 1) + + + Widget(s) of the main widget (≥ 0) + + + Widget(s) from the parent widget (≥ 0) + + + diff --git a/doc/first-steps.md b/doc/first-steps.md index 1e1e376f..b7d5bf52 100644 --- a/doc/first-steps.md +++ b/doc/first-steps.md @@ -7,6 +7,8 @@ Table of Contents - [Basic functions](#basic-functions) +- [Widgets](#widgets) +- [Widget tree](#widget-tree) - [How to use the library](#how-to-use-the-library) - [Memory Management](#memory-management) - [Event Processing](#event-processing) @@ -55,6 +57,48 @@ emulator. It uses various optimization methods to improve the drawing speed. +Widgets +------- + +FINAL CUT has many widgets. It offers buttons, input fields, menus, and +dialog boxes that cover the most common use cases. Widgets are visual +elements that are combined to create user interfaces. Own widgets can be +easily created by creating a derived class of `FWidget` or other existing +widgets. All widgets are instances of +[FWidget](https://codedocs.xyz/gansm/finalcut/classfinalcut_1_1FWidget.html) +or its subclasses. + +A widget can contain any number of child widgets. Child widgets are displayed +in the display area of the parent widget. Window widgets based on `FWindow` +have their own virtual display area and are independent of the parent widget. + +When a parent widget is disabled, hidden, or deleted, the same operation is +used recursively to all its child widgets. The base class `FObject` implements +the self-organized object tree behavior. For example, `addChild()` removes +the child ownership from an existing parent object before assigning it to +the new target. When a child becomes deleted, the parent-child relationship +causes its reference in the parent object to be removed. An explicit +`delChild()` is no longer required here. + + +Widget tree +----------- + +An `FApplication` widget is the top-level widget of an application. It is +unique and can not have a parent widget. The class `FApplication` manages +all settings and assigns keyboard and mouse input to the different widgets. + +
+ application structure +
Figure 2. Widget tree of a FINAL CUT application
+
+ +The main widget of a FINAL CUT application is the only object that +`FApplication` can have as a child. This main widget is usually a window +object that contains all sub-widgets of the application. A sub-widget can +also be another window. + + How to use the library ---------------------- @@ -82,7 +126,7 @@ int main (int argc, char* argv[]) ```
dialog.cpp -
Figure 2. A blank dialog
+
Figure 3. A blank dialog


@@ -229,7 +273,7 @@ int main (int argc, char* argv[]) ```
memory.cpp -
Figure 3. FObject manages its child objects
+
Figure 4. FObject manages its child objects


@@ -369,7 +413,7 @@ int main (int argc, char* argv[]) ```
timer.cpp -
Figure 4. FObject::onTimer event handler
+
Figure 5. FObject::onTimer event handler


@@ -482,7 +526,7 @@ int main (int argc, char* argv[]) ```
user-event.cpp -
Figure 5. User event generation
+
Figure 6. User event generation


@@ -753,7 +797,7 @@ int main (int argc, char* argv[]) ```
callback-function.cpp -
Figure 6. Button with a callback function
+
Figure 7. Button with a callback function


@@ -816,7 +860,7 @@ int main (int argc, char* argv[]) ```
callback-lambda.cpp -
Figure 7. Button with lambda expression callback.
+
Figure 8. Button with lambda expression callback.


@@ -875,7 +919,7 @@ int main (int argc, char* argv[]) ```
callback-method.cpp -
Figure 8. Button with a callback method
+
Figure 9. Button with a callback method


@@ -996,7 +1040,7 @@ int main (int argc, char* argv[]) ```
emit-signal.cpp -
Figure 9. Callbacks with custom signals
+
Figure 10. Callbacks with custom signals


@@ -1037,7 +1081,7 @@ If you want to ignore padding spaces, you must force this with the
widget coordinates -
Figure 10. Widget coordinates
+
Figure 11. Widget coordinates


@@ -1087,7 +1131,7 @@ methods.
widget lengths -
Figure 11. Width and height of a widget
+
Figure 12. Width and height of a widget


@@ -1140,7 +1184,7 @@ absolute geometry values as a `FRect` object, you can call the method
widget geometry -
Figure 12. Geometry of widgets
+
Figure 13. Geometry of widgets


@@ -1267,7 +1311,7 @@ int main (int argc, char* argv[]) ```
size-adjustment.cpp -
Figure 13. Dynamic layout
+
Figure 14. Dynamic layout


@@ -1395,7 +1439,7 @@ int main (int argc, char* argv[]) ```
scrollview.cpp -
Figure 14. Dialog with a scrolling viewport
+
Figure 15. Dialog with a scrolling viewport