Debian Codegraph @

Debconf/FrontEnd.pm

raw
1 #!/usr/bin/perl
2
3 =head1 NAME
4
5 Debconf::FrontEnd - base FrontEnd
6
7 =cut
8
9 package Debconf::FrontEnd;
10 use warnings;
11 use strict;
12 use Debconf::Gettext;
13 use Debconf::Priority;
14 use Debconf::Log ':all';
15 use base qw(Debconf::Base);
16
17 =head1 DESCRIPTION
18
19 This is the base of the FrontEnd class. Each FrontEnd presents a
20 user interface of some kind to the user, and handles generating and
21 communicating with Elements to form that FrontEnd.
22
23 =head1 FIELDS
24
25 =over 4
26
27 =item elements
28
29 A reference to an array that contains all the elements that the FrontEnd
30 needs to show to the user.
31
32 =item interactive
33
34 Is this an interactive FrontEnd?
35
36 =item capb
37
38 Holds any special capabilities the FrontEnd supports.
39
40 =item title
41
42 The title of the FrontEnd.
43
44 =item requested_title
45
46 The title last explicitly requested for the FrontEnd. May be temporarily
47 overridden by another title, e.g. for progress bars.
48
49 =item info
50
51 A question containing an informative message to be displayed, without
52 requiring any acknowledgement from the user. FrontEnds may choose not to
53 implement this. If they do implement it, they should display the info
54 persistently until some other info comes along.
55
56 =item backup
57
58 A flag that Elements can set when they are displayed, to tell the FrontEnd
59 that the user has indicated they want to back up.
60
61 =item capb_backup
62
63 This will be set if the confmodule states it has the backup capability.
64
65 =item progress_bar
66
67 The element used for the currently running progress bar, if any.
68
69 =item need_tty
70
71 Set to true if the frontend needs a tty. Defaults to true.
72
73 Note that setting this to true does not ensure that the frontend actually
74 gets a tty. It does let debconf abort in cases where the selected frontend
75 cannot work due to it being impossible to get a tty for it.
76
77 =back
78
79 =head1 METHODS
80
81 =over 4
82
83 =item init
84
85 Sets several of the fields to defaults.
86
87 =cut
88
89 sub init {
90 my $this=shift;
91
92 $this->elements([]);
93 $this->interactive('');
94 $this->capb('');
95 $this->title('');
96 $this->requested_title('');
97 $this->info(undef);
98 $this->need_tty(1);
99 }
100
101 =item elementtype
102
103 What type of elements this frontend uses. Defaults to returning the same
104 name as the frontend, but tightly-linked frontends might want to share
105 elements; if so, one can override this with a method that returns the name
106 of the other.
107
108 This may be called as either a class or an object method.
109
110 =cut
111
112 sub elementtype {
113 my $this=shift;
114
115 my $ret;
116 if (ref $this) {
117 # Called as object method.
118 ($ret) = ref($this) =~ m/Debconf::FrontEnd::(.*)/;
119 }
120 else {
121 # Called as class method.
122 ($ret) = $this =~ m/Debconf::FrontEnd::(.*)/;
123 }
124 return $ret;
125 }
126
127 my %nouse;
128
129 sub _loadelementclass {
130 my $this=shift;
131 my $type=shift;
132 my $nodebug=shift;
133
134 # See if we need to load up the object class.. The eval
135 # inside here is leak-prone if run multiple times on a
136 # given type, so make sure to only ever do it once per type.
137 if (! UNIVERSAL::can("Debconf::Element::$type", 'new')) {
138 return if $nouse{$type};
139 eval qq{use Debconf::Element::$type};
140 if ($@ || ! UNIVERSAL::can("Debconf::Element::$type", 'new')) {
141 warn sprintf(gettext("Unable to load Debconf::Element::%s. Failed because: %s"), $type, $@) if ! $nodebug;
142 $nouse{$type}=1;
143 return;
144 }
145 }
146 }
147
148 =item makeelement
149
150 Creates an Element of the type used by this FrontEnd. Pass in the question
151 that will be bound to the Element. It returns the generated Element, or false
152 if it was unable to make an Element of the given ype.
153
154 This may be called as either a class or an object method.
155
156 Normally, it outputs debug codes if creating the Element fails. If failure
157 is expected, a second parameter can be passed with a true value to turn
158 off those debug messages.
159
160 =cut
161
162 sub makeelement {
163 my $this=shift;
164 my $question=shift;
165 my $nodebug=shift;
166
167 # Figure out what type of frontend this is.
168 my $type=$this->elementtype.'::'.ucfirst($question->type);
169 $type=~s/::$//; # in case the question has no type..
170
171 $this->_loadelementclass($type, $nodebug);
172
173 my $element="Debconf::Element::$type"->new(question => $question);
174 return if ! ref $element;
175 return $element;
176 }
177
178 =item add
179
180 Adds an Element to the list to be displayed to the user. Just pass the
181 Element to add. Note that it detects multiple Elements that point to the
182 same Question and only adds the first.
183
184 =cut
185
186 sub add {
187 my $this=shift;
188 my $element=shift;
189
190 foreach (@{$this->elements}) {
191 return if $element->question == $_->question;
192 }
193
194 $element->frontend($this);
195 push @{$this->elements}, $element;
196 }
197
198 =item go
199
200 Display accumulated Elements to the user.
201
202 This will normally return true, but if the user indicates they want to
203 back up, it returns false.
204
205 =cut
206
207 sub go {
208 my $this=shift;
209 $this->backup('');
210 foreach my $element (@{$this->elements}) {
211 $element->show;
212 return if $this->backup && $this->capb_backup;
213 }
214 return 1;
215 }
216
217 =item progress_start
218
219 Start a progress bar.
220
221 =cut
222
223 sub progress_start {
224 my $this=shift;
225 my $min=shift;
226 my $max=shift;
227 my $question=shift;
228
229 my $type = $this->elementtype.'::Progress';
230 $this->_loadelementclass($type);
231
232 my $element="Debconf::Element::$type"->new(question => $question);
233 unless (ref $element) {
234 # TODO: error somehow
235 return;
236 }
237 $element->frontend($this);
238 $element->progress_min($min);
239 $element->progress_max($max);
240 $element->progress_cur($min);
241
242 $element->start;
243
244 $this->progress_bar($element);
245 }
246
247 =item progress_set
248
249 Set the value of a progress bar, within the minimum and maximum values
250 passed when starting it.
251
252 Returns true unless the progress bar was canceled by the user.
253 Cancelation is indicated by the progress bar object's set method returning
254 false.
255
256 =cut
257
258 sub progress_set {
259 my $this=shift;
260 my $value=shift;
261
262 return $this->progress_bar->set($value);
263 }
264
265 =item progress_step
266
267 Step a progress bar by the given amount.
268
269 Returns true unless the progress bar was canceled by the user.
270 Cancelation is indicated by the progress bar object's set method returning
271 false.
272
273 =cut
274
275 sub progress_step {
276 my $this=shift;
277 my $inc=shift;
278
279 return $this->progress_set($this->progress_bar->progress_cur + $inc);
280 }
281
282 =item progress_info
283
284 Set an informational message to be displayed along with the progress bar.
285
286 Returns true unless the progress bar was canceled by the user.
287 Cancelation is indicated by the progress bar object's info method returning
288 false.
289
290 =cut
291
292 sub progress_info {
293 my $this=shift;
294 my $question=shift;
295
296 return $this->progress_bar->info($question);
297 }
298
299 =item progress_stop
300
301 Tear down a progress bar.
302
303 =cut
304
305 sub progress_stop {
306 my $this=shift;
307
308 $this->progress_bar->stop;
309 $this->progress_bar(undef);
310 }
311
312 =item clear
313
314 Clear out the accumulated Elements.
315
316 =cut
317
318 sub clear {
319 my $this=shift;
320
321 $this->elements([]);
322 }
323
324 =item default_title
325
326 This sets the title field to a default. Pass in the name of the
327 package that is being configured.
328
329 =cut
330
331 sub default_title {
332 my $this=shift;
333
334 $this->title(sprintf(gettext("Configuring %s"), shift));
335 $this->requested_title($this->title);
336 }
337
338 =item shutdown
339
340 This method should be called before a frontend is shut down.
341
342 =cut
343
344 sub shutdown {}
345
346 =back
347
348 =head1 AUTHOR
349
350 Joey Hess <[email protected]>
351
352 =cut
353
354 1