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::HSeparator
65 +--- Gtk2::Ex::FormFactory::Image
66 +--- Gtk2::Ex::FormFactory::Label
67 +--- Gtk2::Ex::FormFactory::List
68 +--- Gtk2::Ex::FormFactory::Menu
69 +--- Gtk2::Ex::FormFactory::Popup
70 +--- Gtk2::Ex::FormFactory::ProgressBar
71 +--- Gtk2::Ex::FormFactory::RadioButton
72 +--- Gtk2::Ex::FormFactory::TextView
73 +--- Gtk2::Ex::FormFactory::Timestamp
74 +--- Gtk2::Ex::FormFactory::ToggleButton
75 +--- Gtk2::Ex::FormFactory::VPaned
76 +--- Gtk2::Ex::FormFactory::VSeparator
77 +--- Gtk2::Ex::FormFactory::YesNo
78 Gtk2::Ex::FormFactory::Layout
80 Gtk2::Ex::FormFactory::Rules
81 Gtk2::Ex::FormFactory::Context
82 Gtk2::Ex::FormFactory::Proxy
83 +--- Gtk2::Ex::FormFactory::ProxyBuffered
84
86 Attributes are handled through the common get_ATTR(), set_ATTR() style
87 accessors, but they are mostly passed once to the object constructor
88 and must not be altered after the associated FormFactory was built.
89 name = SCALAR [optional]
91 Each widget has a unique name. If you don't specify it explicitly a
92 name is generated automatically. You can select named widgets later
93 by using the get_widget and lookup_widget methods described below.
94 object = SCALAR [optional]
96 The name of the object, which controls this widget. This object
97 name must be registered at the Gtk2::Ex::FormFactory::Context of
98 the Gtk2::Ex::FormFactory associated with this Widget.
99 You may omit the object property and use a fully qualified
101 "object.attr" notation in the attr attribute described beyond. If
102 you want to associate your Widget only with an object, but not to
103 an attribute (e.g. to get the activity of a container widget
104 without an associated object attribute managed automatically) just
105 omit attr and specify only object here.
106 attr = SCALAR [optional]
108 Usually a Widget represents a specific object attribute, e.g. a
109 text entry shows the current value of the attribute you specify
110 here. How this attribute is accessed is defined in the
111 Gtk2::Ex::FormFactory::Context instance.
112 If you used the object property just pass the name of your
114 attribute here, but you may omit object and pass "object.attr" to
115 the attr property for convenience as well.
116 label = SCALAR [optional]
118 Each Widget may have an associated label. How this label is
119 actually rendered depends on the Gtk2::Ex::FormFactory::Container
120 to which this Widget was added. E.g. Gtk2::Ex::FormFactory::Form
121 implements a simple two column table with the labels in the left
122 and the widgets in the right column.
123 label_markup = BOOLEAN [optional]
125 If this is set to a true value, the label will be rendered with a
126 HTML like markup. Refer to the chapter "Pango Text Attribute
127 Markup" of the official Gtk documentation for details about the
128 known markup tags.
129 label_group = SCALAR [optional]
131 If you have a complex layout and you want to align your labels
132 although they are not part of the same container you can specify an
133 arbitrary name of a label group here. A correspondent
134 Gtk2::SizeGroup is managed automatically for you. Simply specify
135 the same name for all Widgets for which you want to have the same
136 label size.
137 widget_group = SCALAR [optional]
139 This is very similar to the label_group attribute. The difference
140 is that the size allocated by the Widget is under control of a
141 Gtk2::SizeGroup.
142 tip = SCALAR [optional]
144 Optional text of the tooltip of this Widget.
145 properties = HASHREF [optional]
147 This is a hash of Gtk+ properties for this Widget, e.g. you can
148 specify { border_width => 5 } here to manipulate the border-width
149 of this specific Widget. You should use this with care, because
150 this breaks the strict isolation of GUI structure and appearance.
151 Probably it's better to implement an own
152 Gtk2::Ex::FormFactory::Layout class, where you can control
153 appearance of your widgets in a much more generic way.
154 inactive = 'insensitive' | 'invisible' [optional]
156 Gtk2::Ex::FormFactory automatically manages the activity state of
157 your Widgets. Specify if you want the Widget getting insensitive or
158 invisible when the Widget is deactivated. This defaults to
159 'insensitive'.
160 rules = rule | [ rule, ... ] [optional]
162 Data entered by the user must apply the rules specified here. Refer
163 to Gtk2::Ex::FormFactory::Rules for details about rules.
164 expand = BOOL [optional]
166 By default a Widget doesn't expand into the space which is avaiable
167 from its container. Specify a TRUE value to activate Widget
168 expansion. Whether the Widget expands vertically or horizontally
169 depends on its Container. E.g. in a VBox it will expand vertically,
170 in a HBox horizontally.
171 expand_h = BOOL [optional]
173 expand_v = BOOL [optional]
174 Some containers can expand the Widget in both directions, e.g. a
175 Gtk2::Table. If your widget is added to such a container (e.g. to a
176 Gtk2::Ex::FormFactory::Form, which is implemented with a
177 Gtk2::Table) you can specify both directions of expansion here.
178 expand_h defaults to TRUE and expand_v to FALSE, or to expand if
180 specified.
181 scrollbars = [ h_policy, v_policy ] [optional]
183 If you want your Widget inside a Gtk2::ScrolledWindow, simply
184 specify the policy for horizontal and vertical scrollbars here.
185 Possible values are: "always", "automatic" or "never".
186 changed_hook = CODEREF(ApplicationObject, WidgetObject) [optional]
188 This code reference is called after the user changed a value of the
189 Widget, but before these changes are applied to the underlying
190 application object. The application object is the first argument of
191 the call, the Widget object the second.
192 changed_hook_after = CODEREF(ApplicationObject, WidgetObject)
194 [optional]
195 This code reference is called after the user changed a value of the
196 Widget and after these changes are applied to the underlying
197 application object. The application object is the first argument of
198 the call, the Widget object the second.
199 signal_connect = HASHREF [optional]
201 Specify all your signal connections in a single hash reference. Key
202 is the name of the signal, and value the callback (a static
203 subroutine reference or a closure).
204 Note: don't use this to track changes made on the GUI!
206 Gtk2::Ex::FormFactory manages this for you. If you want to be
207 notified about changes, use the Widget transparent changed_hook
208 described above.
209 signal_connect_after = HASHREF [optional]
211 Same as signal_connect, but signals are connected using Gtk2's
212 signal_connect_after method.
213 width = INTEGER [optional]
215 height = INTEGER [optional]
216 You can specify a desired width and/or height. Internally
217 Gtk2::Widget->set_default_size is used on windows and
218 Gtk2::Widget->set_size_request on all other widgets.
219 customize_hook = CODEREF(Gtk2::Widget) [optional]
221 This code reference is called after the Gtk2::Widget's are built.
222 The Gtk2::Widget object of this Gtk2::Ex::FormFactory::Widget is
223 the first argument of this call.
224 You can use this hook to do very specific customization with this
226 Widget. Again: use this with care, probably implement your own
227 Gtk2::Ex::FormFactory::Layout class to control the layout.
228 active_cond = CODEREF(ApplicationObject) [optional]
230 Widget's activity state (visible/sensitive) is controlled by this
231 condition resp. the return value of this code reference. Use this
232 if you want to fine control the activity state of the widget with
233 arbitrary conditions. Note that widgets get automatically inactive
234 if the object they're bound to get's undef.
235 The return value is as follows:
237 0 Widget gets inactive. According to the B<inactive>
239 attribute it gets either invisible or insensitive.
240 1 Widget gets active. According to the B<inactive>
242 attribute it gets either visible or sensitive.
243 Or return one of these strings
245 'insensitive'
247 'invisible'
248 'sensitive'
249 'visible'
250 to get the corresponding widget state.
252 active_depends = SCALAR | ARRAYREF [optional]
254 This lists the attribute(s) the activity condition above depends
255 on, resp. which attributes are variables in the condition. May
256 point to objects or attributes (in "object.attr" notation).
257 With this knowledge Gtk2::Ex::FormFactory is able to update the
259 activity automatically if one of the corresponding objects or
260 attributes changes.
261
263 $widget->update ()
264 Updates this specific Widget resp. sets it's state to the value
265 from the associated application object attribute. In case of a
266 Container the child widgets are not updated.
267 $widget->update_all ()
269 Same as update, but containers will update their children as well.
270 $widget->update_widget_activity ()
272 Only update the Widget's activity state.
273 $app_object_attr_value = $widget->get_object_value ([$attr])
275 A convenience method to get the actual value of an associated
276 application object attribute. If $attr is omitted, the default
277 attribute is used.
278 $widget->set_object_value ( [$attr, ] $value )
280 A convenience method to set the actual value of an associated
281 application object attribute to $value. If $attr is omitted, the
282 default attribute is used.
283 $widget->check_widget_value ()
285 Checks the current Widget value against the rules provided for this
286 Widget. An error dialog is opened if the rule check failed and the
287 previous value is restored automatically. Nothing happens if all
288 rules apply.
289 $widget->widget_value_changed ()
291 This method is called if the Widget value was changed. All Widget
292 implementations of Gtk2::Ex::FormFactory must connect their
293 specific "changed" signal to this method call.
294 $widget->apply_changes ()
296 Copy the Widget value to the associated application object
297 attribute. In a FormFactory with the sync flag set to TRUE this
298 happens on each change. If the FormFactory is asynchronous it's
299 called only when the user hit the Ok button.
300 $widget->show_error_message ( message => $message, type => $type )
302 Small convenience method which opens a Gtk+ error dialog with
303 $message. $type defaults to 'error', but you can specify 'info',
304 'warning' and 'question' as well to get corresponding dialogs.
305 $proxy = $widget->get_proxy ()
307 Convenience method which returns the Gtk2::Ex::FormFactory::Proxy
308 instance for the object associated with this Widget.
309 $another_widget = $widget->get_widget ( $name )
311 Returns the Gtk2::Ex::FormFactory::Widget object named $name of the
312 FormFactory of this widget.
313 $another_widget = $widget->lookup_widget ($name)
315 The same as get_widget if a widget name is passed, but additionally
316 you may dereference sibling widgets by passing
317 sibling($n)
319 This returns the $n-th sibling of this Widget, whereby $n may be a
321 negative value.
322 This method is used to lookup widgets assigned to a
324 Gtk2::Ex::FormFactory::Label using the Label's for attribute.
325 The following methods are used by the Gtk2::Ex::FormFactory::Layout
327 module, so you need them only if you implement your own layout.
328 $widget->set_gtk_widget (Gtk2::Widget)
330 The Gtk2::Widget which represents the associated application object
331 attribute, e.g. this is a Gtk2::Entry for a
332 Gtk2::Ex::FormFactory::Entry widget.
333 $widget->set_gtk_parent_widget (Gtk2::Widget)
335 Often the real Gtk2 widget is inside a container, e.g. a
336 Gtk2::Frame. The Gtk2 widget of the container needs to be set
337 explicetly using this method.
338
340 You can implement new widgets by subclassing
341 Gtk2::Ex::FormFactory::Widget or Gtk2::Ex::FormFactory::Container.
342 You need to implement the following methods (not all are mandatory,
344 e.g. if your Widget is a container actually doesn't representing any
345 application object value, you can omit most of them):
346 $self->get_type() [mandatory]
348 This returns the short name of your Widget. It should be lower case
349 and may contain underscores. If you wrap an existent Gtk2 widget
350 try to derive the type name from the widget's name.
351 $self->object_to_widget [optional]
353 This method transfers the value of the associated application
354 object attribute to your widget. You may use the convenience method
355 $self->get_object_value() to get the value of the default attribute
356 of this widget.
357 $self->widget_to_object [optional]
359 This method transfers the value of your widget to the associated
360 application object attribute. You may use the convenience method
361 $self->set_object_value($value) to set the value of the default
362 attribute of this widget.
363 $self->empty_widget [optional]
365 This method sets your widget to an empty value, e.g. an Image
366 widget should display nothing, or the text of some sort of text
367 entry should be deleted.
368 $self->backup_widget_value [optional]
370 This method makes a backup of the current widget value.
371 Gtk2::Ex::FormFactory::Widget has a convenience method for setting
372 the backup value you may use:
373 $self->set_backup_widget_value($value). If your widget has a more
374 complex value, which can't be covered by a single scalar, the
375 implementation must care about this.
376 $self->restore_widget_value [optional]
378 This restores a value from the backup created with
379 $self->backup_widget_value().
380 $self->get_gtk_check_widget [optional]
382 Returns the Gtk widget to which the focus-in and focus-out signals
383 should be connected to for rule checking. Defaults to
384 $self->get_gtk_widget().
385 $self->get_widget_check_value [optional]
387 Currently Gtk2::Ex::FormFactory::Rules can only check a single
388 scalar value. Your widget must implement this method to return the
389 correspondent value.
390 $self->connect_changed_signal [optional]
392 This method must connect the "changed" signal of the specific Gtk2
393 widget your implementation uses. The connected callback must call
394 the $self->widget_value_changed() method, so Gtk2::Ex::FormFactory
395 can track all changes on the GUI.
396 $gtk_widget = $self->get_gtk_signal_widget() [optional]
398 This defaults to $self->get_gtk_widget() and returns the Gtk2
399 widget to which additional user specified signals should be
400 connected.
401 $gtk_widget = $self->get_gtk_properties_widget() [optional]
403 This defaults to $self->get_gtk_widget() and returns the Gtk2
404 widget which should get the properties defined for this
405 Gtk2::Ex::FormFactory widget. This is useful if the actual
406 GtkWidget is not the gtk_widget (e.g. Gtk2::Ex::FormFactory::Window
407 needs this, since it's finally a VBox, but you want to apply
408 properties like default_width to the GtkWindow and not to the
409 VBox).
410 $widgets_lref = $self->get_gtk_tip_widgets() [optional]
412 This defaults to [ $self->get_gtk_widget() ] and returns a list
413 reference of Gtk2 widgets which should get a tooltip, if the user
414 specified one.
415 $self->has_additional_attrs() [optional]
417 If your widget supports additional application object attributes
418 which should be managed automatically, this method returns a list
419 reference of symbolic names for these attributes. Please refer to
420 the implementation of Gtk2::Ex::FormFactory::List, which uses this
421 feature to store the actually selected item(s) in the application
422 object.
423 BOOL = $self->has_label() [optional]
425 This defaults to 0. Set this to 1 if your widget manage it's label
426 by itself (like a Gtk2::CheckBox does).
427 Creating the Gtk2 widget(s)
429 You probably recognized that a method which actually builds the Gtk2
430 widgets of your widget is missing here. This is covered by the
431 Gtk2::Ex::FormFactory::Layout module. So create your own layouter and
432 add the $layouter->build_TYPE($widget) method for your widget to it. If
433 your widget is a container you also need to implement at least the
434 generic $layouter->add_widget_to_TYPE method. For details about this
435 please refer to the documentation of Gtk2::Ex::FormFactory::Layout.
436 Nevertheless, if your widget is very specific to your application, e.g.
438 because it displays a very specific data structure, creating your own
439 Layout module just for that purpose is somewhat involved. In that case
440 you can implement this method:
441 $self->build_widget()
443 If implemented this method is called to actually create the Gtk2
444 widgets for your Gtk2::Ex::FormFactory widget.
445
447 JA~Xrn Reder <joern at zyn dot de>
448
450 Copyright 2004-2006 by JA~Xrn Reder.
451 This library is free software; you can redistribute it and/or modify it
453 under the terms of the GNU Library General Public License as published
454 by the Free Software Foundation; either version 2.1 of the License, or
455 (at your option) any later version.
456 This library is distributed in the hope that it will be useful, but
458 WITHOUT ANY WARRANTY; without even the implied warranty of
459 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
460 Library General Public License for more details.
461 You should have received a copy of the GNU Library General Public
463 License along with this library; if not, write to the Free Software
464 Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307
465 USA.
466perl v5.12.0 2006-07-02 Gtk2::Ex::FormFactory::Widget(3)