diff --git a/ChangeLog b/ChangeLog index bd418235..63522064 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,5 +1,6 @@ 2018-09-24 Markus Gans * Stricter use of the keyword virtual + * Add a first steps document 2018-09-20 Markus Gans * Added pkg-config file finalcut.pc diff --git a/doc/first-steps.md b/doc/first-steps.md new file mode 100644 index 00000000..3ec0d26f --- /dev/null +++ b/doc/first-steps.md @@ -0,0 +1,100 @@ + +First steps with the Final Cut widget toolkit +============================================= + + +How to use the library +---------------------- + +At the beginning of this introduction to the Final Cut usage, +we start with a little example. + +It creates an empty 30×10 character dialog. + +**File:** *dialog.cpp* +```cpp +#include + +int main (int argc, char* argv[]) +{ + finalcut::FApplication app(argc, argv); + finalcut::FDialog dialog(&app); + dialog.setText ("A dialog"); + dialog.setGeometry (25, 5, 30, 10); + app.setMainWidget(&dialog); + dialog.show(); + return app.exec(); +} +``` +*(Note: Use mouse or Shift+F10 or +Ctrl+^ to close the dialog)* + + +After entering the source code in *dialog.cpp* you can compile +the above program with gcc: +```cpp +g++ -O2 -lfinal dialog.cpp -o dialog +``` + + +How it works +------------ + + +```cpp +#include +``` +All final cut programs must include the *final.h* header. + +```cpp +finalcut::FApplication app(argc, argv); +``` +In this line creates the `finalcut::FApplication` object `app` with +the command line arguments `argc` and `argv`. This object manages +the application main event loop. It receives keyboard and mouse events +and sends them to the target widgets. Before widgets can be created, +an application object must be created! Only one `finalcut::FApplication` +object should be created. + +The next line +```cpp +finalcut::FDialog dialog(&app); +``` +creates the `finalcut::FDialog` object `dialog` with the object `app` +as parent object. The `finalcut::FDialog` class is the base class for +creating dialog windows. + +```cpp +dialog.setText ("A dialog"); +``` +The title bar of the dialog box gets the text "A dialog". + +```cpp +dialog.setGeometry (25, 5, 30, 10); +``` +The dialog window geometry is set to a width of 30 characters and +a height of 10 characters. The window is positioned in the terminal +at the positions x=25 and y=5. (Note: x=1 and y=1 represents the upper +left corner ) + +```cpp +app.setMainWidget(&dialog); +``` +The `dialog` object is selected as the main widget for the application. +When the user closes a main widget, the application exits. + +```cpp +dialog.show(); +``` +A window or widget is not visible directly after its creation. +Only the call of `show()` makes it (and its child objects, +if available) visible. + +```cpp +return app.exec(); +``` +The last line calls `exec()` to start the application and return +the result to the operating system. When the application starts, +it enters the main event loop. This loop doesn't end until the +window/application is closed. +