1Gtk2::Ex::FormFactory::UCsoenrteCxotn(t3r)ibuted Perl DoGctukm2e:n:tEaxt:i:oFnormFactory::Context(3)
2
6 Gtk2::Ex::FormFactory::Context - Context in a FormFactory framework
7
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 $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
37 This module implements a very importent concept of the
38 Gtk2::Ex::FormFactory framework.
39 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 So the Context is a layer between your application objects and the GUI
47 which represents particular attributes of your objects.
48
50 Gtk2::Ex::FormFactory::Context
51
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 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 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
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 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 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 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 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 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 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 object.attr
104 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 Once this attribute resp. the parent object change, the Context
110 will be updated automatically, including all widgets depending
111 on this widget.
112 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 get_prefix = SCALAR [optional]
118 With this parameter you can override the default_get_prefix
119 setting of this Context for this object.
120 set_prefix = SCALAR [optional]
122 With this parameter you can override the default_set_prefix
123 setting of this Context for this object.
124 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 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 This overrides attr_accessors_href described beyond.
135 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 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 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 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 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 $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 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 With the attr_activity_href setting you can handle activity on
208 attribute level, not only on object level.
209 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 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 $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 For details about the attr_depends_href option read on.
233 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 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 If an attribute depends on more than one other attributes you
248 can use a list reference:
249 attr_depends_href => sub {
251 ident_number => [
252 "person.may_override_ident_number",
253 "foo.bar",
254 ],
255 },
256 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 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 To receive or change the object's changed state refer to the
270 object_changed attribute of Gtk2::Ex::FormFactory::Proxy.
271 $context->remove_object ( $name )
273 Remove the object $name from this context.
274 $app_object = $context->get_object ( $name )
276 This returns the application object registered as $name to this
277 context.
278 $context->set_object ( $name => $object )
280 This sets a new object, which was registered as $name to this
281 context.
282 $context->get_object_attr ( "$object.$attr" )
284 Retrieves the attribute named $attr of the object $object.
285 $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 $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 You may omit $attr_name and pass a fully qualified "object.attr"
296 noted string as the first argument instead.
297 $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 $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 $activity is 'inactive' or 'active'.
308 $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
316 This feature was introduced in version 0.58 and is marked experimental
317 so please use with care.
318 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 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 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 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 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
352 Jörn Reder <joern at zyn dot de>
353
355 Copyright 2004-2006 by Jörn Reder.
356 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 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 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
373 Hey! The above document had some coding errors, which are explained
374 below:
375 Around line 851:
377 Non-ASCII character seen before =encoding in 'Jörn'. Assuming UTF-8
378perl v5.28.0 2009-11-08 Gtk2::Ex::FormFactory::Context(3)