| 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 |