Gtk2::Ex::FormFactory:UsergContributed Perl DoGtk2::Ex::FormFactory::Widget(3)NAMEGtk2::Ex::FormFactory::Widget - Base class for all FormFactory Widgets
SYNOPSIS
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
);
DESCRIPTION
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.
OBJECT HIERARCHY
Gtk2::Ex::FormFactory::Intro
Gtk2::Ex::FormFactory::Widget
+--- 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::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::Layout
Gtk2::Ex::FormFactory::Rules
Gtk2::Ex::FormFactory::Context
Gtk2::Ex::FormFactory::Proxy
+--- Gtk2::Ex::FormFactory::ProxyBuffered
ATTRIBUTES
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
'insensitive'
'invisible'
'sensitive'
'visible'
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.
METHODS
$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
sibling($n)
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.
IMPLEMENT NEW WIDGETS
You can implement new widgets by subclassing
Gtk2::Ex::FormFactory::Widget or Gtk2::Ex::FormFactory::Container.
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
object.
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:
$self->build_widget()
If implemented this method is called to actually create the Gtk2
widgets for your Gtk2::Ex::FormFactory widget.
AUTHORS
JA~Xrn Reder <joern at zyn dot de>
COPYRIGHT AND LICENSE
Copyright 2004-2006 by JA~Xrn 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.
perl v5.14.1 2006-07-02 Gtk2::Ex::FormFactory::Widget(3)
