Glade-- V0.5 User's Guide

Glade-- is a backend to glade. 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 a side note I recommend using CVS. It makes source code management really easy and if you by chance delete a file or overwrite it you can easily get it back. And, opposed to SCCS, it doesn't bloat your working directory with it's files. You might even get your old files back if your design decisions misleaded you. Besides that you can light-heartedly delete unecessary files, you can get them back.

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.
Beware, stock glade does not support it (but gtk--addons come with a patch at hand).

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

I recommend putting all your widgets on the heap (use_heap=true, -p option for glade--). Though current glade doesn't default to this behaviour. You might take a text editor and replace each '<widget>' by
'<widget><cxx_use_heap>True</cxx_use_heap>'. Loading and saving this file in glade will reindent it.

Then think about partitioning complex windows into substructures. Toplevel windows always come in an own file (and an 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.

Then think whether you need to access a widget in your program. If you need to access it inside your scope (class) declare it as protected.
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();
 

Create your initial program files (glade--)

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

Some options are only available from the command line:
'-s' gives you some programming examples for signals and widget modification
'-p' puts widgets into the heap. [This is important for large projects. The total size of a structure with virtual functions can not exceed 32k on x86 computers. Since gtk-- is full of virtual function calls putting all widgets into one memory chunk is not advisable.]
'-A' disables autoconf/automake. For small projects these are overkill. Also, gnome automake support is not yet available.

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
• glademm_support.hh, glademm_support.cc: these files contain the widget map and (if needed) functions for radio group lookup.
• window1_glade.hh: This is the GUI classes declaration file. For the class name the widget name's first letter is capitalized and '_Glade' is appended.

Each class contains its child-widgets' declarations as members (widget names converted to lowercase).
Do not modify this file!
• window1.hh: These are your program's classes. Signal handlers are declared as member functions, this is the place to add your program's variables and functions (besides creating your own classes of course).
• 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. Though add these files to the Makefile. 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!

! Do not forget to delete glade-- V0.2's 'connect_to_method's from your Constructors if you migrate your programs to V0.5. They went into the window1_glade.cc file!

You changed the glade file

• myprog.cc_glade: contains the new main function, most likely new toplevel widgets have been added, insert the variable declaration into your main file.
• Makefile_glade: New toplevel widgets? Add the corresponding .o files to your Makefile
• window1.hh_glade: 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_glade: 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_glade | less

The widget map

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. Name the windows child widget to represent your type! Mark it as 'separate class' and 'separate file'
• Pass it through glade--.

You might well delete the window's files.
• Use it like any other custom widget (put your widget's name into the 'creation function' part) (kind of abuse)

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 supported (without patching glade--). If you need it, tell me.
• SourceWriter is not yet runtime customizable (indentation of generated programs).
• gnome support is under development
• widgets with duplicated names really confuse glade--!

Future development

• full gnome support
• a libglade--
• automatized source code updates (see 'You changed the glade file')

How to get it