finalcut/doc/first-steps.md

First steps with the Final Cut widget toolkit

How to use the library

At the beginning of this introduction to the Final Cut we will start with a small example.

The following example creates an empty 30×10 character dialog.

File: dialog.cpp

#include <final/final.h>

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: You can close the dialog with the mouse, Shift+F10 or Ctrl+^.)

After entering the source code in dialog.cpp you can compile the above program with gcc:

g++ -O2 -lfinal dialog.cpp -o dialog

How it works

#include <final/final.h>

All final cut programs must include the final.h header.

finalcut::FApplication app(argc, argv);

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. You must create an application object before you can create a widgets object.

The next line

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.

dialog.setText ("A dialog");

The title bar of the dialog box gets the text "A dialog".

dialog.setGeometry (25, 5, 30, 10);

The dialog window gets a width of 30 and a height of 10 characters. The position of the window in the terminal is at x=25 and y=5 (note: x=1 and y=1 represents the upper left corner).

app.setMainWidget(&dialog);

The dialog object was now selected as the main widget for the application. When you close the main widget, the entire application quits.

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.

return app.exec();

The last line calls exec() to start the application and return the result to the operating system. The started application enters the main event loop. This loop does not end until the window is not closed.