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.
This release also adds improved management of color space reduction for image capture and printing. Whereas previous releases relied on the Windows device drivers for color space reduction when printing or capturing of widgets, this release implements error diffusion based dithering against "standard' palettes, resulting in considerably improved color matching.
Clipboard support has also been added to the Capture command, so that widgets may be captured directly to the clipboard in Windows DIB format, optionally at reduced color space resolutions. Again, captured DIB format images can then be pasted directly into other applications.
This release also adds a check to the print command that the widget path name passed is in fact a text. If this command is used for a non text widget it will return an error message.
The code that handles the printing of text widgets has been modified to support UTF-8 character encoding. This enables the printing of characters used by various european languages that are usually outside the ASCII-96 character set.
A new option is added to the PrintCanvas command, providing the ability to scale the output on the printer page.
A new command, PrinterCapabilities, has been added to the package to allow users to determine whether a printer will likely print screen images.
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.
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.
The format of the margin specification is...
... -margins left,top,right,bottom ...
where the values are in inches.
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 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.
... -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.
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 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.
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.
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.
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.
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.
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.
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 ...
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.
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 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
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 : firstname.lastname@example.org