Getting Started with CTK+: CTK+ 3 Reference Manual

## Getting Started with CTK+

CTK+ is a widget toolkit. Each user interface created by CTK+ consists of widgets. This is implemented in C using GObject, an object-oriented framework for C. Widgets are organized in a hierachy. The window widget is the main container. The user interface is then built by adding buttons, drop-down menus, input fields, and other widgets to the window. If you are creating complex user interfaces it is recommended to use CtkBuilder and its CTK-specific markup description language, instead of assembling the interface manually. You can also use a visual user interface editor, like Glade.

CTK+ is event-driven. The toolkit listens for events such as a click on a button, and passes the event to your application.

This chapter contains some tutorial information to get you started with CTK+ programming. It assumes that you have CTK+, its dependencies and a C compiler installed and ready to use. If you need to build CTK+ itself first, refer to the Compiling the CTK+ libraries section in this reference.

## Basics

To begin our introduction to CTK, we'll start with a simple signal-based Ctk application. This program will create an empty 200 × 200 pixel window.

Create a new file with the following content named `example-0.c.`

    #include <ctk/ctk.h>

    static void
    activate (CtkApplication *app,
              gpointer        user_data G_GNUC_UNUSED)
    {
      CtkWidget *window;

      window = ctk_application_window_new (app);
      ctk_window_set_title (CTK_WINDOW (window), "Window");
      ctk_window_set_default_size (CTK_WINDOW (window), 200, 200);
      ctk_widget_show_all (window);
    }

    int
    main (int    argc,
          char **argv)
    {
      CtkApplication *app;
      int status;

      app = ctk_application_new ("org.ctk.example", G_APPLICATION_DEFAULT_FLAGS);
      g_signal_connect (app, "activate", G_CALLBACK (activate), NULL);
      status = g_application_run (G_APPLICATION (app), argc, argv);
      g_object_unref (app);

      return status;
    }

You can compile the program above with GCC using:

`gcc `pkg-config --cflags ctk+-3.0` -o example-0 example-0.c `pkg-config --libs ctk+-3.0``

For more information on how to compile a CTK+ application, please refer to the Compiling CTK+ Applications section in this reference.

All CTK+ applications will, of course, include `ctk/ctk.h`, which declares functions, types and macros required by CTK+ applications.

Even if CTK+ installs multiple header files, only the top-level `ctk/ctk.h` header can be directly included by third party code. The compiler will abort with an error if any other header is directly included.

In a CTK+ application, the purpose of the `main()` function is to create a CtkApplication object and run it. In this example a CtkApplication pointer named `app` is called and then initialized using `ctk_application_new()`.

When creating a CtkApplication you need to pick an application identifier (a name) and input to `ctk_application_new()` as parameter. For this example `org.ctk.example` is used but for choosing an identifier for your application see this guide. Lastly `ctk_application_new()` takes a GApplicationFlags as input for your application, if your application would have special needs.

Next the activate signal is connected to the `activate()` function above the `main()` functions. The `activate` signal will be sent when your application is launched with `g_application_run()` on the line below. The `ctk_application_run()` also takes as arguments the pointers to the command line arguments counter and string array; this allows CTK+ to parse specific command line arguments that control the behavior of CTK+ itself. The parsed arguments will be removed from the array, leaving the unrecognized ones for your application to parse.

Within g_application_run the `activate()` signal is sent and we then proceed into the `activate`() function of the application. Inside the `activate()` function we want to construct our CTK window, so that a window is shown when the application is launched. The call to `ctk_application_window_new()` will create a new CtkWindow and store it inside the `window` pointer. The window will have a frame, a title bar, and window controls depending on the platform.

A window title is set using `ctk_window_set_title()`. This function takes a CtkWindow* pointer and a string as input. As our `window` pointer is a CtkWidget pointer, we need to cast it to CtkWindow*. But instead of casting `window` via `(CtkWindow*)`, `window` can be cast using the macro ``CTK_WINDOW()``. ``CTK_WINDOW()`` will check if the pointer is an instance of the CtkWindow class, before casting, and emit a warning if the check fails. More information about this convention can be found here.

Finally the window size is set using ctk_window_set_default_size and the window is then shown by CTK via `ctk_widget_show_all()`.

When you exit the window, by for example pressing the X, the `g_application_run()` in the main loop returns with a number which is saved inside an integer named "status". Afterwards, the CtkApplication object is freed from memory with `g_object_unref()`. Finally the status integer is returned and the CTK application exits.

While the program is running, CTK+ is receiving events. These are typically input events caused by the user interacting with your program, but also things like messages from the window manager or other applications. CTK+ processes these and as a result, signals may be emitted on your widgets. Connecting handlers for these signals is how you normally make your program do something in response to user input.

The following example is slightly more complex, and tries to showcase some of the capabilities of CTK+.

In the long tradition of programming languages and libraries, it is called Hello, World.

Example 1. Hello World in CTK+

Create a new file with the following content named example-1.c.

    #include <ctk/ctk.h>

    static void
    print_hello (CtkWidget *widget G_GNUC_UNUSED,
                 gpointer   data G_GNUC_UNUSED)
    {
      g_print ("Hello World\n");
    }

    static void
    activate (CtkApplication *app,
              gpointer        user_data G_GNUC_UNUSED)
    {
      CtkWidget *window;
      CtkWidget *button;
      CtkWidget *button_box;

      window = ctk_application_window_new (app);
      ctk_window_set_title (CTK_WINDOW (window), "Window");
      ctk_window_set_default_size (CTK_WINDOW (window), 200, 200);

      button_box = ctk_button_box_new (CTK_ORIENTATION_HORIZONTAL);
      ctk_container_add (CTK_CONTAINER (window), button_box);

      button = ctk_button_new_with_label ("Hello World");
      g_signal_connect (button, "clicked", G_CALLBACK (print_hello), NULL);
      g_signal_connect_swapped (button, "clicked", G_CALLBACK (ctk_widget_destroy), window);
      ctk_container_add (CTK_CONTAINER (button_box), button);

      ctk_widget_show_all (window);
    }

    int
    main (int    argc,
          char **argv)
    {
      CtkApplication *app;
      int status;

      app = ctk_application_new ("org.ctk.example", G_APPLICATION_DEFAULT_FLAGS);
      g_signal_connect (app, "activate", G_CALLBACK (activate), NULL);
      status = g_application_run (G_APPLICATION (app), argc, argv);
      g_object_unref (app);

      return status;
    }

You can compile the program above with GCC using:

`gcc `pkg-config --cflags ctk+-3.0` -o example-1 example-1.c `pkg-config --libs ctk+-3.0``

As seen above, example-1.c builds further upon example-0.c by adding a button to our window, with the label "Hello World". Two new CtkWidget pointers are declared to accomplish this, `button` and `button_box`. The button_box variable is created to store a CtkButtonBox which is CTK+'s way of controlling the size and layout of buttons. The CtkButtonBox is created and assigned to `ctk_button_box_new()` which takes a CtkOrientation enum as parameter. The buttons which this box will contain can either be stored horizontally or vertically but this does not matter in this particular case as we are dealing with only one button. After initializing button_box with horizontal orientation, the code adds the button_box widget to the window widget using `ctk_container_add()`.

Next the `button` variable is initialized in similar manner. `ctk_button_new_with_label()` is called which returns a CtkButton to be stored inside `button`. Afterwards `button` is added to our `button_box`. Using g_signal_connect the button is connected to a function in our app called `print_hello()`, so that when the button is clicked, CTK will call this function. As the `print_hello()` function does not use any data as input, NULL is passed to it. `print_hello()` calls `g_print()` with the string "Hello World" which will print Hello World in a terminal if the CTK application was started from one.

After connecting `print_hello()`, another signal is connected to the "clicked" state of the button using `g_signal_connect_swapped()`. This functions is similar to a `g_signal_connect()` with the difference lying in how the callback function is treated. `g_signal_connect_swapped()` allow you to specify what the callback function should take as parameter by letting you pass it as data. In this case the function being called back is `ctk_widget_destroy()` and the `window` pointer is passed to it. This has the effect that when the button is clicked, the whole CTK window is destroyed. In contrast if a normal `g_signal_connect()` were used to connect the "clicked" signal with `ctk_widget_destroy()`, then the `button` itself would have been destroyed, not the window. More information about creating buttons can be found here.

The rest of the code in example-1.c is identical to example-0.c. Next section will elaborate further on how to add several CtkWidgets to your CTK application.