NAME

       Gtk2::Ex::FormFactory::Layout - Do layout in a FormFactory framework

SYNOPSIS

         package My::Layout;

         use base qw/Gtk2::Ex::FormFactory::Layout/;

         sub build_form         { ... }
         sub add_widget_to_form { ... }
         ...

         package main;

         $ff = Gtk2::Ex::FormFactory->new (
           layouter => My::Layout->new(),
           ...
         );

DESCRIPTION

       This class implements the layout of Containers and their Widgets in a
       Gtk2::Ex::FormFactory framework. "Layout" means, how are the widgets aligned to each
       other, how much space is between them, how are titles rendered, how labels, etc.

       The idea behind Gtk2::Ex::FormFactory::Layout is to have a unique point in a GUI
       application which actually implements these things. The advantage of this approach is
       obvious: the implementation is very generic and if you want to change layout things you
       subclass from Gtk2::Ex::FormFactory::Layout and implement your changes there, and not at
       hundreds of spots distributed over the source code of your application.

       The natural result: a consistent looking GUI.

SUBCLASSING

       As described above implementing your own layout module starts with subclassing from
       Gtk2::Ex::FormFactory::Layout. To use your layout implementation set an object of your
       class as layouter in your Gtk2::Ex::FormFactory objects.

       Gtk2::Ex::FormFactory::Layout mainly defines two sorts of methods.

   BUILD METHODS
       The names of the methods are derived from the Widget's short names (which can be retrieved
       with $widget->get_type), with a prepended build_, e.g.:

         build_form  ( ... )
         build_label ( ... )
         build_table ( ... )

       The method prototype looks like this:

       $layout->build_TYPE ($widget)
           $widget is the actual Gtk2::Ex::FormFactory::Widget, e.g.  Gtk2::Ex::FormFactory::Form
           for build_form($form).

       The build_TYPE method actually creates the necessary Gtk2 widgets, e.g. a Gtk2::Table for
       a Gtk2::Ex::FormFactory::Form and adds these to the FormFactory's widget instance using
       the set_gtk_widget() and set_gtk_parent_widget() methods of Gtk2::Ex::FormFactory::Widget.

       Call $widget->set_gtk_widget($gtk_widget) for the primary Gtk2 widget which directly
       displays the value in question, e.g. a Gtk2::Entry if you're dealing with a
       Gtk2::Ex::FormFactory::Entry.

       If you like to do more layout things which require to add the primary Gtk2 widget to a
       container, e.g. a Gtk2::Frame, you must call
       $widget->set_gtk_parent_widget($gtk_parent_widget) with the most top level container
       widget.

       Note: the implemenations of all the FormFactory's widgets expect a specific gtk_widget to
       be set. If you like to change the primary Gtk widget you need to create your own
       Gtk2::Ex::FormFactory::Widget for this, because the default implemention most probably
       won't work with a another Gtk2::Widget.

   ADD...TO... METHODS
       The second type of methods are so called add-to methods, which place a widget inside a
       container. The prototye is as follows:

       $layout->add_TYPE_to_TYPE ($widget, $container)
           $widget is the actual Gtk2::Ex::FormFactory::Widget, e.g.  Gtk2::Ex::FormFactory::Form
           for build_form($form).

       Examples:

         add_form_to_window ( ... )
         add_table_to_form  ( ... )

       This way you can adjust layout at a very detailed level, but you need not. E.g. the
       implementation of these methods is most likely the same:

         add_entry_to_form ( ... )
         add_popup_to_form ( ... )

       because the implemenation mainly depends on the form (the container widget) and not on the
       widget which is added to the form.

       That's why Gtk2::Ex::FormFactory::Layout knows a default mechanism: if no add-to method is
       found for a specific widget/container pair, a generic default implementation is used
       instead. These are named as follows:

         add_widget_to_window ( ... )
         add_widget_to_form   ( ... )
         add_widget_to_table  ( ... )
         add_widget_to_vbox   ( ... )
         ...

       For a new Container you just need to implement the generic add_widget_to_TYPE method, and
       everything will work. If you want to slightly modify the implementation for specific child
       widgets, you implement only the methods for these and you're done.

       For a example for such a specific add-to message refer to add_menu_to_window() which
       attaches the menu without any space around it. The default of a
       Gtk2::Ex::FormFactory::Window is to have some spacing, which looks ugly around a menu.

OBJECT HIERARCHY

         Gtk2::Ex::FormFactory::Layout

ATTRIBUTES

       This class has not attributes.

AUTHORS

        Joern Reder <joern at zyn dot de>

COPYRIGHT AND LICENSE

       Copyright 2004-2006 by Joern Reder.

       This library is free software; you can redistribute it and/or modify it under the terms of
       the GNU Library General Public License as published by the Free Software Foundation;
       either version 2.1 of the License, or (at your option) any later version.

       This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY;
       without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
       See the GNU Library General Public License for more details.

       You should have received a copy of the GNU Library General Public License along with this
       library; if not, write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
       Boston, MA  02111-1307 USA.