Overview of the Tkprint 1.1 package


This extension package is for use with stubs aware binary releases of Tcl/Tk 8.1 and later that run under the Windows operating systems. The extension implements native mode printing of canvas and text widgets as well as the capture of widgets from the screen to files in Windows .BMP format.

This package enhances the original Tkprint 1.0 package by adding some basic pagination capabilities, enabling the use of user specified fonts for the printing of text widgets, and the capture of widgets displayed under Tcl/Tk using the widget path to identify the window.

Installation

Download the Tkprint 1.1 archive into your $tcl_library directory. Unpack the archive with a utility that will preserve the embedded directory structure (Such as unzip.exe). This will create a sub-directory named tkprint1.1 which contains the extension .dll file, a pkgIndex.tcl file and some support files.

Using the Tkprint 1.1 Extension

The extension can be loaded using the following command...

    package require Tkprint 1.1

It will make available the commands "PrintCanvas","Print","Capture" ,"PrinterCapabilities","MetaFile", "PrintMetafile" and "PrintWindow", as well as loading the script file "window.tcl" which comes with the distribution. The "window.tcl" file shows how to implement the script based capture of widgets. Note that because the "PrintWindow" function has to ask you for a printer, you can not implement operator free printing of widgets. You can, however, implement operator free capture of widgets to image files.

The distribution provides a file named "console.tcl". This is a modified version of the standard "console.tcl" file that comes with the Tcl/Tk distribution. Its menus are enhanced to add a "Print" and a "Capture" command that allow the printing of the contents of the interactive console text widget, or its capture as an image file. If you want to use this version of the console just copy it into the $tk_library directory. Its wise to backup the original version before you do the copy. Note that this version of the "console.tcl" file can also make use of the Help extension found on this site.

Licence

Free for non-commercial use. Redistribution permitted. Resale prohibited.

Warranty

None. Use at your own risk. This software is provided as is, without any warranty of any kind.

Command Reference

Generic Options

The general form of the commands provided by this package is as follows...

command path ?-file? ?file? ?-title? ?title? ?-font? ?font? ?-margins? ?margins? ?-paginate? ?boolean? ?-position? ?position? ?-scale? ?scale? ?-pagefont? ?pagefont? ?-clipboard? ?boolean? ?-header? ?header? ?-footer? ?footer?

where the command is one of the supported commands (see below) and path is the path name of the widget to be used. All of the commands require a path. The file option is needed for capture operations, and is mandatory for the Capture command. The title option is useful where a printout is the result of the command. The remaining options are supported by specific commands where it makes sense to do so.

-paginate

For commands that result in a printed page, the paginate option can be used to toggle the printing of a page header that contains a title, a date stamp and a page number. If paginate is false then no pagination will be done, and any value for title is ignored. By default, paginate is true.

-margins

The margins option allows specification of the page margins used when printing things. The margins are set, by default, to 1.0,1.0,1.0 and 0.5 (all inches) representing the left,top,right and bottom margins with respect to the printer's printable page surface. Note that many printers have margin settings specified in the printer driver dialog that can affect the printable area on a page. The margins option acts on whatever printable page area the device driver indicates is available.

The format of the margin specification is...

... -margins left,top,right,bottom ...

where the values are in inches.

-position

The position option allows specification of the location and size of the printed image produced by the PrintWindow command. Normally, the position and size default to the top of the page (possibly after any pagination output) with a width equal to the page width less the margins, and a height scaled to preserve the aspect of the widget. By specifying the position option you can define the location and size of the printed widget.

The format of the position specification is...

... -position left,top,right,bottom ...

where left,top,right and bottom are values in inches that describe the rectangle to be occupied by the printed widget. These coordinates are relative to an origin that is in the top left corner of the page region defined by the printable page size deflated by the margins and any pagination output.

Have care in using the position option, as it is easy to destroy the printed output to the extent that the printout is unrecognizable. The PrintWindow function uses the StretchDIBits Windows function, which works well for aspect preserving expansions and contractions of moderate scale factor, but can produce a mess if not controlled carefully.

-scale

The format of the scale specification is...

... -scale horizontal,vertical

where horizontal and vertical are floating point numbers that can be used to scale the output on the printed page. By default, both of these values are 1.0. The current version of the extension tries to preserve the aspect ratio of the canvas objects, so usually, only the horizontal scale value need be supplied. Because the resolution of the printer will be, in general, higher than that of the display on which the canvas is drawn, then the printed canvas contents will be physically smaller than they are on the display. By choosing an appropriate scale factor, users can achieve a printed output that matches the screen, or some other size.

-font

The font specification is used to supply a font for the header and footer that is printed on pages that use pagination. See the Print command below for a description of how to specify a font.

-clipboard

The clipboard option can be used with the Capture and MetaFile commands to place copies of widget windows on the clipboard. The format of the clipboard option is as follows:

... -clipboard boolean

where boolean indicates that the image or metafile is to be written to the clipboard if its value is "true", "yes" or "1". By default, images or metafiles are not written to the clipboard.

-header and -footer

The header and footer options can be used to format the page header and page footer that is printed when pagination is being used. The header and footer values are text strings that can include embedded format specifiers from the following list: You can also specify %% to get a single % sign, and %number, where number is a string of digits, to specify the number of blanks to be inserted. There are a few caveats. The maximum number of characters in a header or footer is 254. If you overflow this number the strings will be truncated. The simple string expander needs to see the % escape as the first character following a blank (ASCII 32) or tab or newline character. Here is an example of a header format specification:

    Print .text -title "My Example" -header "%t printed %d"

which results in the page header being something like:

    "My Example printed Tue Sep 2001 12:32:00 2002"

Note that text tokens that are not preceded by a % escape appear as they are. If paginate is true and there is no header or footer specified on the command line, the default formats are used.

PrintCanvas

This command will print the contents of a canvas widget on a Windows printer. If necessary, the canvas contents will be printed on multiple, paginated pages. The format of the command is

    PrintCanvas path ?-title? ?title?

where path is the path name of the widget. If the title option is specified, the title string will appear on the printed page of the output. The command will prompt the user for the Windows printer to be used.

This command does the job of printing the canvas, but does not perform any scaling of the output. Since current generation printers have generally much larger pixel resolutions than do display screens, printed canvases will look rather small on the printout when compared to the screen. If you use this function on a really high resolution printer, the output may be of little use for purposes other than debugging.

If this command is successful, the value returned is the path name of the canvas window that has been printed.

If the user cancels the printing, or if there is an error in the command line, an error message is returned.

Print

This command will print the contents of a text widget on a Windows printer. The printed output will not show any embedded windows of the text, just the actual character strings in the text. The output will be paginated as necessary.

The format of the command is...

    Print path ?-title? ?title? ?-font? ?font? ?-pagefont? ?pagefont?   ?-tabwidth? ?width?

where path is the path name of the widget, title is an optional title for the printed pages, and pagefont is the name of the font to be used. The font is a font that is used to print the page headers and footers.

-title

If title is specified, the pages of printed text will use this string as a title. If font is not specified, the command will print the output using the font retrieved from the text widget via the "cget -font" widget command.

-font and -pagefont

If font or pagefont is specified, the general format of the font specification string is as follows...

facename size ?bold? ?normal? ?light? ?italic? ?underline? ?strikeout?

where facename should be the name of a font that is installed on the computer being used and size is a number representing the desired size of the characters to be printed. The remaining keywords are optional, and can be used to change the appearance of the printed output. The default is font is "Terminal 12 normal", a font that is more or less certain to exist on Windows machines.

Note that the use of fonts is problematic on windows machines in that different printers have different resolutions, resulting in a font specification appearing somewhat different on each machine. What has been done in this extension is to scale the actual font size specification according to the ratio of the current printer resolution to the standard display resolution of 72 pixels per inch. This causes the printed output to resemble the contents of a typical 17 inch monitor running in 1024 by 768 mode. If you don't want this font size, you will have to fool with the font specification using the command line.

Previous to 1.17, Tkprint used whatever was specified either in the Tk text or the command line, and the result was so small as to be unreadable on high resolution printers. The new scheme is good for the lazy, but not necessarily for the pure.

-tabwidth

If tabwidth is specified, it is followed by a number indicating the number of space characters that a full tab should expand to. The value is used to specify the interval of tab positions across a page, so the actual tab expansion will bring the print head to the next tab position by padding the output line with blanks. The default value of the tabwidth is 8. Setting tabwidth to 0 will turn off tab expansion, and the tab character will be printed as the graphic symbol appropriate to the selected font.

Capture

This command will grab a displayed widget and map it to a 256 color Device Independent Bitmap (DIB) format file. It is important to ensure that the widget being captured is on the top of the display (that is, not overlapped by other windows), and is fully updated (that is, completely displayed) when capture occurs. Otherwise, you will capture whatever is in the window rectangle of the widget.

The format of the command is...

    Capture path -file file

where path is the path to the widget and file is the required name of the file to be used for the image. This command saves 256 color bitmaps regardless of the nature of the actual display. The reason for this is that while 24 bit displays are common and are universally well handled, 16 bit displays are also common, and the bitmaps generated are not universally well handled. I have never come across any software that does a bad job of indexed BMP files, and they are easy to convert to GIF format for all the UNIX fans out there.

While the Capture command actually does the work, see the "GrabWindow" command below for a solution to some implementation issues.

If this command is successful, the name of the file containing the captured window is returned.

PrintWindow

This command captures a widget and prints it on a printer page. In order to use this command, your printer driver needs to support the StretchDIBits GDI command. Unless you are using a printer driver that dates from before 1986 or so, or, like me, you use one you wrote yourself, you should not have any worry on this point.

The format of the command is...

    PrintWindow path ?-title? ?title?

where path is the path name of the widget and title is an optional title for the printed page. This command works the same way as the Capture command does, so you need to be sure that the widget to be printed is on top of other widgets and fully displayed on the screen.

The printed output will have the widget stretched to the page width of the printer, but the aspect ratio of the printed widget will be preserved, so it will look like the one on the screen.

While the PrintWindow command actually does the work, see the "PrintAWindow" command below for a solution to certain implementation issues.

PrinterCapabilities

This command will present a printer selection dialog asking the user to choose the printer that is of interest. The result of the command will be a message that displays the color capabilities of the printer, and optionally, the color parameters of a Tk window on the display screen.

This command may be useful where attempts to use the PrintWindow command fail because there is a mismatch between color capabilities of the printer driver for a printer and the color parameters of a window being printed. Not all printer drivers support the printing of images in all color formats. By default, the PrintWindow command will set the color depth of the captured screen image to the color depth reported by the printer driver. The user, may, by using the "-colordepth" option of the PrintWindow command specify an alternate color depth which the printer may support.

The format of the command is ...

    PrinterCapabilities ?path?

where path is an optional Tk window path to a window on the screen. If path is not specified, the result of this command is a text string that contains the color capabilities of the selected printer. If a path is supplied, then the color parameters of the screen image in the associated Tk window is also displayed.

Metafile

This command will create various types of Windows metafiles from canvas widgets. The distribution contains a document that describes the various available options and contains some examples of captured widgets in both metafile and bitmap format.

The format of the command is:

    MetaFile path ?-file? ?name? ?-clipboard? ?boolean? ?-format? ?format? ...

where the path is the Tk path name to the canvas widget to be used to create the metafile. If neither the file nor the clipboard options are specified, then the metafile will be generated and printed to a native Windows printer.

The file and clipboard options are mutually exclusive. If a file name is specified, then the target Windows metafile format is determined from the file extension. Extensions of .WMF result in a traditional format windows metafile, marginally useful for Windows 3.1 applications. The default format is .EMF, or the Windows Enhanced Metafile format. This format is good for Win 9x, NT and 2000 applications.

If the clipboard option is used, the metafile will be put onto the Windows clipboard in the requested format. Not all applications will support all metafile formats. Microsoft Office 9x and Lotus SmartSuite will accept the pasting and resizing of Enhanced format metafiles from the clipboard.

The format option can be "enhanced", "aldus" or "windows". The default format is "enhanced". There may be some applications that can use "aldus", which will generate Aldus Placeable Metafile format.

PrintMetaFile

This is a utility that will print Windows metafile formats to a native windows printer. The format of the command is:

    PrintMetafile name ...options...

where name is the name of the Windows metafile to be printed. You can use any of the page formatting options to add headers, footers or set margins. The format of the Windows metafile is determined from the file name extension. Traditional Windows metafiles have the extension .WMF, new style files have the extension .EMF

GrabWindow and PrintAWindow

These commands are implemented via the script file "windows.tcl" that comes with the package. There purpose is to pop a widget to the top of a display stack, allow some time for the Windows O/S to redraw the widget. There are many possible ways of ensuring that the widget to be captured or printed is topmost and fully updated, so do your own by changing the scripts if you don't like the way it works now.

These commands put the widget topmost by iconifying it, then deiconifying it. Then, after a delay of 1/2 a second, time enough for the window to be redrawn completely, the appropriate command is executed.

The command formats are...

    GrabWindow path ?file?

    PrintAWindow path ?title?

where path is the path name of the widget, file is the file name to use for capture, and title is a title for the printed page.

Email : customclients@videotron.ca