A beginner's introduction to gtk+ by red_Marvin

This is not a document to explain exactly how and why stuff works, but rather an introduction to how to use it.

Gtk+ is one, but not the only, linux equivalents of the winAPI, which means it's what you use when creating windows and buttons etc. If you use a linux distro that lets Gnome or XFCE take carer of the desktop you already use gtk+. KDE uses something else, but you should still be able to run gtk-based programs if you have the right libs installed. When developing you of course need the development libraries and fbc comes with the bi headers.

Generally one could say that gtk+ works through allocating objects (widgets), setting it's properties and then connecting your callback functions to one or more of it's signals. Each time a button is pressed the signal ”clicked” gets emitted, and if you have connected any callback functions to that button, listening to that signal, then the callback function will get executed.

If you are interested in learning and using gtk+ for your programs I strongly suggest that you bookmark this site: http://developer.gnome.org/doc/API/2.0/gtk/index.html

Here's an example that is more or less identical to one included with fbc.

        option explicit
        #include once "gtk/gtk.bi"

        declare function close_button_has_been_pressed cdecl (o as gtkObject ptr, d as gPointer ) as integer

        '--------------------

        gtk_init 0,0

        dim myWindow as gtkWidget ptr
        myWindow = gtk_window_new(GTK_WINDOW_TOPLEVEL)
        gtk_window_set_title GTK_WINDOW(myWindow), "Woot! a window! 1337"

        g_signal_connect(myWindow, "destroy", GTK_SIGNAL_FUNC(@close_button_has_been_pressed), 0)

        gtk_widget_show_all myWindow
        gtk_main()
        end 0

        '--------------------

        function close_button_has_been_pressed cdecl (o as gtkObject ptr, d as gPointer ) as integer

          print "The window is destroyed, I can't feel my legs!"

          gtk_main_quit

        end function

The program starts with a gtk_init, which I suppose is more or less like calling screen before using graphic related commands. the 0's are argc and argv parameters, which I think is used if you want to pass any extra parameters to gtk_init, I have yet to have a use for them.

Later we dim a gtkWidget ptr, and it is through them we can manipulate ha widget's appearence etc. We also create a new window widget and the GTK_WINDOW_TOPLEVEL means that it is a ”normal” window instead of the kind used on popup menus etc. Even the reference library tells you that you're not likeley to need anything else than the toplevel variant.
We also set the title of the window to something that will leave all future users in awe. You might notice the GTK_WINDOW(), which I think is a macro that cast the parameter to a window, bundled with an assert that it actually is one.

After that we make sure that, when the ”destroy” signal get's emitted for myWindow, the function close_butto(etc.) is called. Simple.

Then we of course make sure that the user of this mighty fine program can see the fruits of our labour.

When gtk_main is called, the gtk faries takes over, and starts listening to keypresses, clicking and all that stuff and makes sure all get's redrawn nicely etc.
If we at that time press the close button of the window or alt-F4 = we close the window, then the window is destroyed an deallocated, and guess what?
The ”destroy” signal is emitted, catched, and close_butto(etc.) is run!

The signal callback functions must take a certain list of parameters, slightly depending on which type of signal it is.
1 The widget the signal came from, useful if you connect different widgets' same signals to the same sub.
2 Some signal callbacks need an extra parameter here but not any of the signals we use here.
3 Some user data. If you want some extra data pass it here, the type is a gPointer which is the same as an any ptr, but you'll have to cast it to avoid warnings.
In the above program we have no extra data to pass, so I put a zero there.
Also note that all functions dealing with signals need to be declared with cdecl.

Inside the function I have put a gtk_main_quit that tells the fairies in gtk_main to go home for the day, so when the function returns to it's caller, gtk_main exits and the program execution continues on the next line, which happens to be an ”end 0”