1Gtk2::Ex::FormFactory(3U)ser Contributed Perl DocumentatiGotnk2::Ex::FormFactory(3)
2
6 Gtk2::Ex::FormFactory - Makes building complex GUI's easy
7
9 #-- Refer to http://www.exit1.org/ for
10 #-- a comprehensive online documentation.
11 #-- Read Gtk2::Ex::FormFactory::Intro
13 use Gtk2::Ex::FormFactory;
15 my $context = Gtk2::Ex::FormFactory::Context->new;
17 $context->add_object (
19 name => "worksheet",
20 object => My::Worksheet->new,
21 );
22 # derived from Gtk2::Ex::FormFactory::Layout
24 my $layouter = My::Layout->new;
25 # derived from Gtk2::Ex::FormFactory::Rules
27 my $rule_checker = My::Rules->new;
28 my $ff = Gtk2::Ex::FormFactory->new (
30 context => $context,
31 layouter => $layouter,
32 rule_checker => $rule_checker,
33 content => [
34 Gtk2::Ex::FormFactory::Window->new (
35 title => "Worksheet Editor",
36 content => [
37 Gtk2::Ex::FormFactory::Form->new (
38 title => "Main data",
39 content => [
40 Gtk2::Ex::FormFactory::Entry->new (
41 label => "Worksheet title",
42 attr => "worksheet.title",
43 tip => "Title of this worksheet",
44 ),
45 #-- More widgets...
46 ],
47 ),
48 Gtk2::Ex::FormFactory->DialogButtons->new,
49 ],
50 ),
51 ],
52 );
53 $ff->open;
55 $ff->update;
56 Gtk2->main;
58
60 With Gtk2::Ex::FormFactory you can build a GUI which consistently
61 represents the data of your application.
62
64 This is a framework which tries to make building complex GUI's easy, by
65 offering these two main features:
66 * Consistent looking GUI without the need to code resp. tune
68 each widget by hand. Instead you declare the structure of your
69 GUI, connect it to the data of your program (which should be
70 a well defined set of objects) and control how this structure
71 is transformed into a specific layout in a very generic way.
72 * Automatically keep widget and object states in sync (in both
74 directions), even with complex data structures with a lot of
75 internal dependencies, object nesting etc.
76 This manpage describes the facilities of Gtk2::Ex::FormFactory objects
78 which are only a small part of the whole framework. To get a full
79 introduction and overview of how this framework works refer to
80 Gtk2::Ex::FormFactory::Intro.
81
83 Gtk2::Ex::FormFactory::Widget
84 +--- Gtk2::Ex::FormFactory::Container
85 +--- Gtk2::Ex::FormFactory
86
88 Attributes are handled through the common get_ATTR(), set_ATTR() style
89 accessors, but they are mostly passed once to the object constructor
90 and must not be altered after the associated FormFactory was built.
91 context = Gtk2::Ex::FormFactory::Context [optional]
93 This is the Context of this FormFactory. The Context connects your
94 application objects and their attributes with the GUI build through
95 the FormFactory. Refer to Gtk2::Ex::FormFactory::Context for
96 details.
97 If you omit this option in the new() object constructor an empty
99 Context is created which can be accessed with get_context.
100 layouter = Gtk2::Ex::FormFactory::Layout [optional]
102 This is the Layout module of this FormFactory. The Layout module
103 actually builds the GUI and thus controls all details of
104 appearance. Refer to Gtk2::Ex::FormFactory::Layout for details, if
105 you're interested in writing your own Layout module.
106 If you omit this option in the new() object constructor a default
108 Gtk2::Ex::FormFactory::Layout object is created which can be
109 accessed with get_layouter.
110 rule_checker = Gtk2::Ex::FormFactory::Rules [optional]
112 This is the rule checker module of this FormFactory. It's
113 responsible to check user input against a set of rules which may be
114 associated with a widget.
115 Refer to Gtk2::Ex::FormFactory::Rules for details, if you're
117 interested in writing your own rule checker module.
118 If you omit this option in the new() object constructor a default
120 Gtk2::Ex::FormFactory::Rules object is created which can be
121 accessed with get_rule_checker.
122 sync = BOOL [optional]
124 By default all changes on the GUI trigger corresopndent updates on
125 your application objects immediately. If you want to build dialogs
126 with local changes on the GUI only, e.g. to be able to implement a
127 Cancel button in a simple fashion (refer to
128 Gtk2::Ex::FormFactory::DialogButtons), you may switch this
129 synchronisation off by setting sync to FALSE.
130 But note that asynchronous dialogs are static. Dependencies between
132 objects and attributes, which are defined in the associated
133 Gtk2::Ex::FormFactory::Context, don't work on widget/GUI level.
134 That's why automatic dependency resolution / widget updating only
135 works for FormFactory's with sync set to TRUE.
136 parent_ff = Gtk2::Ex::FormFactory object [optional]
138 You may specify a parent Gtk2::Ex::FormFactory object. The Gtk
139 Window of this FormFactory will be set transient to the Gtk Window
140 of the parent FormFactory.
141
143 $form_factory->open ( [ hide => BOOL ])
144 This actually builds and displays the GUI, if you set the hide
145 parameter to a true value. Until this method is called you can add
146 new or modify existent Widgets of this FormFactory.
147 If you set hide you need to call $form_factory->show later,
149 otherwise all widgets will keep invisible.
150 No object data will be transfered to the GUI, so it will be more or
152 less empty. Call update to put data into the GUI.
153 $form_factory->update ()
155 After building the GUI you should call update to transfer your
156 application data to the GUI.
157 $form_factory->ok ()
159 This method applies all changes of a asynchronous FormFactory and
160 closes it afterwards.
161 $form_factory->apply ()
163 All changes to Widgets inside this FormFactory are applied to the
164 associated application object attributes.
165 Useful only in a FormFactory with sync=FALSE.
167 $form_factory->close ()
169 When you exit the program you must call close on all FormFactories
170 which are actually open. Otherwise you will get error messages like
171 this from Perl's garbage collector:
172 Attempt to free unreferenced scalar: SV 0x85d7374
174 during global destruction.
175 That's because circular references are necessary between Gtk2 and
177 Gtk2::Ex::FormFactory widgets. These references need first to be
178 deleted until Perl can exit the program cleanly.
179 $form_factory->cancel
181 Currently this simply calls $form_factory->close.
182 $form_factory->open_confirm_window ( parameters )
184 This is a convenience method to open a confirmation window which is
185 set modal and transient to the window of this FormFactory. The
186 following parameters are known:
187 message The message resp. question, HTML markup allowed
189 position Position of the dialog. Defaults to 'center-on-parent'.
190 Other known values are: 'none', 'center', 'mouse'
191 and 'center-always'
192 yes_callback Code reference to be called if the user
193 answered your question with "Yes"
194 no_callback Code reference to be called if the user
195 answered your question with "No"
196 yes_label (Stock-)Label for the yes button. Default 'gtk-yes'
197 no_label (Stock-)Label for the no button. Default 'gtk-no'
198 $form_factory->open_message_window ( parameters )
200 This is a convenience method to open a message window which is set
201 modal and transient to the window of this FormFactory. The
202 following parameters are known:
203 type Type of the dialog. Defaults to 'info'.
205 Other known values are: 'warning', 'question' and 'error'
206 message The message, HTML markup allowed
207 position Position of the dialog. Defaults to 'center-on-parent'.
208 Other known values are: 'none', 'center', 'mouse'
209 and 'center-always'
210 $filename = $form_factory->get_image_path
212 This is a convenience method to find a filename inside Perl's @INC
213 path. You will need this if you ship images or icons inside your
214 module namespace and want to retreive the actual filenames of them.
215 $form_factory->change_mouse_cursor ( $type [, $gtk_widget] )
217 This convenience method changes the mouse cursor of the window of
218 this FormFactory, or of an arbitrary widget passed as $gtk_widget.
219 $type is the cursor type, e.g. "watch" for a typical busy /
220 sandglass cursor. Refer to the Gtk documentation for a complete
221 list of possible mouse cursors.
222
224 Jörn Reder <joern at zyn dot de>
225
227 Copyright 2004-2006 by Jörn Reder.
228 This library is free software; you can redistribute it and/or modify it
230 under the terms of the GNU Library General Public License as published
231 by the Free Software Foundation; either version 2.1 of the License, or
232 (at your option) any later version.
233 This library is distributed in the hope that it will be useful, but
235 WITHOUT ANY WARRANTY; without even the implied warranty of
236 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
237 Library General Public License for more details.
238 You should have received a copy of the GNU Library General Public
240 License along with this library; if not, write to the Free Software
241 Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307
242 USA.
243
245 Hey! The above document had some coding errors, which are explained
246 below:
247 Around line 564:
249 Non-ASCII character seen before =encoding in 'Jörn'. Assuming UTF-8
250perl v5.28.0 2011-08-11 Gtk2::Ex::FormFactory(3)