/ 
PPM-Win32-PrintBox-0.001
/ Win32::PrintBox

NAME

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

VERSION

Version 0.01

SYNOPSIS

use Win32::PrintBox;

print "Program output\n";
warn "I am here\n";

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 .

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

This module does not play nicely with other modules that use the __WARN__ signal handler, for obvious reasions.

compiler errors/warnings will not be visible if the script is executed via wperl

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.

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.