1Gtk2::Ex::FormFactory::UWsiedrgeCto(n3t)ributed Perl DocGutmke2n:t:aEtxi:o:nFormFactory::Widget(3)
2
3
4

NAME

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

SYNOPSIS

9         Gtk2::Ex::FormFactory::Widget->new (
10           name                 => Name of this Widget,
11           object               => Name of the associated application object,
12           attr                 => Attribute represented by the Widget,
13           label                => Label text,
14           label_markup         => Boolean, indicating whether the label has markup,
15           label_group          => Name of a Gtk2::SizeGroup for the label,
16           widget_group         => Name of a Gtk2::SizeGroup for the widget,
17           tip                  => Tooltip text,
18           properties           => { Gtk2 Properties ... }
19           inactive             => 'insensitive' | 'invisible',
20           rules                => [ Rules for this Widget ],
21           expand               => Boolean: should the Widget expand?,
22           expand_h             => Boolean: should the Widget expand horizontally?,
23           expand_v             => Boolean: should the Widget expand vertically?,
24           scrollbars           => [ hscrollbar_policy, vscrollbar_policy ],
25           signal_connect       => { signal => CODREF, ... },
26           signal_connect_after => { signal => CODREF, ... },
27           width                => Desired width,
28           height               => Desired height,
29           customize_hook       => CODEREF: Customize the underlying Gtk2 Widget,
30           changed_hook         => CODEREF: Track changes made to the Widget,
31           changed_hook_after   => CODEREF: Track changes made to the Widget,
32           active_cond          => CODEREF: Condition for Widget being active
33           active_depends       => SCALAR|ARRAYREF: Attribute(s) activity depends on
34         );
35

DESCRIPTION

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

OBJECT HIERARCHY

43         Gtk2::Ex::FormFactory::Intro
44
45         Gtk2::Ex::FormFactory::Widget
46         +--- Gtk2::Ex::FormFactory::Container
47         |    +--- Gtk2::Ex::FormFactory
48         |    +--- Gtk2::Ex::FormFactory::Expander
49         |    +--- Gtk2::Ex::FormFactory::Form
50         |    +--- Gtk2::Ex::FormFactory::HBox
51         |    +--- Gtk2::Ex::FormFactory::Notebook
52         |    +--- Gtk2::Ex::FormFactory::Table
53         |    +--- Gtk2::Ex::FormFactory::VBox
54         |    +--- Gtk2::Ex::FormFactory::Window
55         +--- Gtk2::Ex::FormFactory::Button
56         +--- Gtk2::Ex::FormFactory::CheckButton
57         +--- Gtk2::Ex::FormFactory::CheckButtonGroup
58         +--- Gtk2::Ex::FormFactory::Combo
59         +--- Gtk2::Ex::FormFactory::DialogButtons
60         +--- Gtk2::Ex::FormFactory::Entry
61         +--- Gtk2::Ex::FormFactory::Expander
62         +--- Gtk2::Ex::FormFactory::ExecFlow
63         +--- Gtk2::Ex::FormFactory::GtkWidget
64         +--- Gtk2::Ex::FormFactory::HPaned
65         +--- Gtk2::Ex::FormFactory::HSeparator
66         +--- Gtk2::Ex::FormFactory::Image
67         +--- Gtk2::Ex::FormFactory::Label
68         +--- Gtk2::Ex::FormFactory::List
69         +--- Gtk2::Ex::FormFactory::Menu
70         +--- Gtk2::Ex::FormFactory::Popup
71         +--- Gtk2::Ex::FormFactory::ProgressBar
72         +--- Gtk2::Ex::FormFactory::RadioButton
73         +--- Gtk2::Ex::FormFactory::TextView
74         +--- Gtk2::Ex::FormFactory::Timestamp
75         +--- Gtk2::Ex::FormFactory::ToggleButton
76         +--- Gtk2::Ex::FormFactory::VPaned
77         +--- Gtk2::Ex::FormFactory::VSeparator
78         +--- Gtk2::Ex::FormFactory::YesNo
79
80         Gtk2::Ex::FormFactory::Layout
81         Gtk2::Ex::FormFactory::Rules
82         Gtk2::Ex::FormFactory::Context
83         Gtk2::Ex::FormFactory::Proxy
84         +--- Gtk2::Ex::FormFactory::ProxyBuffered
85

ATTRIBUTES

87       Attributes are handled through the common get_ATTR(), set_ATTR() style
88       accessors, but they are mostly passed once to the object constructor
89       and must not be altered after the associated FormFactory was built.
90
91       name = SCALAR [optional]
92           Each widget has a unique name. If you don't specify it explicitly a
93           name is generated automatically. You can select named widgets later
94           by using the get_widget and lookup_widget methods described below.
95
96       object = SCALAR [optional]
97           The name of the object, which controls this widget. This object
98           name must be registered at the Gtk2::Ex::FormFactory::Context of
99           the Gtk2::Ex::FormFactory associated with this Widget.
100
101           You may omit the object property and use a fully qualified
102           "object.attr" notation in the attr attribute described beyond.  If
103           you want to associate your Widget only with an object, but not to
104           an attribute (e.g. to get the activity of a container widget
105           without an associated object attribute managed automatically) just
106           omit attr and specify only object here.
107
108       attr = SCALAR [optional]
109           Usually a Widget represents a specific object attribute, e.g. a
110           text entry shows the current value of the attribute you specify
111           here. How this attribute is accessed is defined in the
112           Gtk2::Ex::FormFactory::Context instance.
113
114           If you used the object property just pass the name of your
115           attribute here, but you may omit object and pass "object.attr" to
116           the attr property for convenience as well.
117
118       label = SCALAR [optional]
119           Each Widget may have an associated label. How this label is
120           actually rendered depends on the Gtk2::Ex::FormFactory::Container
121           to which this Widget was added. E.g. Gtk2::Ex::FormFactory::Form
122           implements a simple two column table with the labels in the left
123           and the widgets in the right column.
124
125       label_markup = BOOLEAN [optional]
126           If this is set to a true value, the label will be rendered with a
127           HTML like markup. Refer to the chapter "Pango Text Attribute
128           Markup" of the official Gtk documentation for details about the
129           known markup tags.
130
131       label_group = SCALAR [optional]
132           If you have a complex layout and you want to align your labels
133           although they are not part of the same container you can specify an
134           arbitrary name of a label group here. A correspondent
135           Gtk2::SizeGroup is managed automatically for you. Simply specify
136           the same name for all Widgets for which you want to have the same
137           label size.
138
139       widget_group = SCALAR [optional]
140           This is very similar to the label_group attribute. The difference
141           is that the size allocated by the Widget is under control of a
142           Gtk2::SizeGroup.
143
144       tip = SCALAR [optional]
145           Optional text of the tooltip of this Widget.
146
147       properties = HASHREF [optional]
148           This is a hash of Gtk+ properties for this Widget, e.g. you can
149           specify { border_width => 5 } here to manipulate the border-width
150           of this specific Widget. You should use this with care, because
151           this breaks the strict isolation of GUI structure and appearance.
152           Probably it's better to implement an own
153           Gtk2::Ex::FormFactory::Layout class, where you can control
154           appearance of your widgets in a much more generic way.
155
156       inactive = 'insensitive' | 'invisible' [optional]
157           Gtk2::Ex::FormFactory automatically manages the activity state of
158           your Widgets. Specify if you want the Widget getting insensitive or
159           invisible when the Widget is deactivated. This defaults to
160           'insensitive'.
161
162       rules = rule | [ rule, ... ] [optional]
163           Data entered by the user must apply the rules specified here. Refer
164           to Gtk2::Ex::FormFactory::Rules for details about rules.
165
166       expand = BOOL [optional]
167           By default a Widget doesn't expand into the space which is avaiable
168           from its container. Specify a TRUE value to activate Widget
169           expansion. Whether the Widget expands vertically or horizontally
170           depends on its Container. E.g. in a VBox it will expand vertically,
171           in a HBox horizontally.
172
173       expand_h = BOOL [optional]
174       expand_v = BOOL [optional]
175           Some containers can expand the Widget in both directions, e.g. a
176           Gtk2::Table. If your widget is added to such a container (e.g. to a
177           Gtk2::Ex::FormFactory::Form, which is implemented with a
178           Gtk2::Table) you can specify both directions of expansion here.
179
180           expand_h defaults to TRUE and expand_v to FALSE, or to expand if
181           specified.
182
183       scrollbars = [ h_policy, v_policy ] [optional]
184           If you want your Widget inside a Gtk2::ScrolledWindow, simply
185           specify the policy for horizontal and vertical scrollbars here.
186           Possible values are: "always", "automatic" or "never".
187
188       changed_hook = CODEREF(ApplicationObject, WidgetObject) [optional]
189           This code reference is called after the user changed a value of the
190           Widget, but before these changes are applied to the underlying
191           application object. The application object is the first argument of
192           the call, the Widget object the second.
193
194       changed_hook_after = CODEREF(ApplicationObject, WidgetObject)
195       [optional]
196           This code reference is called after the user changed a value of the
197           Widget and after these changes are applied to the underlying
198           application object. The application object is the first argument of
199           the call, the Widget object the second.
200
201       signal_connect = HASHREF [optional]
202           Specify all your signal connections in a single hash reference. Key
203           is the name of the signal, and value the callback (a static
204           subroutine reference or a closure).
205
206           Note: don't use this to track changes made on the GUI!
207           Gtk2::Ex::FormFactory manages this for you. If you want to be
208           notified about changes, use the Widget transparent changed_hook
209           described above.
210
211       signal_connect_after = HASHREF [optional]
212           Same as signal_connect, but signals are connected using Gtk2's
213           signal_connect_after method.
214
215       width = INTEGER [optional]
216       height = INTEGER [optional]
217           You can specify a desired width and/or height. Internally
218           Gtk2::Widget->set_default_size is used on windows and
219           Gtk2::Widget->set_size_request on all other widgets.
220
221       customize_hook = CODEREF(Gtk2::Widget) [optional]
222           This code reference is called after the Gtk2::Widget's are built.
223           The Gtk2::Widget object of this Gtk2::Ex::FormFactory::Widget is
224           the first argument of this call.
225
226           You can use this hook to do very specific customization with this
227           Widget. Again: use this with care, probably implement your own
228           Gtk2::Ex::FormFactory::Layout class to control the layout.
229
230       active_cond = CODEREF(ApplicationObject) [optional]
231           Widget's activity state (visible/sensitive) is controlled by this
232           condition resp. the return value of this code reference. Use this
233           if you want to fine control the activity state of the widget with
234           arbitrary conditions. Note that widgets get automatically inactive
235           if the object they're bound to get's undef.
236
237           The return value is as follows:
238
239             0   Widget gets inactive. According to the B<inactive>
240                 attribute it gets either invisible or insensitive.
241
242             1   Widget gets active. According to the B<inactive>
243                 attribute it gets either visible or sensitive.
244
245           Or return one of these strings
246
247             'insensitive'
248             'invisible'
249             'sensitive'
250             'visible'
251
252           to get the corresponding widget state.
253
254       active_depends = SCALAR | ARRAYREF [optional]
255           This lists the attribute(s) the activity condition above depends
256           on, resp. which attributes are variables in the condition. May
257           point to objects or attributes (in "object.attr" notation).
258
259           With this knowledge Gtk2::Ex::FormFactory is able to update the
260           activity automatically if one of the corresponding objects or
261           attributes changes.
262

METHODS

264       $widget->update ()
265           Updates this specific Widget resp. sets it's state to the value
266           from the associated application object attribute. In case of a
267           Container the child widgets are not updated.
268
269       $widget->update_all ()
270           Same as update, but containers will update their children as well.
271
272       $widget->update_widget_activity ()
273           Only update the Widget's activity state.
274
275       $app_object_attr_value = $widget->get_object_value ([$attr])
276           A convenience method to get the actual value of an associated
277           application object attribute. If $attr is omitted, the default
278           attribute is used.
279
280       $widget->set_object_value ( [$attr, ] $value )
281           A convenience method to set the actual value of an associated
282           application object attribute to $value. If $attr is omitted, the
283           default attribute is used.
284
285       $widget->check_widget_value ()
286           Checks the current Widget value against the rules provided for this
287           Widget. An error dialog is opened if the rule check failed and the
288           previous value is restored automatically. Nothing happens if all
289           rules apply.
290
291       $widget->widget_value_changed ()
292           This method is called if the Widget value was changed. All Widget
293           implementations of Gtk2::Ex::FormFactory must connect their
294           specific "changed" signal to this method call.
295
296       $widget->apply_changes ()
297           Copy the Widget value to the associated application object
298           attribute.  In a FormFactory with the sync flag set to TRUE this
299           happens on each change. If the FormFactory is asynchronous it's
300           called only when the user hit the Ok button.
301
302       $widget->show_error_message ( message => $message, type => $type )
303           Small convenience method which opens a Gtk+ error dialog with
304           $message. $type defaults to 'error', but you can specify 'info',
305           'warning' and 'question' as well to get corresponding dialogs.
306
307       $proxy = $widget->get_proxy ()
308           Convenience method which returns the Gtk2::Ex::FormFactory::Proxy
309           instance for the object associated with this Widget.
310
311       $another_widget = $widget->get_widget ( $name )
312           Returns the Gtk2::Ex::FormFactory::Widget object named $name of the
313           FormFactory of this widget.
314
315       $another_widget = $widget->lookup_widget ($name)
316           The same as get_widget if a widget name is passed, but additionally
317           you may dereference sibling widgets by passing
318
319             sibling($n)
320
321           This returns the $n-th sibling of this Widget, whereby $n may be a
322           negative value.
323
324           This method is used to lookup widgets assigned to a
325           Gtk2::Ex::FormFactory::Label using the Label's for attribute.
326
327       The following methods are used by the Gtk2::Ex::FormFactory::Layout
328       module, so you need them only if you implement your own layout.
329
330       $widget->set_gtk_widget (Gtk2::Widget)
331           The Gtk2::Widget which represents the associated application object
332           attribute, e.g. this is a Gtk2::Entry for a
333           Gtk2::Ex::FormFactory::Entry widget.
334
335       $widget->set_gtk_parent_widget (Gtk2::Widget)
336           Often the real Gtk2 widget is inside a container, e.g. a
337           Gtk2::Frame. The Gtk2 widget of the container needs to be set
338           explicetly using this method.
339

IMPLEMENT NEW WIDGETS

341       You can implement new widgets by subclassing
342       Gtk2::Ex::FormFactory::Widget or Gtk2::Ex::FormFactory::Container.
343
344       You need to implement the following methods (not all are mandatory,
345       e.g.  if your Widget is a container actually doesn't representing any
346       application object value, you can omit most of them):
347
348       $self->get_type() [mandatory]
349           This returns the short name of your Widget. It should be lower case
350           and may contain underscores. If you wrap an existent Gtk2 widget
351           try to derive the type name from the widget's name.
352
353       $self->object_to_widget [optional]
354           This method transfers the value of the associated application
355           object attribute to your widget. You may use the convenience method
356           $self->get_object_value() to get the value of the default attribute
357           of this widget.
358
359       $self->widget_to_object [optional]
360           This method transfers the value of your widget to the associated
361           application object attribute. You may use the convenience method
362           $self->set_object_value($value) to set the value of the default
363           attribute of this widget.
364
365       $self->empty_widget [optional]
366           This method sets your widget to an empty value, e.g. an Image
367           widget should display nothing, or the text of some sort of text
368           entry should be deleted.
369
370       $self->backup_widget_value [optional]
371           This method makes a backup of the current widget value.
372           Gtk2::Ex::FormFactory::Widget has a convenience method for setting
373           the backup value you may use:
374           $self->set_backup_widget_value($value).  If your widget has a more
375           complex value, which can't be covered by a single scalar, the
376           implementation must care about this.
377
378       $self->restore_widget_value [optional]
379           This restores a value from the backup created with
380           $self->backup_widget_value().
381
382       $self->get_gtk_check_widget [optional]
383           Returns the Gtk widget to which the focus-in and focus-out signals
384           should be connected to for rule checking. Defaults to
385           $self->get_gtk_widget().
386
387       $self->get_widget_check_value [optional]
388           Currently Gtk2::Ex::FormFactory::Rules can only check a single
389           scalar value. Your widget must implement this method to return the
390           correspondent value.
391
392       $self->connect_changed_signal [optional]
393           This method must connect the "changed" signal of the specific Gtk2
394           widget your implementation uses. The connected callback must call
395           the $self->widget_value_changed() method, so Gtk2::Ex::FormFactory
396           can track all changes on the GUI.
397
398       $gtk_widget = $self->get_gtk_signal_widget() [optional]
399           This defaults to $self->get_gtk_widget() and returns the Gtk2
400           widget to which additional user specified signals should be
401           connected.
402
403       $gtk_widget = $self->get_gtk_properties_widget() [optional]
404           This defaults to $self->get_gtk_widget() and returns the Gtk2
405           widget which should get the properties defined for this
406           Gtk2::Ex::FormFactory widget. This is useful if the actual
407           GtkWidget is not the gtk_widget (e.g. Gtk2::Ex::FormFactory::Window
408           needs this, since it's finally a VBox, but you want to apply
409           properties like default_width to the GtkWindow and not to the
410           VBox).
411
412       $widgets_lref = $self->get_gtk_tip_widgets() [optional]
413           This defaults to [ $self->get_gtk_widget() ] and returns a list
414           reference of Gtk2 widgets which should get a tooltip, if the user
415           specified one.
416
417       $self->has_additional_attrs() [optional]
418           If your widget supports additional application object attributes
419           which should be managed automatically, this method returns a list
420           reference of symbolic names for these attributes. Please refer to
421           the implementation of Gtk2::Ex::FormFactory::List, which uses this
422           feature to store the actually selected item(s) in the application
423           object.
424
425       BOOL = $self->has_label() [optional]
426           This defaults to 0. Set this to 1 if your widget manage it's label
427           by itself (like a Gtk2::CheckBox does).
428
429   Creating the Gtk2 widget(s)
430       You probably recognized that a method which actually builds the Gtk2
431       widgets of your widget is missing here. This is covered by the
432       Gtk2::Ex::FormFactory::Layout module. So create your own layouter and
433       add the $layouter->build_TYPE($widget) method for your widget to it. If
434       your widget is a container you also need to implement at least the
435       generic $layouter->add_widget_to_TYPE method. For details about this
436       please refer to the documentation of Gtk2::Ex::FormFactory::Layout.
437
438       Nevertheless, if your widget is very specific to your application, e.g.
439       because it displays a very specific data structure, creating your own
440       Layout module just for that purpose is somewhat involved. In that case
441       you can implement this method:
442
443       $self->build_widget()
444           If implemented this method is called to actually create the Gtk2
445           widgets for your Gtk2::Ex::FormFactory widget.
446

AUTHORS

448        Jörn Reder <joern at zyn dot de>
449
451       Copyright 2004-2006 by Jörn Reder.
452
453       This library is free software; you can redistribute it and/or modify it
454       under the terms of the GNU Library General Public License as published
455       by the Free Software Foundation; either version 2.1 of the License, or
456       (at your option) any later version.
457
458       This library is distributed in the hope that it will be useful, but
459       WITHOUT ANY WARRANTY; without even the implied warranty of
460       MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
461       Library General Public License for more details.
462
463       You should have received a copy of the GNU Library General Public
464       License along with this library; if not, write to the Free Software
465       Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307
466       USA.
467

POD ERRORS

469       Hey! The above document had some coding errors, which are explained
470       below:
471
472       Around line 1379:
473           Non-ASCII character seen before =encoding in 'Jörn'. Assuming UTF-8
474
475
476
477perl v5.28.0                      2011-08-11  Gtk2::Ex::FormFactory::Widget(3)
Impressum