Provided by: libgtk2-ex-formfactory-perl_0.67-0ubuntu1_all bug


       Gtk2::Ex::FormFactory::Widget - Base class for all FormFactory Widgets


         Gtk2::Ex::FormFactory::Widget->new (
           name                 => Name of this Widget,
           object               => Name of the associated application object,
           attr                 => Attribute represented by the Widget,
           label                => Label text,
           label_markup         => Boolean, indicating whether the label has markup,
           label_group          => Name of a Gtk2::SizeGroup for the label,
           widget_group         => Name of a Gtk2::SizeGroup for the widget,
           tip                  => Tooltip text,
           properties           => { Gtk2 Properties ... }
           inactive             => 'insensitive' | 'invisible',
           rules                => [ Rules for this Widget ],
           expand               => Boolean: should the Widget expand?,
           expand_h             => Boolean: should the Widget expand horizontally?,
           expand_v             => Boolean: should the Widget expand vertically?,
           scrollbars           => [ hscrollbar_policy, vscrollbar_policy ],
           signal_connect       => { signal => CODREF, ... },
           signal_connect_after => { signal => CODREF, ... },
           width                => Desired width,
           height               => Desired height,
           customize_hook       => CODEREF: Customize the underlying Gtk2 Widget,
           changed_hook         => CODEREF: Track changes made to the Widget,
           changed_hook_after   => CODEREF: Track changes made to the Widget,
           active_cond          => CODEREF: Condition for Widget being active
           active_depends       => SCALAR|ARRAYREF: Attribute(s) activity depends on


       This is an abstract base class and usually not used directly from the application. For
       daily programming the attributes defined in this class are most important, since they are
       common to all Widgets of the Gtk2::Ex::FormFactory framework.



         +--- Gtk2::Ex::FormFactory::Container
         |    +--- Gtk2::Ex::FormFactory
         |    +--- Gtk2::Ex::FormFactory::Expander
         |    +--- Gtk2::Ex::FormFactory::Form
         |    +--- Gtk2::Ex::FormFactory::HBox
         |    +--- Gtk2::Ex::FormFactory::Notebook
         |    +--- Gtk2::Ex::FormFactory::Table
         |    +--- Gtk2::Ex::FormFactory::VBox
         |    +--- Gtk2::Ex::FormFactory::Window
         +--- Gtk2::Ex::FormFactory::Button
         +--- Gtk2::Ex::FormFactory::CheckButton
         +--- Gtk2::Ex::FormFactory::CheckButtonGroup
         +--- Gtk2::Ex::FormFactory::Combo
         +--- Gtk2::Ex::FormFactory::DialogButtons
         +--- Gtk2::Ex::FormFactory::Entry
         +--- Gtk2::Ex::FormFactory::Expander
         +--- Gtk2::Ex::FormFactory::ExecFlow
         +--- Gtk2::Ex::FormFactory::GtkWidget
         +--- Gtk2::Ex::FormFactory::HPaned
         +--- Gtk2::Ex::FormFactory::HSeparator
         +--- Gtk2::Ex::FormFactory::Image
         +--- Gtk2::Ex::FormFactory::Label
         +--- Gtk2::Ex::FormFactory::List
         +--- Gtk2::Ex::FormFactory::Menu
         +--- Gtk2::Ex::FormFactory::Popup
         +--- Gtk2::Ex::FormFactory::ProgressBar
         +--- Gtk2::Ex::FormFactory::RadioButton
         +--- Gtk2::Ex::FormFactory::TextView
         +--- Gtk2::Ex::FormFactory::Timestamp
         +--- Gtk2::Ex::FormFactory::ToggleButton
         +--- Gtk2::Ex::FormFactory::VPaned
         +--- Gtk2::Ex::FormFactory::VSeparator
         +--- Gtk2::Ex::FormFactory::YesNo

         +--- Gtk2::Ex::FormFactory::ProxyBuffered


       Attributes are handled through the common get_ATTR(), set_ATTR() style accessors, but they
       are mostly passed once to the object constructor and must not be altered after the
       associated FormFactory was built.

       name = SCALAR [optional]
           Each widget has a unique name. If you don't specify it explicitly a name is generated
           automatically. You can select named widgets later by using the get_widget and
           lookup_widget methods described below.

       object = SCALAR [optional]
           The name of the object, which controls this widget. This object name must be
           registered at the Gtk2::Ex::FormFactory::Context of the Gtk2::Ex::FormFactory
           associated with this Widget.

           You may omit the object property and use a fully qualified "object.attr" notation in
           the attr attribute described beyond.  If you want to associate your Widget only with
           an object, but not to an attribute (e.g. to get the activity of a container widget
           without an associated object attribute managed automatically) just omit attr and
           specify only object here.

       attr = SCALAR [optional]
           Usually a Widget represents a specific object attribute, e.g. a text entry shows the
           current value of the attribute you specify here. How this attribute is accessed is
           defined in the Gtk2::Ex::FormFactory::Context instance.

           If you used the object property just pass the name of your attribute here, but you may
           omit object and pass "object.attr" to the attr property for convenience as well.

       label = SCALAR [optional]
           Each Widget may have an associated label. How this label is actually rendered depends
           on the Gtk2::Ex::FormFactory::Container to which this Widget was added. E.g.
           Gtk2::Ex::FormFactory::Form implements a simple two column table with the labels in
           the left and the widgets in the right column.

       label_markup = BOOLEAN [optional]
           If this is set to a true value, the label will be rendered with a HTML like markup.
           Refer to the chapter "Pango Text Attribute Markup" of the official Gtk documentation
           for details about the known markup tags.

       label_group = SCALAR [optional]
           If you have a complex layout and you want to align your labels although they are not
           part of the same container you can specify an arbitrary name of a label group here. A
           correspondent Gtk2::SizeGroup is managed automatically for you. Simply specify the
           same name for all Widgets for which you want to have the same label size.

       widget_group = SCALAR [optional]
           This is very similar to the label_group attribute. The difference is that the size
           allocated by the Widget is under control of a Gtk2::SizeGroup.

       tip = SCALAR [optional]
           Optional text of the tooltip of this Widget.

       properties = HASHREF [optional]
           This is a hash of Gtk+ properties for this Widget, e.g. you can specify { border_width
           => 5 } here to manipulate the border-width of this specific Widget. You should use
           this with care, because this breaks the strict isolation of GUI structure and
           appearance. Probably it's better to implement an own Gtk2::Ex::FormFactory::Layout
           class, where you can control appearance of your widgets in a much more generic way.

       inactive = 'insensitive' | 'invisible' [optional]
           Gtk2::Ex::FormFactory automatically manages the activity state of your Widgets.
           Specify if you want the Widget getting insensitive or invisible when the Widget is
           deactivated. This defaults to 'insensitive'.

       rules = rule | [ rule, ... ] [optional]
           Data entered by the user must apply the rules specified here. Refer to
           Gtk2::Ex::FormFactory::Rules for details about rules.

       expand = BOOL [optional]
           By default a Widget doesn't expand into the space which is avaiable from its
           container. Specify a TRUE value to activate Widget expansion. Whether the Widget
           expands vertically or horizontally depends on its Container. E.g. in a VBox it will
           expand vertically, in a HBox horizontally.

       expand_h = BOOL [optional]
       expand_v = BOOL [optional]
           Some containers can expand the Widget in both directions, e.g. a Gtk2::Table. If your
           widget is added to such a container (e.g. to a Gtk2::Ex::FormFactory::Form, which is
           implemented with a Gtk2::Table) you can specify both directions of expansion here.

           expand_h defaults to TRUE and expand_v to FALSE, or to expand if specified.

       scrollbars = [ h_policy, v_policy ] [optional]
           If you want your Widget inside a Gtk2::ScrolledWindow, simply specify the policy for
           horizontal and vertical scrollbars here. Possible values are: "always", "automatic" or

       changed_hook = CODEREF(ApplicationObject, WidgetObject) [optional]
           This code reference is called after the user changed a value of the Widget, but before
           these changes are applied to the underlying application object. The application object
           is the first argument of the call, the Widget object the second.

       changed_hook_after = CODEREF(ApplicationObject, WidgetObject) [optional]
           This code reference is called after the user changed a value of the Widget and after
           these changes are applied to the underlying application object. The application object
           is the first argument of the call, the Widget object the second.

       signal_connect = HASHREF [optional]
           Specify all your signal connections in a single hash reference. Key is the name of the
           signal, and value the callback (a static subroutine reference or a closure).

           Note: don't use this to track changes made on the GUI!  Gtk2::Ex::FormFactory manages
           this for you. If you want to be notified about changes, use the Widget transparent
           changed_hook described above.

       signal_connect_after = HASHREF [optional]
           Same as signal_connect, but signals are connected using Gtk2's signal_connect_after

       width = INTEGER [optional]
       height = INTEGER [optional]
           You can specify a desired width and/or height. Internally
           Gtk2::Widget->set_default_size is used on windows and
           Gtk2::Widget->set_size_request on all other widgets.

       customize_hook = CODEREF(Gtk2::Widget) [optional]
           This code reference is called after the Gtk2::Widget's are built. The Gtk2::Widget
           object of this Gtk2::Ex::FormFactory::Widget is the first argument of this call.

           You can use this hook to do very specific customization with this Widget. Again: use
           this with care, probably implement your own Gtk2::Ex::FormFactory::Layout class to
           control the layout.

       active_cond = CODEREF(ApplicationObject) [optional]
           Widget's activity state (visible/sensitive) is controlled by this condition resp. the
           return value of this code reference. Use this if you want to fine control the activity
           state of the widget with arbitrary conditions. Note that widgets get automatically
           inactive if the object they're bound to get's undef.

           The return value is as follows:

             0   Widget gets inactive. According to the B<inactive>
                 attribute it gets either invisible or insensitive.

             1   Widget gets active. According to the B<inactive>
                 attribute it gets either visible or sensitive.

           Or return one of these strings


           to get the corresponding widget state.

       active_depends = SCALAR | ARRAYREF [optional]
           This lists the attribute(s) the activity condition above depends on, resp. which
           attributes are variables in the condition. May point to objects or attributes (in
           "object.attr" notation).

           With this knowledge Gtk2::Ex::FormFactory is able to update the activity automatically
           if one of the corresponding objects or attributes changes.


       $widget->update ()
           Updates this specific Widget resp. sets it's state to the value from the associated
           application object attribute. In case of a Container the child widgets are not

       $widget->update_all ()
           Same as update, but containers will update their children as well.

       $widget->update_widget_activity ()
           Only update the Widget's activity state.

       $app_object_attr_value = $widget->get_object_value ([$attr])
           A convenience method to get the actual value of an associated application object
           attribute. If $attr is omitted, the default attribute is used.

       $widget->set_object_value ( [$attr, ] $value )
           A convenience method to set the actual value of an associated application object
           attribute to $value. If $attr is omitted, the default attribute is used.

       $widget->check_widget_value ()
           Checks the current Widget value against the rules provided for this Widget. An error
           dialog is opened if the rule check failed and the previous value is restored
           automatically. Nothing happens if all rules apply.

       $widget->widget_value_changed ()
           This method is called if the Widget value was changed. All Widget implementations of
           Gtk2::Ex::FormFactory must connect their specific "changed" signal to this method

       $widget->apply_changes ()
           Copy the Widget value to the associated application object attribute.  In a
           FormFactory with the sync flag set to TRUE this happens on each change. If the
           FormFactory is asynchronous it's called only when the user hit the Ok button.

       $widget->show_error_message ( message => $message, type => $type )
           Small convenience method which opens a Gtk+ error dialog with $message. $type defaults
           to 'error', but you can specify 'info', 'warning' and 'question' as well to get
           corresponding dialogs.

       $proxy = $widget->get_proxy ()
           Convenience method which returns the Gtk2::Ex::FormFactory::Proxy instance for the
           object associated with this Widget.

       $another_widget = $widget->get_widget ( $name )
           Returns the Gtk2::Ex::FormFactory::Widget object named $name of the FormFactory of
           this widget.

       $another_widget = $widget->lookup_widget ($name)
           The same as get_widget if a widget name is passed, but additionally you may
           dereference sibling widgets by passing


           This returns the $n-th sibling of this Widget, whereby $n may be a negative value.

           This method is used to lookup widgets assigned to a Gtk2::Ex::FormFactory::Label using
           the Label's for attribute.

       The following methods are used by the Gtk2::Ex::FormFactory::Layout module, so you need
       them only if you implement your own layout.

       $widget->set_gtk_widget (Gtk2::Widget)
           The Gtk2::Widget which represents the associated application object attribute, e.g.
           this is a Gtk2::Entry for a Gtk2::Ex::FormFactory::Entry widget.

       $widget->set_gtk_parent_widget (Gtk2::Widget)
           Often the real Gtk2 widget is inside a container, e.g. a Gtk2::Frame. The Gtk2 widget
           of the container needs to be set explicetly using this method.


       You can implement new widgets by subclassing Gtk2::Ex::FormFactory::Widget or

       You need to implement the following methods (not all are mandatory, e.g.  if your Widget
       is a container actually doesn't representing any application object value, you can omit
       most of them):

       $self->get_type() [mandatory]
           This returns the short name of your Widget. It should be lower case and may contain
           underscores. If you wrap an existent Gtk2 widget try to derive the type name from the
           widget's name.

       $self->object_to_widget [optional]
           This method transfers the value of the associated application object attribute to your
           widget. You may use the convenience method $self->get_object_value() to get the value
           of the default attribute of this widget.

       $self->widget_to_object [optional]
           This method transfers the value of your widget to the associated application object
           attribute. You may use the convenience method $self->set_object_value($value) to set
           the value of the default attribute of this widget.

       $self->empty_widget [optional]
           This method sets your widget to an empty value, e.g. an Image widget should display
           nothing, or the text of some sort of text entry should be deleted.

       $self->backup_widget_value [optional]
           This method makes a backup of the current widget value.  Gtk2::Ex::FormFactory::Widget
           has a convenience method for setting the backup value you may use:
           $self->set_backup_widget_value($value).  If your widget has a more complex value,
           which can't be covered by a single scalar, the implementation must care about this.

       $self->restore_widget_value [optional]
           This restores a value from the backup created with $self->backup_widget_value().

       $self->get_gtk_check_widget [optional]
           Returns the Gtk widget to which the focus-in and focus-out signals should be connected
           to for rule checking. Defaults to $self->get_gtk_widget().

       $self->get_widget_check_value [optional]
           Currently Gtk2::Ex::FormFactory::Rules can only check a single scalar value. Your
           widget must implement this method to return the correspondent value.

       $self->connect_changed_signal [optional]
           This method must connect the "changed" signal of the specific Gtk2 widget your
           implementation uses. The connected callback must call the
           $self->widget_value_changed() method, so Gtk2::Ex::FormFactory can track all changes
           on the GUI.

       $gtk_widget = $self->get_gtk_signal_widget() [optional]
           This defaults to $self->get_gtk_widget() and returns the Gtk2 widget to which
           additional user specified signals should be connected.

       $gtk_widget = $self->get_gtk_properties_widget() [optional]
           This defaults to $self->get_gtk_widget() and returns the Gtk2 widget which should get
           the properties defined for this Gtk2::Ex::FormFactory widget. This is useful if the
           actual GtkWidget is not the gtk_widget (e.g. Gtk2::Ex::FormFactory::Window needs this,
           since it's finally a VBox, but you want to apply properties like default_width to the
           GtkWindow and not to the VBox).

       $widgets_lref = $self->get_gtk_tip_widgets() [optional]
           This defaults to [ $self->get_gtk_widget() ] and returns a list reference of Gtk2
           widgets which should get a tooltip, if the user specified one.

       $self->has_additional_attrs() [optional]
           If your widget supports additional application object attributes which should be
           managed automatically, this method returns a list reference of symbolic names for
           these attributes. Please refer to the implementation of Gtk2::Ex::FormFactory::List,
           which uses this feature to store the actually selected item(s) in the application

       BOOL = $self->has_label() [optional]
           This defaults to 0. Set this to 1 if your widget manage it's label by itself (like a
           Gtk2::CheckBox does).

   Creating the Gtk2 widget(s)
       You probably recognized that a method which actually builds the Gtk2 widgets of your
       widget is missing here. This is covered by the Gtk2::Ex::FormFactory::Layout module. So
       create your own layouter and add the $layouter->build_TYPE($widget) method for your widget
       to it. If your widget is a container you also need to implement at least the generic
       $layouter->add_widget_to_TYPE method. For details about this please refer to the
       documentation of Gtk2::Ex::FormFactory::Layout.

       Nevertheless, if your widget is very specific to your application, e.g.  because it
       displays a very specific data structure, creating your own Layout module just for that
       purpose is somewhat involved. In that case you can implement this method:

           If implemented this method is called to actually create the Gtk2 widgets for your
           Gtk2::Ex::FormFactory widget.


        Joern Reder <joern at zyn dot de>


       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.