Glade-- User's Guide (revised for 1.1.x)

Glade-- is a backend to glade and glade-2. Glade is a GUI builder for the Gimp Toolkit (gtk). Glade is entirely written in C. It operates on an XML file and can output C sourcecode. Glade-- is written in C++ and makes use of recent C++ features such as the STL.

As you might already know there are different versions of gtk+ around:

• 1.2: the old stable release, standard between 1999 and 2002. This corresponds to gnome 1.2 and 1.4 and gtk-- 1.2. The matching glade version is 0.6.5. It has a lot of drawbacks compared to 2.2 [no pkgconfig, no gdk-pixbuf, no unicode, no model/view/controller concept ...]
• 2.2: the new stable release, and upcoming standard. This is the base of gnome2 and gtkmm2 (2.2 silently replaced 2.0 in 2002.). The corresponding glade-2 version is 1.1.3. Sadly 1.2 and 2.2 are not compatible.

As a side note I recommend using a version control system for your projects, e.g. CVS, subversion or bitkeeper. It makes source code management really easy and if you by chance delete a file or overwrite it you can easily get it back. You might even get your old files back if your design decisions misleaded you. Besides that you can light-heartedly delete no longer necessary files, you can get their content back if you need to.

Table of contents

Create your glade file

For textual input you might prefer option menus or combo boxes.
You should also take a look at the fancy SearchCombo widget of the gtk--addons I put to cvs.gnome.org.

! You will not see the C++ code options in glade unless you select C++ as your language. (Project options)

Think about partitioning complex windows into substructures. Toplevel windows always come in their own file (and their own class). Signal callback functions are part of the topmost widget's class.
Feel free to break this via the 'separate class' or 'separate_file' switch. I recommend up to ten to twenty callbacks in one class. But on the other hand you lose the ability to easily access widgets outside your class if you partition too much.

Then think whether you need to access a widget in your program. If you need to access it (e.g. read or alter values) inside your scope (class) declare it as protected. (Attaching signals to widget does not count as a need to access it)

If you need to access it outside your scope, mark it as public. Then include the appropriate header file, glade-- has generated a GMM_* macro for easy access:
   GMM_WINDOW1->show();
But remember this breaks all OO design rules! I do not recommend it. A better way is to pass the widget (or it's containing class) to other classes' ctors.

Create your initial program files (glade--)

Simply invoke glade-- by pressing the gear's button in glade or by hand:
    glade-- <project file>

Note that some glade-- options are only available from the command line.

Glade-- will generate the following files:

• myprog.cc: This file contains a sample main function. Simple. Extend it up to your choice.
• autogen.sh: Invoking this shell script configures and compiles the program (standard for gnome projects)
• Makefile.am: automake/autoconf really are your friends! Get used to them. I admit that m4 is horrible though.
• glademm_support.hh, glademm_support.cc: these files contain helper functions
• window1_glade.hh: This is the GUI classes declaration file. For the GUI-class name '_glade' is appended to the widget name. Each class contains its child-widgets' declarations as members.
  
Do not modify this file!
• window1.hh: These are your program's classes, no GUI parts beside the derivation. Signal handlers are declared as member functions (private by default), this is the place to add your program's variables and functions (besides including your own classes of course). Glade-- will not add new callbacks to this file, it will not change it. Look into window1.hh_new for the signature.
• window1_glade.cc: This file contains the constructors and destructors for the GUI part of your program. Do not edit! You might take a look here to see what the code looks like.
• window1.cc: This file contains your constructors, destructors, signal handlers, custom functions etc. Take them out to other files, it would not matter (as long as you link them into the program, remember to add new files to the Makefile.am). Good stuff for a constructor is reading of data (e.g. database interaction) or anything else which has to be done before the user starts interacting with your program.

Signal handlers react to user's actions. Writing a program in this manner is not very difficult. Try yourself!

You changed the glade file

• myprog.cc_new: contains the new main function, most likely new toplevel widgets have been added, insert the variable declaration into your main file.
• Makefile.am_new: New toplevel widgets? Add the corresponding .o files to your Makefile.am
• window1.hh_new: New classes? Add the corresponding class declaration to your header file.

New signal handlers? Add the handler declaration to the corresponding class.
Other changes should not affect this file.
• window1.cc_new: You divided a class (separate class/separate file)? Move the corresponding Signal callbacks to the right scope!

New signal handlers? Add the handler stub and fill it.

diff window1.hh window1.hh_new | less

The widget map (not recommended, see here)

User types

Using glade-- generated widgets within another context (components, user defined widgets)

• Create another toplevel window (the name determines the source file name), I usually set visible to off and title to '' to remember that this is a dummy window (you don't have to compile these four files). Name the windows child widget to represent your type! Mark it as 'separate class' and 'separate file'
• Pass it through glade--.

You might as well delete the empty window's files.
• Use it like any other custom widget (put your widget's name into the 'creation function' part) (see above)

Strengths of glade--

• Used well, glade-- will not overwrite any of your code. Designing the GUI and programming the application is seperated. You might also name this a weakness ;-)
• Glade-- is pure C++. You can customize the indentation style of its output via the 'SourceWriter' class.

You can change the naming of files/widgets via the 'Naming' class.
Glade-- now inherits widget code generation functions (in the src/writers dir).

Weaknesses of glade--

• Using different file naming schemes is not yet supported. If you really need it, tell me. You can use a different header extension (e.g. .h with --header-suffix h)
• SourceWriter is not yet runtime customizable (indentation of generated programs).
• gnomemm support is still under development (especially 2.x)
• widgets with duplicated names really confuse glade-- (or your compiler)! And it will choke on widget names with spaces!

Future development

• more and more gnome support
• automatized source code updates (see 'You changed the glade file')

How to get it

Further reading