1Gtk2::Ex::FormFactory::UWsiedrgeCto(n3t)ributed Perl DocGutmke2n:t:aEtxi:o:nFormFactory::Widget(3)
2
6 Gtk2::Ex::FormFactory::Widget - Base class for all FormFactory Widgets
7
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
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
43 Gtk2::Ex::FormFactory::Intro
44 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 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
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 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 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 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 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 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 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 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 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 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 tip = SCALAR [optional]
145 Optional text of the tooltip of this Widget.
146 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 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 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 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 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 expand_h defaults to TRUE and expand_v to FALSE, or to expand if
181 specified.
182 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 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 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 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 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 signal_connect_after = HASHREF [optional]
212 Same as signal_connect, but signals are connected using Gtk2's
213 signal_connect_after method.
214 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 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 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 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 The return value is as follows:
238 0 Widget gets inactive. According to the B<inactive>
240 attribute it gets either invisible or insensitive.
241 1 Widget gets active. According to the B<inactive>
243 attribute it gets either visible or sensitive.
244 Or return one of these strings
246 'insensitive'
248 'invisible'
249 'sensitive'
250 'visible'
251 to get the corresponding widget state.
253 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 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
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 $widget->update_all ()
270 Same as update, but containers will update their children as well.
271 $widget->update_widget_activity ()
273 Only update the Widget's activity state.
274 $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 $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 $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 $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 $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 $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 $proxy = $widget->get_proxy ()
308 Convenience method which returns the Gtk2::Ex::FormFactory::Proxy
309 instance for the object associated with this Widget.
310 $another_widget = $widget->get_widget ( $name )
312 Returns the Gtk2::Ex::FormFactory::Widget object named $name of the
313 FormFactory of this widget.
314 $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 sibling($n)
320 This returns the $n-th sibling of this Widget, whereby $n may be a
322 negative value.
323 This method is used to lookup widgets assigned to a
325 Gtk2::Ex::FormFactory::Label using the Label's for attribute.
326 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 $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 $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
341 You can implement new widgets by subclassing
342 Gtk2::Ex::FormFactory::Widget or Gtk2::Ex::FormFactory::Container.
343 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 $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 $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 $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 $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 $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 $self->restore_widget_value [optional]
379 This restores a value from the backup created with
380 $self->backup_widget_value().
381 $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 $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 $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 $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 $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 $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 $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 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 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 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 $self->build_widget()
444 If implemented this method is called to actually create the Gtk2
445 widgets for your Gtk2::Ex::FormFactory widget.
446
448 Jörn Reder <joern at zyn dot de>
449
451 Copyright 2004-2006 by Jörn Reder.
452 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 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 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
469 Hey! The above document had some coding errors, which are explained
470 below:
471 Around line 1379:
473 Non-ASCII character seen before =encoding in 'Jörn'. Assuming UTF-8
474perl v5.32.0 2020-07-28 Gtk2::Ex::FormFactory::Widget(3)