AppWindow/Ext/Help.pm untested

filter: Statementstmt 0.0% 0 / 219 Branchbran 0.0% 0 / 52 Conditioncond n/a MC/DCmcdc n/a Subroutinesub 0.0% 0 / 19 Podpod 0.0% 0 / 8 totaltotal 0.0% 0 / 298 CC 27 SCAR 49.6
CC
27
Cov
0%
CmdAbout
342.0
CmdHelp
20.0
CmdUpdates
20.0
CRAP 142.0
1 package Tk::AppWindow::Ext::Help;
2  
3 =head1 NAME
4  
5 Tk::AppWindow::Ext::Help - about box and help facilities
6  
7 =cut
8  
9 use strict;
10 use warnings;
11 use vars qw($VERSION);
12 $VERSION="0.17";
13  
14 use base qw( Tk::AppWindow::BaseClasses::Extension );
15  
16 use Tk;
17 use File::Basename;
18 require Tk::HList;
19 require Tk::NoteBook;
20 require Tk::PodViewer::Full;
21 require Tk::ROText;
22 require Tk::YADialog;
23  
24  
25 =head1 SYNOPSIS
26  
27 my $app = new Tk::AppWindow(@options,
28 -extensions => ['Help'],
29 );
30 $app->MainLoop;
31  
32 =head1 DESCRIPTION
33  
34 Adds a help facility and an about box to your application. Initiates
35 menu entries for them.
36  
37 =head1 CONFIG VARIABLES
38  
39 =over 4
40  
41 =item Switch: B<-aboutinfo>
42  
43 Specify the link to a hash. Possible keys:
44  
45 =over 4
46  
47 =item B<author>
48  
49 Your name
50  
51 =item B<components>
52  
53 Specify a list of modules you want the version numbers displayed.
54 Opens a new tab.
55  
56 =item B<email>
57  
58 Who to contact
59  
60 =item B<http>
61  
62 The website that supports this application
63  
64 =item B<license>
65  
66 Specify your license. By default it is set to I<Same as Perl>.
67 Set it to I<undef> if you do not want it to show.
68  
69 =item B<licensefile>
70  
71 Specify a plain text file as your license file. It is displayed in a new
72 tab with a L<Tk::ROText> widget.
73  
74 =item B<licenselink>
75  
76 Works only if the I<license> key is defined. Specify the weblink to your license. By default it
77 is set to L<https://dev.perl.org/licenses/>.
78 Set it to I<undef> if you do not want it to show.
79  
80 =item B<version>
81  
82 Specify the version of your application. By default it is set to the
83 version numer of the main window widget. Set it to undef if you do not
84 want it to show.
85  
86 =back
87  
88 =item Switch: B<-helpfile>
89  
90 Point to your help file. Can be a weblink.
91 If it is a I<.pod> file it will launch a dialog box with
92 a I<PodText> widget.
93  
94 =item Switch: B<-updatesmenuitem>
95  
96 Default value 0;
97  
98 If set a menu entrie 'Check for updates' is added to the menu.
99  
100 =back
101  
102 =head1 COMMANDS
103  
104 The following commands are defined.
105  
106 =over 4
107  
108 =item B<about>
109  
110 Pops the about box.
111  
112 =item B<help>
113  
114 Loads the helpfile in your system's default application or browser.
115  
116 =item B<updates>
117  
118 Pops the updates box and starts checking for updates.
119  
120 =back
121  
122 =cut
123  
124 sub new {
125 my $class = shift;
126 my $self = $class->SUPER::new(@_);
127  
128 $self->{ABOUTDEFAULTS} = {
129 version => $self->GetAppWindow->VERSION,
130 license => 'Same as Perl',
131 licenselink => 'https://dev.perl.org/licenses/',
132 };
133 $self->addPreConfig(
134 -aboutinfo => ['PASSIVE', undef, undef, { }],
135 -helpfile => ['PASSIVE'],
136 -reportproblemlink => ['PASSIVE'],
137 -updatesmenuitem => ['PASSIVE', undef, undef, 0],
138 );
139  
140 $self->cmdConfig(
141 about => ['CmdAbout', $self],
142 updates => ['CmdUpdates', $self],
143 report_problem => ['CmdReportProblem', $self],
144 help => ['CmdHelp', $self],
145 );
146 return $self;
147 }
148  
149 =head1 METHODS
150  
151 =over 4
152  
153 =cut
154  
155 sub CmdAbout {
156 my $self = shift;
157 my $inf = $self->configGet('-aboutinfo');
158 my $defaults = $self->{ABOUTDEFAULTS};
159 for (keys %$defaults) {
160 $inf->{$_} = $defaults->{$_} unless exists $inf->{$_}
161 }
162  
163 my $db = $self->YADialog(
164 -buttons => ['Close'],
165 -defaultbutton => 'Close',
166 -title => 'About ' . $self->appName,
167 );
168  
169 my @padding = (-padx => 2);
170 my $nb; #NoteBookWidget;
171 my $ap; #About frame widget
172 my $addnb = sub {
173 unless (defined $nb) {
174 $nb = $db->NoteBook->pack(-expand => 1, -fill => 'both') ;
175 $ap = $nb->add('about', -label =>'About');
176 }
177 };
178 my @col0 = ( -column => 0, -sticky => 'e', @padding);
179 my @col1 = ( -column => 1, -sticky => 'w', @padding);
180  
181 if (my $file = $inf->{licensefile}) {
182 &$addnb;
183 my $lp = $nb->add('licence', -label => 'License');
184 my $t = $lp->Scrolled('ROText',
185 -width => 8,
186 -height => 8,
187 -scrollbars => 'osoe'
188 )->pack(-expand =>1, -fill => 'both', @padding);
189 if (open(my $fh, '<', $file)) {
190 while (my $line = <$fh>) {
191 $t->insert('end', $line)
192 }
193 close $fh
194 }
195 } else {
196 $ap = $db->Frame->pack(-expand => 1, -fill => 'both') unless defined $ap;
197 }
198  
199 if (exists $inf->{components}) {
200 &$addnb;
201 my $lp = $nb->add('components', -label => 'Components');
202 my $cl = $lp->Scrolled('HList',
203 -width => 4,
204 -height => 4,
205 -columns => 2,
206 -header => 1,
207 -scrollbars => 'osoe',
208 )->pack(-expand => 1, -fill => 'both', @padding);
209 my $count = 0;
210 for ('Module', 'Version') {
211 my $header = $cl->Frame;
212 $header->Label(-text => $_)->pack(-side => 'left');
213 $cl->headerCreate($count,
214 -headerbackground => $self->configGet('-background'),
215 -itemtype => 'window',
216 -widget => $header
217 );
218 $count ++;
219 }
220 my $components = $inf->{components};
221 my $row = 0;
222 for (@$components) {
223 my $module = $_;
224 my $version = $self->moduleVersion($module);
225 if (defined $version) {
226 $cl->add($row, -data => "$module: $version\n");
227 $cl->itemCreate($row, 0, -text => $module);
228 $cl->itemCreate($row, 1, -text => $version);
229 $row++
230 }
231 }
232 $lp->Button(
233 -text => 'Copy',
234 -command => sub {
235 my $text = '';
236 for (0 .. $row - 1) {
237 $text = $text . $cl->infoData($_);
238 }
239 $self->clipboardClear;
240 $self->clipboardAppend($text);
241 }
242 )->pack;
243 } else {
244 $ap = $db->Frame->pack(-expand => 1, -fill => 'both') unless defined $ap;
245 }
246  
247 my $lg = $self->configGet('-logo');
248 if (defined $lg) {
249 $ap->Label(-image => $self->Photo(-file => $lg))->pack;
250 }
251 my $gf = $ap->Frame->pack(-expand => 1, -fill => 'both');
252 my $row = 0;
253 my $ver = $inf->{version};
254 if (defined $ver) {
255 $gf->Label(-text => 'Version:')->grid(-row => $row, @col0);
256 my $l = $gf->Label(-text => $ver)->grid(-row => $row, @col1);
257 $row ++;
258 }
259 my $aut = $inf->{author};
260 if (defined $aut) {
261 $gf->Label(-text => 'Author:')->grid(-row => $row, @col0);
262 $gf->Label(-text => $aut)->grid(-row => $row, @col1);
263 $row ++;
264 }
265 my $mail = $inf->{email};
266 if (defined $mail) {
267 $gf->Label(-text => 'E-mail:')->grid(-row => $row, @col0);
268 my $url = $gf->Label(
269 -text => $mail,
270 )->grid(-row => $row, @col1);
271 $self->ConnectURL($url, "mailto:$mail");
272 $row ++;
273 }
274 my $web = $inf->{http};
275 if (defined $web) {
276 $gf->Label(-text => 'Website:')->grid(-row => $row, @col0);
277 my $url = $gf->Label(
278 -text => $web,
279 )->grid(-row => $row, @col1);
280 $self->ConnectURL($url, $web);
281 $row ++;
282 }
283 my $lc = $inf->{license};
284 if (defined $lc) {
285 if (defined $lc) {
286 $gf->Label(-text => 'License:')->grid(-row => $row, @col0);
287 my $l = $gf->Label(-text => $lc)->grid(-row => $row, @col1);
288 my $lcu = $inf->{licenselink};
289 if (defined $lcu) {
290 $self->ConnectURL($l, $lcu) if defined $lcu;
291 }
292 }
293 $row ++;
294 }
295 $db->Show(-popover => $self->GetAppWindow);
296 $db->destroy;
297 }
298  
299 sub CmdHelp {
300 my $self = shift;
301 my $file = $self->configGet('-helpfile');
302 if (defined $file) {
303 if ($file =~ /\.pod$/) { #is pod
304 my $db = $self->YADialog(
305 -buttons => ['Close'],
306 -title => 'Help',
307 );
308 my @podopt = ();
309 my $art = $self->extGet('Art');
310 @podopt = (
311 -nextimage => $art->createCompound(
312 -image => $art->getIcon('go-next', 22),
313 -text => 'Next',
314 ),
315 -previmage => $art->createCompound(
316 -image => $art->getIcon('go-previous', 22),
317 -text => 'Previous',
318 ),
319 -zoominimage => $art->createCompound(
320 -image => $art->getIcon('zoom-in', 22),
321 -text => 'Zoom in',
322 ),
323 -zoomoutimage => $art->createCompound(
324 -image => $art->getIcon('zoom-out', 22),
325 -text => 'Zoom out',
326 ),
327 -zoomresetimage => $art->createCompound(
328 -image => $art->getIcon('zoom-original', 22),
329 -text => 'Zoom reset',
330 ),
331 ) if defined $art;
332
333 my $pod = $db->PodViewerFull(@podopt,
334 -width => 80,
335 -height => 20,
336 )->pack(-expand => 1, -fill => 'both');
337 $self->after(100, sub { $pod->load($file) });
338 $db->Show(-popover => $self->GetAppWindow);
339 $db->destroy;
340 } else {
341 $self->openURL($file);
342 }
343 }
344 }
345  
346 sub CmdReportProblem {
347 my $self = shift;
348 my $url = $self->configGet('-reportproblemlink');
349 $self->openURL($url) if defined $url
350 }
351  
352 sub CmdUpdates {
353 my $self = shift;
354  
355 my $db = $self->YADialog(
356 -buttons => ['Close'],
357 -defaultbutton => 'Close',
358 -nowithdraw => 1,
359 -title => 'Updates check',
360 );
361 my $txt = $db->Scrolled('ROText',
362 -tabs => '8m',
363 -width => 36,
364 -wrap => 'none',
365 -height => 12,
366 -scrollbars => 'osoe',
367 )->pack(-padx => 2, -pady => 2, -expand => 1, -fill => 'both');
368  
369 my $app = $self->GetAppWindow;
370  
371 my @modules = (ref $app);
372 my $inf = $self->configGet('-aboutinfo');
373 if (exists $inf->{components}) {
374 my $c = $inf->{components};
375 push @modules, @$c;
376 }
377 $self->after(200, sub {
378 $db->Subwidget('Close')->configure(-state => 'disabled');
379 for (@modules) {
380 my $mod = $_;
381 $txt->insert('end', "Please wait ...");
382 $db->update;
383 my $output = "$mod\n";
384 my $string = `cpan -D $mod`;
385 while ($string ne '') {
386 if ($string =~ s/^(\s+Installed:\s+\d.*\n)//) {
387 $output = $output . $1
388 } elsif ($string =~ s/^(\s+CPAN:\s*\d.*\n)//) {
389 $output = $output . $1;
390 last;
391 } else {
392 $string =~ s/^.*\n|$//
393 }
394 }
395 my $end = $txt->index('end -1c');
396 $txt->delete("$end linestart", $end);
397 $txt->insert('end', $output);
398 $txt->see('end');
399 $db->update;
400 }
401 $txt->insert('end', "Done checking.\n");
402 $txt->see('end');
403 $db->Subwidget('Close')->configure(-state => 'normal');
404 $db->configure(-nowithdraw => 0);
405 });
406 $db->show(-popover => $app);
407 $db->destroy;
408 }
409  
410 sub ConnectURL {
411 my ($self, $widget, $url) = @_;
412 $widget->configure(-cursor => 'hand2');
413 $widget->bind('<Enter>', sub {
414 $widget->configure(-foreground => $self->configGet('-linkcolor'))
415 });
416 $widget->bind('<Leave>', sub {
417 $widget->configure(-foreground => $self->configGet('-foreground'))
418 });
419 $widget->bind('<Button-1>', sub {
420 $self->openURL($url)
421 });
422 }
423  
424 sub MenuItems {
425 my $self = shift;
426 my @items = (
427 #This table is best viewed with tabsize 3.
428 # type menupath label cmd icon keyb config variable
429 [ 'menu_normal', 'appname::Quit', "~About", 'about', 'help-about', 'SHIFT+F1' ],
430 [ 'menu_normal', 'appname::Quit', "~Help", 'help', 'help-browser', 'F1', ],
431 );
432
433 push @items, [ 'menu_normal', 'appname::Quit', "~Check for updates", 'updates' ]
434 if $self->configGet('-updatesmenuitem');
435 push @items, [ 'menu_normal', 'appname::Quit', "~Report a problem", 'report_problem' ]
436 if defined $self->configGet('-reportproblemlink');
437 push @items, [ 'menu_separator', 'appname::Quit', 'h1'];
438 return @items
439 }
440  
441 =item B<moduleVersion>I<($module)>
442  
443 Returns the version number of I<$module>. Returns undef if the module is not found.
444  
445 =cut
446  
447 sub moduleVersion {
448 my ($self, $module) = @_;
449 my $version;
450 my $s = '->VERSION';
451 eval "use $module; \$version = $module$s";
452 return $version
453 }
454  
455 =back
456  
457 =head1 AUTHOR
458  
459 Hans Jeuken (hanje at cpan dot org)
460  
461 =head1 BUGS
462  
463 Unknown. If you find any, please contact the author.
464  
465 =head1 SEE ALSO
466  
467 =over 4
468  
469 =item L<Tk::AppWindow>
470  
471 =item L<Tk::AppWindow::BaseClasses::Extension>
472  
473 =back
474  
475 =cut
476  
477  
478 1;
479  
480  
481  
482