Enough buzzwords

The straight approach often is to code all the stuff by hand or "draw" all widgets using Glade. At any rate you need to take care of:

• Consistent look and feel, e.g. labels should be bold and properly aligned to the widgets; the widgets iteslf should have some space around them, buttons should always be aligned to the form above etc.
• Initializing the widgets with the actual content of your configuration data
• Either connecting a lot of signals to track the changes the user made. This would apply all changes straight to your internal data structure, which may make implementing the Cancel button difficult or impossible
• Or grabbing all (changed) data from the widgets, when the user hit the Ok button resp. simply close the window, when the user hit the Cancel button

That's a lot of stuff, which needs to be repeated for every single dialog in your application. No fun anymore.

Gtk2::Ex::FormFactory will do the boring stuff for you. That's how it works:

Register your objects to the Context

  my $context = Gtk2::Ex::FormFactory::Context->new;
  $context->add_object (
    name   => "config",
    object => $config_object
  );

$config_object has at least the following methods in our example below:

  - get_data_dir()
  - get_selected_page()
  - set_data_dir()
  - set_selected_page()

The Context is a layer which encapsulates the methods of accessing your object's attributes. Also the Context knows about relationships between objects and/or their attributes, so it's able to handle correspondent updates on the GUI side automatically. We will discuss more details of Gtk2::Ex::FormFactory::Context later in this document.

Define the structure of your GUI

  my $ff = Gtk2::Ex::FormFactory->new (
    context => $context,
    content => [
      Gtk2::Ex::FormFactory::Window->new(
        title   => "Preferences",
        content => [
          Gtk2::Ex::FormFactory::Notebook->new (
            attr    => "config.selected_page",
            content => [
              Gtk2::Ex::FormFactory::VBox->new (
                title   => "Filesystem",
                content => [
                  Gtk2::Ex::FormFactory::Form->new (
                    content => [
                      Gtk2::Ex::FormFactory::Entry->new (
                        attr   => "config.data_dir",
                        label  => "Data Directory",
                        tip    => "This directory takes all your files.",
                        rules  => "writable-directory",
                      ),
                    ],
                  ),
                ],
              ),
            ],
          );
          Gtk2::Ex::FormFactory::DialogButtons->new
        ],
      ),
    ],
  );
  
  $ff->open;    # actually build the GUI and open the window
  $ff->update;  # fill in the values from $config_object

So now you defined that you want to have a text entry, which contains a valid writable directory name, which should be inside a form on a notebook page. No details about the exact layout yet, this is just the strucure of your dialog

But how is this rendered?

The Layout module mainly consists of two types of methods

Methods for building a widget

build_TYPE() methods for each FormFactory widget type (Entry, SelectList, Popup, Foo etc.) you use in your dialog. These have the Gtk2 code actually necessary to create the corresponding Gtk2 widgets.

Methods for adding a widget to a container

These are the so called add_WIDGET_to_CONTAINER() methods, which specify how a particular widget type is added to a particular container type. E.g. they're responsible for consistent looking labels beside widgets etc.

Because the details of adding a widget mainly depend on the container the widget is added to, there are generic methods for adding arbitrary widgets to a container. If there is no specific method for a widget type this generic method is called instead.

Layout methods for our example

  build_window           => creates a Gtk2::VBox in a Gtk2::Window    
  build_notebook         => creates a Gtk2::Notebook                   
  build_form             => creates a Gtk2::Table (2 columns)         
  build_entry            => creates a Gtk2::Entry                      
  build_dialog_buttons   => creates a ButtonBox with Ok/Apply/Cancel  

  add_widget_to_form     => adds entry to table, label in 1st column  
  add_widget_to_notebook => adds form to notebook with tab title            
  add_widget_to_window   => adds notebook and buttonbox to the window

If you regularly code applications with Gtk2 you know, that none of this tasks is rocket science. But you have a lot of parameters for each widget in question to take care of (simply think of the border_width property which may lead to an ugly misaligned mess, if you don't handle it really consistently)

Because you define this tasks at a single point in your program, it's really easy to create a consistently looking application. Or to change the look quickly. E.g. you decide to put a frame around all your forms? Just change one method - build_form() - and you're done!

Huh, a lot of new Widget classes to learn!

Using the builtin widgets is really easy. They all ship with a manual page describing their specific attributes, which usualy isn't much.

Also Gtk2::Ex::FormFactory has some nifty wrappers for really inconvenient Gtk2 widgets, like Gtk2::Table. Take a look at Gtk2::Ex::FormFactory::Table to learn how easy programming complex table layouts can be. Or look at Gtk2::Ex::FormFactory::Image which is a nice image widget which resizes the image automatically in configurable ranges.

Building your own FormFactory widgets

• Define a short name for the type (e.g. "entry" for a Gtk2::Entry - the Layout->add_X_to_Y() methods are derived from the short name)
• Transfer the object's attribute value to the widget
• Transfer the widget's value to the object's attribute
• Connect the 'changed' signal for a synchronized dialog, e.g. if you want to react immedately on user input

What the widget and object "value" actually is (a scalar, hash, array or complex structure) may be arbitrarly defined. How object attributes are accessed, is defined in the Context module. Our example uses the default set_foo(), get_foo() style accessors, but there are more methods up to defining callbacks, which can do very complex lookups.

Data consistency

Change an object attribute: the correspondent GUI widgets will update automatically. The user entered data to a text entry: the object attribute associated with this entry will automatically get the new text.

Gtk2::Ex::FormFactory must know your application's objects very well to do such a magic. That's what the Gtk2::Ex::FormFactory::Context module is good for, mentioned shortly at the top of our example.

Abstraction from your application's objects

When you register your object to the Context, you may specify how attributes are accessed by setting prefixes for read/write accessors.

You may even override methods inside the Context by specifying correspondent closures, which are called instead of the original method.

Also objects in terms of the Context module may be abstract things like "The currently selected disc from the currently selected artist", not only a simply hardwired object reference. This is done by calling a closure returning the actual object instead of using a hardwired object.

This way dependend widgets update automaticly, as soon as the correspondent selection changes, e.g. updating a list of CD titles when switching to another disc in an imaginary CD database program.

Widget consistency

Gtk2::Ex::FormFactory manages visibility and sensivity of your widgets automatically for you once you registered the correspondent dependencies at the Context. E.g. if there currently is no CD album selected, the corresponding fields are greyed out automatically, including the field labels.

Data validity

Extensibility

• Define your own FormFactory widgets, by simply using the base class Gtk2::Ex::FormFactory::Widget resp. Gtk2::Ex::FormFactory::Container. No matter how complex your widget is as long as you provide correspondent object attribute accessors, which transfer the widget's state to the object and vice versa.
• Define your own FormFactory Layout module, by deriving from the default Layout implementation and passing a correspondent object to the FormFactory constructor.
• All items in your FormFactory have a name, which will be set by default or to a value, you pass to the item's constructor. This way your Layout implementation can even do very special things for very special widgets, without the need of creating an extra Widget module for this.
• You can request any Gtk widget from a FormFactory widget by name to do further manipulation, although you should consider doing this inside your Layout implementation, to keep the "single point of layout" rule.