1Gtk2::Ex::FormFactory::UCsoenrteCxotn(t3r)ibuted Perl DoGctukm2e:n:tEaxt:i:oFnormFactory::Context(3)
2
3
4

NAME

6       Gtk2::Ex::FormFactory::Context - Context in a FormFactory framework
7

SYNOPSIS

9         my $context = Gtk2::Ex::FormFactory::Context->new (
10           default_get_prefix => Default prefix for read accessors,
11           default_set_prefix => Default prefix for write accessors,
12         );
13
14         $context->add_object (
15           name                => Name of the application object in
16                                  this Context,
17           aggregated_by       => Object.Attribute of the parent object
18                                  aggregating this object
19           object              => The application object itself or a
20                                  callback which returns the object,
21                                  or undef if aggregated or set later
22           get_prefix          => Prefix for read accessors,
23           set_prefix          => Prefix for write accessors,
24           accessor            => CODEREF which handles access to all object
25                                  attributes
26           attr_activity_href  => Hash of CODEREFS for attributes which return
27                                  activity of the corresponding attributes,
28           attr_depends_href   => Hash defining attribute dependencies,
29           attr_accessors_href => Hash of CODEREFS which override correspondent
30                                  accessors in this Context,
31           buffered            => Indicates whether changes should be buffered,
32           changes_attr_filter => Regex for attributes which should not trigger
33                                  the object's 'changed' status
34         );
35

DESCRIPTION

37       This module implements a very importent concept of the
38       Gtk2::Ex::FormFactory framework.
39
40       The Context knows of all your application objects, how attributes of
41       the objects can be accessed (for reading and writing), which attributes
42       probably depend on other attributes and knows of how to control the
43       activity state of attributes resp. of the Widgets which represent these
44       attributes.
45
46       So the Context is a layer between your application objects and the GUI
47       which represents particular attributes of your objects.
48

OBJECT HIERARCHY

50         Gtk2::Ex::FormFactory::Context
51

ATTRIBUTES

53       Attributes are handled through the common get_ATTR(), set_ATTR() style
54       accessors, but they are mostly passed once to the object constructor
55       and must not be altered after associated FormFactory's were built.
56
57       default_get_prefix = SCALAR [optional]
58           Usually your application's objects use a common prefix for all
59           attribute accessors. This defines the default prefix for read
60           accessors and defaults to "get_".
61
62       default_set_prefix = SCALAR [optional]
63           Usually your application's objects use a common prefix for all
64           attribute accessors. This defines the default prefix for write
65           accessors and defaults to "set_".
66

METHODS

68       $context->add_object (...)
69           All your application objects must be added to the Context using
70           this method. Parameters are passed to the method as a hash:
71
72           name = SCALAR [mandatory]
73               Each object in a Context need a unique name, so this parameter
74               is mandatory. You refer to this name when you create Widgets
75               and want to associate these with your application object's
76               attributes.
77
78           object = BLESSED REF|CODEREF [optional]
79               This is the application object itself, or a code reference
80               which returns the object. Using the code reference option gives
81               you very flexible control of what this object actually is. But
82               also note that this may have some impact on performance,
83               because this code reference will be called quite often.
84
85               Often objects are aggregated by other objects, in that case
86               don't set the object reference here but use the aggregate_by
87               option described below.
88
89               An application object in terms of the Context may become undef,
90               that's why the object parameter is optional here. Also the code
91               reference may return undef.
92
93               Once an object gets undef, all associated widgets will be set
94               inactive automatically. You can control per widget if it should
95               render invisible or insensitive in that case. Refer to
96               Gtk2::Ex::FormFactory::Widget for details.
97
98           aggregated_by = "object.attr" [optional]
99               If this object has a parent object set this option to the fully
100               qualified attribute holding the object reference, using the
101               object dot attribute notation:
102
103                 object.attr
104
105               where object is the name of the parent object used to register
106               it to this Context, and attr the attribute holding the
107               reference to the object currently added to the Context.
108
109               Once this attribute resp. the parent object change, the Context
110               will be updated automatically, including all widgets depending
111               on this widget.
112
113               This way you can define your full object aggregation hierarchy
114               and Gtk2::Ex::FormFactory takes care of all resulting
115               dependencies on the GUI.
116
117           get_prefix = SCALAR [optional]
118               With this parameter you can override the default_get_prefix
119               setting of this Context for this object.
120
121           set_prefix = SCALAR [optional]
122               With this parameter you can override the default_set_prefix
123               setting of this Context for this object.
124
125           accessor = CODEREF(object,attr[,value]) [optional]
126               If accessor is set this code reference is used as a generic
127               accessor callback for all attributes. It handles getting and
128               setting as well.
129
130               Called with two arguments the passed attribute is to be read,
131               with three arguments, the third argument is the value which is
132               to be assigned to the attribute.
133
134               This overrides attr_accessors_href described beyond.
135
136           attr_accessors_href = HASHREF [optional]
137               Often your application object attribute values doesn't fit the
138               data type a particular Widget expects, e.g. in case of the
139               Gtk2::Ex::FormFactory::List widget, which expects a two
140               dimensional array for its content.
141
142               Since you need this conversion only for a particular GUI task
143               it makes sense to implement the conversion routine in the
144               Context instead of adding such GUI specific methods to your
145               underlying classes, which should be as much GUI independent as
146               possible.
147
148               That's why you can override arbitrary accessors (read and
149               write) using the attr_accessors_href parameter. Key is the name
150               of method to be overriden and constant scalar value or a code
151               reference, which is called instead of the real method.
152
153               The code reference gets your application object as the first
154               parameter, as usual for object methods, and additionally the
155               new value in case of write access.
156
157               A short example. Here we override the accessors get_tracks and
158               set_tracks of an imagnary disc object, which represents an
159               audio CD. The track title is stored as a simple array and needs
160               to be converted to a two dimensional array as expected by
161               Gtk2::Ex::FormFactory::List. Additionally an constant accessor
162               is defined for a Gtk2::Ex::FormFactory::Popup showing a bunch
163               of music genres:
164
165                 $context->add_object (
166                   name => "disc",
167                   attr_accessors_href => {
168                     get_tracks => sub {
169                       my $disc = shift;
170                       #-- Convert the one dimensional array of disc
171                       #-- tracks to the two dimensional array expected
172                       #-- by Gtk2::Ex::FormFactory::List. Also the number
173                       #-- of the track is added to the first column here
174                       my @list;
175                       my $nr = 1;
176                       foreach my $track ( @{$disc->get_tracks} ) {
177                         push @list, [ $nr++, $track ];
178                       }
179                       return\@list;
180                     },
181                     set_tracks => sub {
182                       my $disc = shift;
183                       my ($list_ref) = @_;
184                       #-- Convert the array back (the List is editable in
185                       #-- our example, so values can be changed).
186                       my @list;
187                       foreach my $row ( @{$list_ref} ) {
188                               push @list, $row->[1];
189                       }
190                       $disc->set_tracks(\@list);
191                       return \@list;
192                     },
193                     genre_list => {
194                       "rock" => "Rock",
195                       "pop"  => "Pop",
196                       "elec" => "Electronic",
197                       "jazz" => "Jazz",
198                     },
199                   },
200                 );
201
202           attr_activity_href = HASHREF [OPTIONAL]
203               As mentioned earlier activity of Widgets is controlled by the
204               Gtk2::Ex::FormFactory framework. E.g. if the an object becomes
205               undef, all associated widgets render inactive.
206
207               With the attr_activity_href setting you can handle activity on
208               attribute level, not only on object level.
209
210               The key of the hash is the attribute name and value is a code
211               reference, which returns TRUE or FALSE and control the activity
212               this way.
213
214               Again an example: imagine a text entry which usually is set
215               with a default value controlled by your application.  But if
216               the user wants to override the entry he first has to press a
217               correpondent checkbox to activate this.
218
219                 $context->add_object (
220                   name => "person",
221                   attr_activity_href => {
222                     ident_number => sub {
223                       my $person = shift;
224                       return $person->get_may_override_ident_number;
225                     },
226                   },
227                   attr_depends_href => {
228                     ident_number => "person.may_override_ident_number",
229                   },
230                 );
231
232               For details about the attr_depends_href option read on.
233
234           attr_depends_href = HASHREF [OPTIONAL]
235               This hash defines dependencies between attributes. If you look
236               at the example above you see why this is necessary.  The
237               ident_number of a person may be overriden only if the
238               may_override_ident_number attribute of this person is set.
239               Since this dependency is coded inside the code reference,
240               Gtk2::Ex::FormFactory isn't aware of it until you add a
241               corresponding attr_depends_href entry.
242
243               Now the GUI will automatically activate the Widget for the
244               ident_number attribute once may_override_ident_number is set,
245               e.g. by a CheckBox the user clicked.
246
247               If an attribute depends on more than one other attributes you
248               can use a list reference:
249
250                 attr_depends_href => sub {
251                     ident_number => [
252                       "person.may_override_ident_number",
253                       "foo.bar",
254                     ],
255                 },
256
257           buffered = BOOL [OPTIONAL]
258               If set to TRUE this activates buffering for this object. Please
259               refer to the BUFFERED CONTEXT OBJECTS chapter for details.
260
261           changes_attr_filter = REGEX [OPTIONAL]
262               Gtk2::Ex::FormFactory maintains a flag indicating whether an
263               object was changed. Under special circumstances you want
264               specific attributes not affecting this "changed" state of an
265               object. You can specify an regular expression here. Changes of
266               attributes matching this expression won't touch the changes
267               state of the object.
268
269               To receive or change the object's changed state refer to the
270               object_changed attribute of Gtk2::Ex::FormFactory::Proxy.
271
272       $context->remove_object ( $name )
273           Remove the object $name from this context.
274
275       $app_object = $context->get_object ( $name )
276           This returns the application object registered as $name to this
277           context.
278
279       $context->set_object ( $name => $object )
280           This sets a new object, which was registered as $name to this
281           context.
282
283       $context->get_object_attr ( "$object.$attr" )
284           Retrieves the attribute named $attr of the object $object.
285
286       $context->set_object_attr ( "$object.$attr", $value )
287           Set the attribute named $attr of the object $object to $value.
288           Dependent widgets update automatically.
289
290       $context->update_object_attr_widgets ( $object_name, $attr_name )
291           Triggers updates on all GUI widgets which are associated with the
292           attribute $attr_name of the object registered as $object_name to
293           this context.
294
295           You may omit $attr_name and pass a fully qualified "object.attr"
296           noted string as the first argument instead.
297
298       $context->update_object_widgets ( $object_name )
299           Triggers updates on all GUI widgets which are associated with the
300           object registered as $object_name to this context.
301
302       $context->update_object_widgets_activity ( $object_name, $activity )
303           This updates the activity state of all GUI widgets which are
304           associated with the object registered as $object_name to this
305           context.
306
307           $activity is 'inactive' or 'active'.
308
309       $proxy = $context->get_proxy ( $object_name )
310           This returns the Gtk2::Ex::FormFactory::Proxy instance which was
311           created for the object registered as $name to this context.  With
312           the proxy you can do updates on object attributes which trigger the
313           correspondent GUI updates as well.
314

BUFFERED CONTEXT OBJECTS

316       This feature was introduced in version 0.58 and is marked experimental
317       so please use with care.
318
319       If you set buffered => 1 when adding an object to the Context a
320       buffering Proxy will be used for this object. That means that all GUI
321       changes in a synchronized FormFactory dialog are buffered in the proxy
322       object. Normally all changes are commited immediately to the object,
323       which is Ok in many situations, but makes implementing a Cancel button
324       difficult resp. you need to care about this yourself by using a copy of
325       the object or something like that.
326
327       A FormFactory gets "buffered" if all its widgets are connected to a
328       buffered object. In that case Gtk2::Ex::Form::DialogButtons show a
329       Cancel button automatically, even in a synchronized dialog.
330
331   What's this good for?
332       If your FormFactory doesn't has the sync flag set you get Cancel button
333       as well, since no changes are applied to the objects until the user hit
334       the Ok button. All changes are kept in the "GUI". But such a dialog
335       lacks of all dynamic auto-widget-updating features, e.g. setting
336       widgets inactive under specific conditions. For very simple dialogs
337       this is Ok, but if you need these features you need the buffering
338       facility as well.
339
340       But take care when implementing your closures for widget activity
341       checking: they must not use the original objects! They need to access
342       the attributes through the Context, because your original object
343       doesn't see any GUI changes until the FormFactory is applied! All
344       changes are buffered in the Context. If you access your objects through
345       the Context anything works as expected.
346
347       Buffering is useful as well in other situations e.g. if you're
348       accessing remote objects over a network (for example with Event::RPC)
349       where a method call is somewhat expensive.
350

AUTHORS

352        Jörn Reder <joern at zyn dot de>
353
355       Copyright 2004-2006 by Jörn Reder.
356
357       This library is free software; you can redistribute it and/or modify it
358       under the terms of the GNU Library General Public License as published
359       by the Free Software Foundation; either version 2.1 of the License, or
360       (at your option) any later version.
361
362       This library is distributed in the hope that it will be useful, but
363       WITHOUT ANY WARRANTY; without even the implied warranty of
364       MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
365       Library General Public License for more details.
366
367       You should have received a copy of the GNU Library General Public
368       License along with this library; if not, write to the Free Software
369       Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307
370       USA.
371

POD ERRORS

373       Hey! The above document had some coding errors, which are explained
374       below:
375
376       Around line 851:
377           Non-ASCII character seen before =encoding in 'Jörn'. Assuming UTF-8
378
379
380
381perl v5.30.1                      2020-01-30 Gtk2::Ex::FormFactory::Context(3)
Impressum