|  +-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::List - A List in a FormFactory framework


  Gtk2::Ex::FormFactory::List->new (
    attr_select        => Attribute name for selection tracking,
    attr_select_column => Use this column's value to store in attr_select
    columns            => Titles of the list columns,
    types              => Types of the list columns,
    editable           => Which columns are editable?,
    visible            => Which columns are visible?
    selection_mode     => Selection mode of this list,
    no_header          => Omit header?
    update_selection_only => Boolean, whether updates should only
                             change the selection, not the list
                             of values,
    Gtk2::Ex::FormFactory::Widget attributes


This class implements a List in a Gtk2::Ex::FormFactory framework (based on Gtk2::Ex::Simple::List). The value of the associated application object attribute needs to be a reference to a two dimensional array with the content of the list.



  +--- Gtk2::Ex::FormFactory::List



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.

attr_select = SCALAR [optional]

If you want to track the selection state of the List set the name of the attribute of the associated application object here. An array reference with the indicies of the selected rows (or specific column values if attr_select_column is set) will be managed automatically and stored in this attribute.


Normally indicies of the selected rows are stored in the attribute passed with attr_select. Specify a column number here and the corresponding values will be stored instead (e.g. an internal database ID of an invisible column). If you use this you may use the select_row_by_attr() method as well, which is described below.

columns = ARRAYREF [mandatory]

This is a reference to an array containing the column titles of this list.

types = ARRAYREF [optional]

You may define types for the columns of the list. The type of a column defaults to 'text'. Other possible types are:

  text    normal text strings
  markup  pango markup strings
  int     integer values
  double  double-precision floating point values
  bool    boolean values, displayed as toggle-able checkboxes
  scalar  a perl scalar, displayed as a text string by default
  pixbuf  a Gtk2::Gdk::Pixbuf
editable = ARRAYREF [optional]

This an array reference of boolean values, one value for each column. Changes to columns marked editable are synchronized automatically with the associated application object attribute.

visible = ARRAYREF [optional]

This an array reference of boolean values, one value for each column and controls the visibility of the corresponding columns. Default is to display all columns.

selection_mode = 'none'|'single'|'browse'|'multiple' [optional]

You may specify a selection mode for the list. Please refer to the Gtk+ documentation of GtkSelectionMode for details about the possible selection modes.

update_selection_only = BOOL [optional]

If you know the values of your list don't change at runtime, and only the actual selection is important, you should set this to a true value, because updating will be significantly faster, since only the actual selection is affected.

For more attributes refer to Gtk2::Ex::FormFactory::Widget.

ATTRIBUTES: Gtk2::Ex::FormFactory::Widget

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 "never".

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 method.

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.

Click header to unfold this chapter


$rows = $widget->get_selected_rows ()

Returns a list reference of selected row indicies.

$data_lref = $widget->get_data ()

Returns the data array of the underlying Gtk2::SimpleList. It's a two dimensional array of rows and columns. All manipulations affect the GUI immediately but bypasses all Gtk2::Ex::FormFactory automatic object value update magic, so be careful with this.

$widget->select_row_by_attr ($value)

Selects a row by a given select_attr attribute value. Works only if select_attr is set for this list.

METHODS: Gtk2::Ex::FormFactory::Widget

$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 updated.

$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 call.

$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.

Click header to unfold this chapter


 Jörn Reder <joern at zyn dot de>


Copyright 2004-2006 by Jörn 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.