NAME Win32::Printer - Perl extension for Win32 printing SYNOPSIS use Win32::Printer; my $dc = new Win32::Printer( papersize => A4, dialog => NOSELECTION, description => 'Hello, Mars!', unit => 'mm' ); my $font = $dc->Font('Arial Bold', 24); $dc->Font($font); $dc->Color(0, 0, 255); $dc->Write("Hello, Mars!", 10, 10); $dc->Brush(128, 0, 0); $dc->Pen(4, 0, 0, 128); $dc->Ellipse(10, 25, 50, 50); $dc->Close(); ABSTRACT Win32 GDI graphical printing INSTALLATION 1. Make sure you have a C/C++ compiler and you're running Win32. 2. For VC++ 6.0 or VC++ .NET do the following (others not tested): > nmake > nmake test > nmake install 3. For bitmap support, copy *FreeImage.dll* somewhere in your system path. You may get this library form *http://sourceforge.net* or binary distribution of this module (*http://www.wasx.net*). FreeImage library is needed for the tests! 4. Enjoy it ;) DESCRIPTION All symbolic constants are exported by default!!! new new Win32::Printer ( [ parameter => value, ... ] ); The new class method creates printer object, starts new document (a print job), returns printer object and changes $dc->{flags} variable. $dc->{flags} contains modified printer dialog flags. new also sets $dc->{copies}, $dc->{collate}, $dc->{maxp} and $dc->{minp}, $dc->{xres}, $dc->{yres}, $dc->{xsize}, $dc->{ysize} variables. $dc->{xres}; # X resolution $dc->{yres}; # Y resolution $dc->{xsize}; # X size in chosen units $dc->{ysize}; # Y size in chosen units NOTE! Print job is automatically aborted if print job is not ended by "End" or "Close" methods or if an error occurs! The new class method sets the following optional printer object and document parameters: * printer If both printer and dialog attributes omitted- systems default printer is used. Value of attribute is also used for dialog initialisation. Set printer's "friendly" name e.g. "HP LaserJet 8500" or network printer's UNC e.g. "\\\\server\\printer". * dc If dc is not zero or null- returns only device context without starting the document and new page. * dialog If both printer and dialog attributes omitted- systems default printer is used. Printer dialog settings. You may use the combination of the following flags ($dc->{flags} contains modified printer dialog flags): ALLPAGES = 0x000000 The default flag that indicates that the All radio button is initially selected. This flag is used as a placeholder to indicate that the PAGENUMS and SELECTION flags are not specified. SELECTION = 0x000001 If this flag is set, the Selection radio button is selected. If neither PAGENUMS nor SELECTION is set, the All radio button is selected. PAGENUMS = 0x000002 If this flag is set, the Pages radio button is selected. If this flag is set when the new method returns, the $dc->{maxp} and $dc->{minp} variables indicate the starting and ending pages specified by the user. NOSELECTION = 0x000004 Disables the Selection radio button. NOPAGENUMS = 0x000008 Disables the Pages radio button and the associated edit controls. PRINTTOFILE = 0x000020 If this flag is set, the Print to File check box is selected. PRINTSETUP = 0x000040 Causes the system to display the Print Setup dialog box rather than the Print dialog box. NOWARNING = 0x000080 Prevents the warning message from being displayed when there is no default printer. USEDEVMODECOPIES = 0x040000 Same as USEDEVMODECOPIESANDCOLLATE USEDEVMODECOPIESANDCOLLATE = 0x040000 This flag indicates whether your application supports multiple copies and collation. Set this flag on input to indicate that your application does not support multiple copies and collation. In this case, the $dc->{copies} member always returns 1, and $dc->{collate} member always returns 0. If this flag is not set, the application is responsible for printing and collating multiple copies. In this case, the $dc->{copies} member indicates the number of copies the user wants to print, and the $dc->{collate} member indicates whether the user wants collation. If this flag is set and the printer driver does not support multiple copies, the Copies edit control is disabled. Similarly, if this flag is set and the printer driver does not support collation, the Collate checkbox is disabled. This feature may not work correctly with all printer drivers! DISABLEPRINTTOFILE = 0x080000 Disables the Print to File check box. HIDEPRINTTOFILE = 0x100000 Hides the Print to File check box. NONETWORKBUTTON = 0x200000 Hides and disables the Network button. * minp Minor page number in printer dialog (minimal possible value). * maxp Major page number in printer dialog (maximal possible value). * orientation * copies Initial number of document copies to print. See also USEDEVMODECOPIESANDCOLLATE. * collate If this flag is set, the Collate check box is checked. See also USEDEVMODECOPIESANDCOLLATE. Page orientation (portrait by default). PORTRAIT = 1 LANDSCAPE = 2 * papersize Defined paper sizes: LETTER = 1 LETTERSMALL = 2 TABLOID = 3 LEDGER = 4 LEGAL = 5 STATEMENT = 6 EXECUTIVE = 7 A3 = 8 A4 = 9 A4SMALL = 10 A5 = 11 B4 = 12 B5 = 13 FOLIO = 14 QUARTO = 15 IN_10X14 = 16 IN_11X17 = 17 NOTE = 18 ENV_9 = 19 ENV_10 = 20 ENV_11 = 21 ENV_12 = 22 ENV_14 = 23 CSHEET = 24 DSHEET = 25 ESHEET = 26 ENV_DL = 27 ENV_C5 = 28 ENV_C3 = 29 ENV_C4 = 30 ENV_C6 = 31 ENV_C65 = 32 ENV_B4 = 33 ENV_B5 = 34 ENV_B6 = 35 ENV_ITALY = 36 ENV_MONARCH = 37 ENV_PERSONAL = 38 FANFOLD_US = 39 FANFOLD_STD_GERMAN = 40 FANFOLD_LGL_GERMAN = 41 ISO_B4 = 42 JAPANESE_POSTCARD = 43 IN_9X11 = 44 IN_10X11 = 45 IN_15X11 = 46 ENV_INVITE = 47 RESERVED_48 = 48 RESERVED_49 = 49 LETTER_EXTRA = 50 LEGAL_EXTRA = 51 TABLOID_EXTRA = 52 A4_EXTRA = 53 LETTER_TRANSVERSE = 54 A4_TRANSVERSE = 55 LETTER_EXTRA_TRANSVERSE = 56 A_PLUS = 57 B_PLUS = 58 LETTER_PLUS = 59 A4_PLUS = 60 A5_TRANSVERSE = 61 B5_TRANSVERSE = 62 A3_EXTRA = 63 A5_EXTRA = 64 B5_EXTRA = 65 A2 = 66 A3_TRANSVERSE = 67 A3_EXTRA_TRANSVERSE = 68 * duplex Duplexing mode: SIMPLEX = 1 VERTICAL = 2 HORIZONTAL = 3 * description Document description. Default is "Printer". * source Specifies the paper source. BIN_ONLYONE = 1 BIN_LOWER = 2 BIN_MIDDLE = 3 BIN_MANUAL = 4 BIN_ENVELOPE = 5 BIN_ENVMANUAL = 6 BIN_AUTO = 7 BIN_TRACTOR = 8 BIN_SMALLFMT = 9 BIN_LARGEFMT = 10 BIN_LARGECAPACITY = 11 BIN_CASSETTE = 14 BIN_FORMSOURCE = 15 * color Switches between color and monochrome on color printers. Following are the possible values: MONOCHROME = 1 COLOR = 2 * unit Document units (inches by default). Specified unit is used for all coordinates and sizes, except for font sizes and pen widths. You may use strings: 'in' - inches 'mm' - millimeters 'cm' - centimeters 'pt' - points (in/72) Or unit ratio according to: ratio = in / unit Example: 2.5409836 cm = 1 in Abort $dc->Abort(); The Abort method stops the current print job and erases everything drawn since the last call to the "Start" method. See also "Start", "Next" and "End". Arc $dc->Arc($x, $y, $width, $height, $start_angle, $end_angle2); The Arc method draws an elliptical arc. $x, $y sets the upper-left corner coordinates of bounding rectangle. $width, $height sets the width and height of bounding rectangle. $start_angle, $end_angle2 sets the starting and ending angle of the arc according to the center of bounding rectangle. The current point is not updated. See also "ArcTo", "Ellipse", "Chord" and "Pie". ArcTo $dc->ArcTo($x, $y, $width, $height, $start_angle, $end_angle2); The ArcTo method draws an elliptical arc. $x, $y sets the upper-left corner coordinates of bounding rectangle. $width, $height sets the width and height of bounding rectangle. $start_angle, $end_angle2 sets the starting and ending angle of the arc according to the center of bounding rectangle. The current point is updated. See also "Move", "Arc", "Ellipse", "Chord" and "Pie". Bezier $dc->Bezier(@points); The Polybezier method draws cubic Bézier curves by using the endpoints and control points specified by the @points array. The first curve is drawn from the first point to the fourth point by using the second and third points as control points. Each subsequent curve in the sequence needs exactly three more points: the ending point of the previous curve is used as the starting point, the next two points in the sequence are control points, and the third is the ending point. The current point is not updated. See also "BezierTo". BezierTo $dc->Bezier(@points); The BezierTo method draws one or more Bézier curves. This method draws cubic Bézier curves by using the control points specified by the @points array. The first curve is drawn from the current position to the third point by using the first two points as control points. For each subsequent curve, the method needs exactly three more points, and uses the ending point of the previous curve as the starting point for the next. The current point is updated. See also "Bezier" and "Move". Brush $dc->Brush([$r, $g, $b, [$hatch]]); The Brush method creates a logical brush that has the specified style and optional hatch style. If no parameters specified, creates transparent brush. You may use the following brush hatch styles: HS_HORIZONTAL = 0 Horizontal hatch. HS_VERTICAL = 1 Vertical hatch. HS_FDIAGONAL = 2 A 45-degree downward, left-to-right hatch. HS_BDIAGONAL = 3 A 45-degree upward, left-to-right hatch. HS_CROSS = 4 Horizontal and vertical cross-hatch HS_DIAGCROSS = 5 45-degree crosshatch. See also "Pen". Caps $dc->Caps($index); The Caps method retrieves device-specific information about a specified device. $index specifies the item to return. This parameter can be one of the following values: DRIVERVERSION The device driver version. HORZSIZE Width, in millimeters, of the physical screen. VERTSIZE Height, in millimeters, of the physical screen. HORZRES Width, in pixels, of the screen. VERTRES Height, in raster lines, of the screen. LOGPIXELSX Number of pixels per logical inch along the screen width. LOGPIXELSY Number of pixels per logical inch along the screen height. BITSPIXEL Number of adjacent color bits for each pixel. PLANES Number of color planes. NUMBRUSHES Number of device-specific brushes. NUMPENS Number of device-specific pens. NUMFONTS Number of device-specific fonts. NUMCOLORS Number of entries in the device's color table, if the device has a color depth of no more than 8 bits per pixel. For devices with greater color depths, -1 is returned. ASPECTX Relative width of a device pixel used for line drawing. ASPECTY Relative height of a device pixel used for line drawing. ASPECTXY Diagonal width of the device pixel used for line drawing. CLIPCAPS Flag that indicates the clipping capabilities of the device. If the device can clip to a rectangle, it is 1. Otherwise, it is 0. SIZEPALETTE Number of entries in the system palette. This index is valid only if the device driver sets the RC_PALETTE bit in the RASTERCAPS index and is available only if the driver is compatible with 16-bit Windows. NUMRESERVED Number of reserved entries in the system palette. This index is valid only if the device driver sets the RC_PALETTE bit in the RASTERCAPS index and is available only if the driver is compatible with 16-bit Windows. COLORRES Actual color resolution of the device, in bits per pixel. This index is valid only if the device driver sets the RC_PALETTE bit in the RASTERCAPS index and is available only if the driver is compatible with 16-bit Windows. PHYSICALWIDTH For printing devices: the width of the physical page, in device units. For example, a printer set to print at 600 dpi on 8.5"x11" paper has a physical width value of 5100 device units. Note that the physical page is almost always greater than the printable area of the page, and never smaller. PHYSICALHEIGHT For printing devices: the height of the physical page, in device units. For example, a printer set to print at 600 dpi on 8.5"x11" paper has a physical height value of 6600 device units. Note that the physical page is almost always greater than the printable area of the page, and never smaller. PHYSICALOFFSETX For printing devices: the distance from the left edge of the physical page to the left edge of the printable area, in device units. For example, a printer set to print at 600 dpi on 8.5"x11" paper, that cannot print on the leftmost 0.25" of paper, has a horizontal physical offset of 150 device units. PHYSICALOFFSETY For printing devices: the distance from the top edge of the physical page to the top edge of the printable area, in device units. For example, a printer set to print at 600 dpi on 8.5"x11" paper, that cannot print on the topmost 0.5" of paper, has a vertical physical offset of 300 device units. SCALINGFACTORX Scaling factor for the x-axis of the printer. SCALINGFACTORY Scaling factor for the y-axis of the printer. RASTERCAPS Value that indicates the raster capabilities of the device, as shown in the following table: 0x0001 Capable of transferring bitmaps. 0x0002 Requires banding support. 0x0004 Capable of scaling. 0x0008 Capable of supporting bitmaps larger than 64K. 0x0010 Capable of supporting features of 16-bit Windows 2.0. 0x0080 Capable of supporting the SetDIBits and GetDIBits functions (Win API). 0x0100 Specifies a palette-based device. 0x0200 Capable of supporting the SetDIBitsToDevice function (Win API). 0x0800 Capable of performing the StretchBlt function (Win API). 0x1000 Capable of performing flood fills. 0x2000 Capable of performing the StretchDIBits function (Win API). CURVECAPS Value that indicates the curve capabilities of the device, as shown in the following table: 0 Device does not support curves. 1 Device can draw circles. 2 Device can draw pie wedges. 4 Device can draw chord arcs. 8 Device can draw ellipses. 16 Device can draw wide borders. 32 Device can draw styled borders. 64 Device can draw borders that are wide and styled. 128 Device can draw interiors. 256 Device can draw rounded rectangles. LINECAPS Value that indicates the line capabilities of the device, as shown in the following table: 0 Device does not support lines. 2 Device can draw a polyline. 4 Device can draw a marker. 8 Device can draw multiple markers. 16 Device can draw wide lines. 32 Device can draw styled lines. 64 Device can draw lines that are wide and styled. 128 Device can draw interiors. POLYGONALCAPS Value that indicates the polygon capabilities of the device, as shown in the following table: 0 Device does not support polygons. 1 Device can draw alternate-fill polygons. 2 Device can draw rectangles. 4 Device can draw winding-fill polygons. 8 Device can draw a single scanline. 16 Device can draw wide borders. 32 Device can draw styled borders. 64 Device can draw borders that are wide and styled. 128 Device can draw interiors. TEXTCAPS Value that indicates the text capabilities of the device, as shown in the following table: 0x00000001 Device is capable of character output precision. 0x00000002 Device is capable of stroke output precision. 0x00000004 Device is capable of stroke clip precision. 0x00000008 Device is capable of 90-degree character rotation. 0x00000010 Device is capable of any character rotation. 0x00000020 Device can scale independently in the x- and y-directions. 0x00000040 Device is capable of doubled character for scaling. 0x00000080 Device uses integer multiples only for character scaling. 0x00000100 Device uses any multiples for exact character scaling. 0x00000200 Device can draw double-weight characters. 0x00000400 Device can italicize. 0x00000800 Device can underline. 0x00001000 Device can draw strikeouts. 0x00002000 Device can draw raster fonts. 0x00004000 Device can draw vector fonts. 0x00010000 Device cannot scroll using a bit-block transfer. Note that this meaning may be the opposite of what you expect. See also "new". Chord $dc->Chord($x, $y, $width, $height, $start_angle, $end_angle2); The Chord method draws a chord (a region bounded by the intersection of an ellipse and a line segment, called a "secant"). The chord is outlined by using the current pen and filled by using the current brush. $x, $y sets the upper-left corner coordinates of bounding rectangle. $width, $height sets the width and height of bounding rectangle. $start_angle, $end_angle2 sets the starting and ending angle of the chord according to the center of bounding rectangle. See also "Ellipse", "Pie", "Arc" and "ArcTo". Close $dc->Close([$image_handle]); The Close method finishes current print job, closes all open handles and frees memory. If optional image handle is provided- closes only image! See also "new" and "Image". Color $dc->Color($b, $g, $b); The Color method sets the text color to the specified color. See also "Write" and "Font". Ellipse $dc->Ellipse($x, $y, $width, $height); The Ellipse method draws an ellipse. The center of the ellipse is the center of the specified bounding rectangle. The ellipse is outlined by using the current pen and is filled by using the current brush. $x, $y sets the upper-left corner coordinates of bounding rectangle. $width, $height sets the width and height of bounding rectangle. See also "Pie", "Chord", "Arc" and "ArcTo". End $dc->End(); The End method finishes a current print job. See also "Start", "Next", "Abort" and "Page". Fill $dc->Fill($mode); The Fill method sets the polygon fill mode for methods that fill polygons. ALTERNATE = 1 Selects alternate mode (fills the area between odd-numbered and even-numbered polygon sides on each scan line). WINDING = 2 Selects winding mode (fills any region with a nonzero winding value). See also "PDraw" and "Poly". Font $font_handle = $dc->Font([$face, [$size, [$angle, [$charset]]]]); or $dc->Font($font_handle); The Font method creates and selects a logical font that has specific characteristics and returns handle to it or selects given font by it's handle. Fontsize is set in pts. Defaults to: $face = 'Courier'; # fontface $size = 10; # fontsize $angle = 0; # text direction angle in degrees $charset = DEFAULT; # character set code $face may include any combination of the following attributes: bold italic underline strike. Defined character set constants: ANSI = 0 DEFAULT = 1 SYMBOL = 2 MAC = 77 SHIFTJIS = 128 HANGEUL = 129 JOHAB = 130 GB2312 = 134 CHINESEBIG5 = 136 GREEK = 161 TURKISH = 162 VIETNAMESE = 163 HEBREW = 177 ARABIC = 178 BALTIC = 186 RUSSIAN = 204 THAI = 222 EASTEUROPE = 238 OEM = 255 See also "Write", and "Color". Image $image_handle = $dc->Image($filename); or $image_handle = $dc->Image($filename, $x, $y, $width, $height); $dc->Image($image_handle, $x, $y, $width, $height); The Image method loads an image file into memory and returns a handle to it or draws it by it's filename or handle. $x, $y specifies coordinates of the image upper-left corner. $width, $height specifies the width and height of image on the paper. Natively it supports EMF and WMF format files. BMP, CUT, ICO, JPEG, JNG, KOALA, LBM, IFF, MNG, PBM, PBMRAW, PCD, PCX, PGM, PGMRAW, PNG, PPM, PPMRAW, PSD, RAS, TARGA, TIFF, WBMP bitmap formats are handled via FreeImage library. After usage, you should use "Close" to unload image from memory and destroy a handle. See also "Close". Line $dc->Line(@endpoints); The Line method draws a series of line segments by connecting the points in the specified array. The current point is not updated. See also "LineTo". LineTo $dc->LineTo(@endpoints); The LineTo method draws a series of line segments by connecting the points in the specified array. The current point is updated. See also "Line". Move $dc->Move(); The Move method updates the current position to the specified point. See also "ArcTo", "LineTo" and "BezierTo". Next $dc->Next([$description]); The Next method ends and starts new print job. Equivalent for: $dc->End(); $dc->Start([$description]); Default description - "Printer". See also "Start", "End", "Abort" and "Page". Page $dc->Page(); The Page method starts new page. See also "Start", "Next" and "End". PAbort $dc->PAbort(); The PAbort method closes and discards any paths. PBegin $dc->PBegin(); The PBegin method opens a path bracket. See also "PClip", "PDraw", "PEnd" and "PAbort". PClip $dc->PClip($mode); The PClip method selects the current path as a clipping region, combining the new region with any existing clipping region by using the specified mode. Where $mode is one of the following: CR_AND = 1 The new clipping region includes the intersection (overlapping areas) of the current clipping region and the current path. CR_OR = 2 The new clipping region is the current path. CR_XOR = 3 The new clipping region includes the areas of the current clipping region with those of the current path excluded. CR_DIFF = 4 The new clipping region includes the union (combined areas) of the current clipping region and the current path. CR_COPY = 5 The new clipping region includes the union of the current clipping region and the current path but without the overlapping areas. See also "PBegin", "PDraw", "PEnd" and "PAbort". PDraw $dc->PDraw(); The PDraw method closes any open figures in a path, strokes the outline of the path by using the current pen, and fills its interior by using the current brush and fill mode. See also "PBegin", "PClip", "PEnd", "PAbort" and "Fill". PEnd $dc->PEnd(); The PEnd method closes a path bracket and selects the path defined by the bracket. See also "PBegin", "PClip", "PDraw" and "PAbort". Pen $dc->Pen([$width, $r, $g, $b, [$style]]); The Pen method creates a logical pen that has the specified style, width, and color. The pen can subsequently be used to draw lines and curves. Pen width is set in pts regardless of unit attribute in "new" constructor or whatever is set by "Unit" method. Using dashed or dotted styles will set the pen width to 1 px! If no parameters specified, creates transparent pen. You may use the following pen styles: PS_DASH = 0x00000001 Pen is dashed. PS_DOT = 0x00000002 Pen is dotted. PS_DASHDOT = 0x00000003 Pen has alternating dashes and dots. PS_DASHDOTDOT = 0x00000004 Pen has alternating dashes and double dots. PS_NULL = 0x00000005 Pen is invisible. PS_INSIDEFRAME = 0x00000006 Pen is solid. When this pen is used in drawing method that takes a bounding rectangle, the dimensions of the figure are shrunk so that it fits entirely in the bounding rectangle, taking into account the width of the pen. PS_SOLID = 0x00010000 Pen is solid (default). PS_JOIN_ROUND = 0x00010000 Joins are round (default). PS_ENDCAP_ROUND = 0x00010000 End caps are round (default). PS_ENDCAP_SQUARE = 0x00010100 End caps are square. PS_ENDCAP_FLAT = 0x00010200 End caps are flat. PS_JOIN_BEVEL = 0x00011000 Joins are beveled. PS_JOIN_MITER = 0x00012000 Joins are mitered. See also "Brush". Pie $dc->Pie($x, $y, $width, $height, $start_angle, $end_angle2); The Pie method draws a pie-shaped wedge bounded by the intersection of an ellipse and two radials. The pie is outlined by using the current pen and filled by using the current brush. $x, $y sets the upper-left corner coordinates of bounding rectangle. $width, $height sets the width and height of bounding rectangle. $start_angle, $end_angle2 sets the starting and ending angle of the pie according to the center of bounding rectangle. See also "Ellipse", "Chord", "Arc" and "ArcTo". Poly $dc->Poly(@vertices); The Poly method draws a polygon consisting of two or more vertices connected by straight lines. The polygon is outlined by using the current pen and filled by using the current brush and polygon fill mode. See also "Rect" and "Fill". Rect $dc->Rect($x, $y, $width, $height, [$ellipse_width, $ellipse_height]); The Rect method draws a rectangle or rounded rectangle. The rectangle is outlined by using the current pen and filled by using the current brush. $x, $y sets the upper-left corner coordinates of rectangle. $width, $height sets the width and height of rectangle. Optional parameters $ellipse_width, $ellipse_height sets the width and height of ellipse used to draw rounded corners. See also "Poly". Space $dc->Space($eM11, $eM12, $eM21, $eM22, $eDx, $eDy); The Space method sets a two-dimensional linear transformation between world space and page space. This transformation can be used to scale, rotate, shear, or translate graphics output. Transformation on the next page is reset to default. Default page origin is upper-left corner, x from left to right and y from top to bottom. 0 ------- x | | | y For any coordinates (x, y) in world space, the transformed coordinates in page space (x', y') can be determined by the following algorithm: x' = x * eM11 + y * eM21 + eDx, y' = x * eM12 + y * eM22 + eDy, where the transformation matrix is represented by the following: | eM11 eM12 0 | | eM21 eM22 0 | | eDx eDy 1 | Start $dc->Start([$description]) The Start method starts a print job. Default description - "Printer". NOTE! Print job is automatically aborted if print job is not ended by "End" or "Close" methods or if an error occurs! See also "Next", "End", "Abort" and "Page". Unit $dc->Unit([$unit]); The Unit method sets or gets current unit ratio. Specified unit is used for all coordinates and sizes, except for font sizes and pen widths. You may use strings: 'in' - inches 'mm' - millimeters 'cm' - centimeters 'pt' - points (in / 72) Or unit ratio according to: ratio = in / unit Example: 2.5409836 cm = 1 in Write # String mode (SM): $dc->Write($text, $x, $y, [$format, [$just_width]]); # Draw mode (DM): $dc->Write($text, $x, $y, $width, $height, [$format, [$tab_stop]]); SM: The Write method string mode writes a character string at the specified location, using the currently selected font, text color and alignment. DM: The Write method draw mode draws formatted text in the specified rectangle. In array context method returns array containing ($width, $height, $length, $text). $height is returned in scalar context. $length receives the number of characters processed by Write, including white-space characters. See CALCRECT and MODIFYSTRING flags. Optional $tab_stop parameter specifies the number of average character widths per tab stop. Optional text format flags: NOUPDATECP = 0x00000000 (SM) The current position is not updated after each text output call. The reference point is passed to the text output method. TOP = 0x00000000 (SM & DM) SL: The reference point will be on the top edge of the bounding rectangle. ML: Top justifies text. This value must be combined with SINGLELINE. LEFT = 0x00000000 (SM & DM) SL: The reference point will be on the left edge of the bounding rectangle. ML: Aligns text to the left. UPDATECP = 0x00000001 (SM) The current position is updated after each text output call. The current position is used as the reference point. RIGHT = 0x00000002 (SM & DM) SL: The reference point will be on the right edge of the bounding rectangle. ML: Aligns text to the right. VCENTER = 0x00000004 (DM) Centers text vertically (single line only). BOTTOM = 0x00000008 (SM & DM) SL: The reference point will be on the bottom edge of the bounding rectangle. ML: Justifies the text to the bottom of the rectangle. This value must be combined with SINGLELINE. WORDBREAK = 0x00000010 (DM) Breaks words. Lines are automatically broken between words if a word extends past the edge of the specified rectangle. A carriage return-linefeed sequence also breaks the line. BASELINE = 0x00000018 (SM) The reference point will be on the base line of the text. SINGLELINE = 0x00000020 (DM) Displays text on a single line only. Carriage returns and linefeeds do not break the line. EXPANDTABS = 0x00000040 (DM) Expands tab characters. Number of characters per tab is eight. NOCLIP = 0x00000100 (DM) Draws without clipping. Write is somewhat faster when NOCLIP is used. EXTERNALLEADING = 0x00000200 (DM) Includes the font external leading in line height. Normally, external leading is not included in the height of a line of text. CALCRECT = 0x00000400 (DM) Determines the $width and $height of the rectangle. If there are multiple lines of text, Write uses the width of the given rectangle and extends the base of the rectangle to bound the last line of text. If there is only one line of text, Write modifies the width of the rectangle so that it bounds the last character in the line. In either case, Write returns the height of the formatted text, but does not draw the text. NOPREFIX = 0x00000800 (DM) Turns off processing of prefix characters. Normally, Write interprets the ampersand (&) mnemonic-prefix character as a directive to underscore the character that follows, and the double ampersand (&&) mnemonic-prefix characters as a directive to print a single ampersand. By specifying NOPREFIX, this processing is turned off. INTERNAL = 0x00001000 (DM) Uses the system font to calculate text metrics. EDITCONTROL = 0x00002000 (DM) Duplicates the text-displaying characteristics of a multiline edit control. Specifically, the average character width is calculated in the same manner as for an edit control, and the method does not display a partially visible last line. PATH_ELLIPSIS = 0x00004000 (DM) END_ELLIPSIS = 0x00008000 (DM) Replaces part of the given string with ellipses, if necessary, so that the result fits in the specified rectangle. The $text element of returning array is not modified unless the MODIFYSTRING flag is specified. You can specify END_ELLIPSIS to replace characters at the end of the string, or PATH_ELLIPSIS to replace characters in the middle of the string. If the string contains backslash (\) characters, PATH_ELLIPSIS preserves as much as possible of the text after the last backslash. MODIFYSTRING = 0x00010000 (DM) Modifies the $text element of returning array to match the displayed text. This flag has no effect unless the END_ELLIPSIS or PATH_ELLIPSIS flag is specified. RTLREADING = 0x00020000 (SM & DM) Layout in right to left reading order for bi-directional text when the selected font is a Hebrew or Arabic font. The default reading order for all text is left to right. WORD_ELLIPSIS = 0x00040000 (DM) Truncates text that does not fit in the rectangle and adds ellipses. CENTER = 0x00080000 (SM & DM) SL: The reference point will be aligned horizontally with the center of the bounding rectangle. ML: Centers text horizontally in the rectangle. JUSTIFY = 0x80000000 (SM) Extends space characters to match given justification width ($just_width). Note: Allways use $just_width parameter with JUSTIFY flag! See also "Font" and "Color". SEE ALSO Win32::Printer::Enum, Win32 Platform SDK GDI documentation. AUTHOR Edgars Binans, *admin@wasx.net*. *http://www.wasx.net* COPYRIGHT AND LICENSE This library uses FreeImage 2.5.4, a free, open source image library supporting all common bitmap formats. Get your free copy from *http://sourceforge.net*. Copyright (C) 2003 Edgars Binans *admin@wasx.net*. THIS LIBRARY IS FREE FOR NON-COMMERCIAL USE!!!