1Gtk2::Ex::FormFactory(3U)ser Contributed Perl DocumentatiGotnk2::Ex::FormFactory(3)
2
3
4

NAME

6       Gtk2::Ex::FormFactory - Makes building complex GUI's easy
7

SYNOPSIS

9         #-- Refer to http://www.exit1.org/ for
10         #-- a comprehensive online documentation.
11
12         #-- Read Gtk2::Ex::FormFactory::Intro
13
14         use Gtk2::Ex::FormFactory;
15
16         my $context  = Gtk2::Ex::FormFactory::Context->new;
17
18         $context->add_object (
19           name   => "worksheet",
20           object => My::Worksheet->new,
21         );
22
23         # derived from Gtk2::Ex::FormFactory::Layout
24         my $layouter = My::Layout->new;
25
26         # derived from Gtk2::Ex::FormFactory::Rules
27         my $rule_checker = My::Rules->new;
28
29         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
54         $ff->open;
55         $ff->update;
56
57         Gtk2->main;
58

ABSTRACT

60       With Gtk2::Ex::FormFactory you can build a GUI which consistently
61       represents the data of your application.
62

DESCRIPTION

64       This is a framework which tries to make building complex GUI's easy, by
65       offering these two main features:
66
67         * 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
73         * 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
77       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

OBJECT HIERARCHY

83         Gtk2::Ex::FormFactory::Widget
84         +--- Gtk2::Ex::FormFactory::Container
85              +--- Gtk2::Ex::FormFactory
86

ATTRIBUTES

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
92       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
98           If you omit this option in the new() object constructor an empty
99           Context is created which can be accessed with get_context.
100
101       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
107           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
111       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
116           Refer to Gtk2::Ex::FormFactory::Rules for details, if you're
117           interested in writing your own rule checker module.
118
119           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
123       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
131           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
137       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

METHODS

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
148           If you set hide you need to call $form_factory->show later,
149           otherwise all widgets will keep invisible.
150
151           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
154       $form_factory->update ()
155           After building the GUI you should call update to transfer your
156           application data to the GUI.
157
158       $form_factory->ok ()
159           This method applies all changes of a asynchronous FormFactory and
160           closes it afterwards.
161
162       $form_factory->apply ()
163           All changes to Widgets inside this FormFactory are applied to the
164           associated application object attributes.
165
166           Useful only in a FormFactory with sync=FALSE.
167
168       $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
173             Attempt to free unreferenced scalar: SV 0x85d7374
174               during global destruction.
175
176           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
180       $form_factory->cancel
181           Currently this simply calls $form_factory->close.
182
183       $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
188             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
199       $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
204             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
211       $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
216       $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

AUTHORS

224        Jörn Reder <joern at zyn dot de>
225
227       Copyright 2004-2006 by Jörn Reder.
228
229       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
234       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
239       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

POD ERRORS

245       Hey! The above document had some coding errors, which are explained
246       below:
247
248       Around line 564:
249           Non-ASCII character seen before =encoding in 'Jörn'. Assuming UTF-8
250
251
252
253perl v5.28.0                      2011-08-11          Gtk2::Ex::FormFactory(3)
Impressum