/ 
Win32-PrintBox-0.004
River stage zero No dependents
/ Win32::PrintBox

NAME

Win32::PrintBox - Redirects print STDOUT and warn statements to a message box under wperl

SYNOPSIS

use Win32::PrintBox;
Win32::PrintBox::init();

print "Program output\n";
warn "Error reported: $!\n";

This program makes perl scripts act like pseudo GUI programs when executed under wperl, without any additional programming. When running from a shell, it does not interfere. However, if a cmd window is created (by clicking on a perl script from File Explorer), it will add a prompt to let the user see the output before the window closes.

DESCRIPTION

At startup, the module checks if the script was started in Windows Mode (it looks for wperl in $^X). If so, it creates a new glob (*MSG_FH), and ties the PRINT, PRINTF and DESTROY methods to it, to convert warn and print statements into Win32 message boxes. It also sets up a handler to trap __WARN__ signals, to do the same.

For warn, output is immediately sent to the user as a message box.

For print and printf, the output is buffered. When a PAGE_SIZE of output is collected, it is displayed to the user. When DESTROY is called, any remaining output left in the buffer is also displayed. The user may press CANCEL to exit the script prematurely.

In console mode (non-windows), this module does nothing, unless the script was started from a windows program (File Explorer or other windows application). In this case, A DOS pause command is emulated at the end of the script, so that the user can acknowledge console output before the console window closes.

SUBROUTINES/METHODS

new

Sets up a handler to catch __WARN__ signals, and process them with sub WarnBox .

init

Initialization logic. Encapsulated in a subroutine so it can be called during testing. This used to be called when the module was loaded, but is now left for the user to invoke, since it interfered with test suites.

pause

Displays "Press Enter to continue" and waits for user input when a console window is about to close.

pause_in

Wrapper for <>, for testing purposes. Allows for detection of <> request, without requiring user input.

WarnBox

Sends warn text to a Win32::MsgBox immediately. Script dies if user presses CANCEL.

PrintMsgBox

This sub is called via a tied file handle when there is a print or printf to STDOUT. Normally it just buffers the input, and returns.

If enough data is collected, the page full of is presented to the user in one shot via a message box and the buffer is emptied. The user acknowleges the message by clicking OK, but can exit, by clicking CANCEL.

Does not actually override the print function, but traps the currently selected file handle, and redirects the output directed to the selected filehandle, and handles it with the subroutines within this package. Not exactly easy to understand, but works very nicely.

No need to override CORE::print or CORE::GLOBAL::print. Which does not work anyways.

CMD_Cursor

Examines the cursor location of the console window. If a new command prompt window is opened, then the 'y' cursor position will be at row 1. This will be used in the END block to decide whether a `Press any key to continue` should be added.

get_page_size

Returns the configured number of lines of collected text, before a message box is displayed. Default is 25.

set_page_size

Sets the configured number of lines of collected text, before a message box is displayed.

AUTHOR

David Clarke, <dclarke@cpan.org>

BUGS

Please report any bugs or feature requests to bug-win32-printbox at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Win32-PrintBox. I will be notified, and then you will automatically be notified of progress on your bug as I make changes.

NOTES

To embed a perl script in a .bat file, add this one-liner at the top of your perl script.

@echo = @echo if 0;#>nul & perl -S -w %0 %* & goto :EOF

It is not as robust as the script generated by pl2bat, but works well on modern Win32 systems. Figuring out how it works is left as an excercise for the reader.

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc Win32::PrintBox

You can also look for information at:

ACKNOWLEDGEMENTS

Concepts for intercepting warn and print statements are borrowed from the Apache::ASP module by Joshua Chamas.

The idea for checking the cursor location came from http://www.codeguru.com/cpp/misc/misc/consoleapps/article.php/c15893/Pause-Before-Exiting-a-Console-Application.htm. Thanks to Marc Gregoire. I tried using Win32::Console to capture the initial cursor position, but Win32::Console::ANSI seemed to work better.

Die handler (e.g. for handlind compile time errors) came from Win32::Die, by Alex Vandiver and Mike Accardo.

Chaining of WARN/DIE handlers came from Win32::GUI::Carp by Cory Johns.

LICENSE AND COPYRIGHT

Copyright 2012 David Clarke

This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.

See http://dev.perl.org/licenses/ for more information.