Win32Forth

gdiDC -- Base device context class

Version 1.0

This GDI class library was written and placed in the Public Domain in 2005 by Dirk Busch

Glossary

:class gdiDC <super gdiObject

Base device context class

:M SelectObject: ( hGdiObject -- hOldObject )

The SelectObject method selects an object into the device context. The new object replaces the previous object of the same type.

If the selected object is not a region and the method succeeds, the return value is a handle to the object being replaced. If the selected object is a region and the method succeeds, the return value is one of the following values:

If an error occurs and the selected object is not a region, the return value is NULL. Otherwise, it is GDI_ERROR.

Note:  hGdiObject  can be a valid GDI object handle or the address of a GdiObject class !

:M GetCurrentObject: ( ObjectType -- hObject )

The GetCurrentObject method retrieves a handle to an object of the specified type that has been selected into the specified device context.

 ObjectType  Specifies the object type to be queried. This parameter can be one of the following values.

:M GetStockObject:      ( nObject -- hObject )

The GetStockObject method retrieves a handle to one of the stock pens, brushes, fonts, or palettes.  nObject  Specifies the type of stock object. This parameter can be one of the following values:

:M SelectStockObject: ( nObject -- hOldObject )

The SelectStockObject method selects one of the stock pens, brushes, fonts, or palettes into the the device context.

 nObject  Specifies the type of stock object. This parameter can be one of the following values. (see GetStockObject:)

:M SetPenColor: ( colorref -- previous-colorref )

SetPenColor method sets the current device context pen color to the specified color value. If the device cannot represent the specified color value, the color is set to the nearest physical color. If the method succeeds, the return value specifies the previous DC pen color as a COLORREF value. If the method fails, the return value is CLR_INVALID.

Only for Windows 2000 and later

:M GetPenColor: ( -- colorref )

The GetPenColor method retrieves the current pen color for the specified device context.

Only for Windows 2000 and later

:M SetBrushColor: ( colorref -- previous-colorref )

SetBrushColor method sets the current device context brush color to the specified color value. If the device cannot represent the specified color value, the color is set to the nearest physical color. If the method succeeds, the return value specifies the previous DC brush color as a COLORREF value. If the method fails, the return value is CLR_INVALID.

Only for Windows 2000 and later

:M GetBrushColor: ( -- colorref )

The GetBrushColor method retrieves the current brush color for the specified device context.

Only for Windows 2000 and later

:M Save:        ( -- )

The Save method saves the current state of the device context by copying data describing selected objects and graphic modes (such as the bitmap, brush, palette, font, pen, region, drawing mode, and mapping mode) to a context stack.

:M Restore:     ( -- )

The Restore method restores the device context to the specified state. The DC is restored by popping state information off a stack created by earlier calls to the Save method.

:M Cancel:      ( -- )

The Cancel method cancels any pending operation on the specified device context.
The Cancel method is used by multithreaded applications to cancel lengthy drawing operations. If thread A initiates a lengthy drawing operation, thread B may cancel that operation by calling this method.

:M GetDeviceCaps: ( Index -- n )

The GetDeviceCaps method retrieves device-specific information for the specified device.

 Index  Specifies the item to return. This parameter can be one of the following values:

 DRIVERVERSION  The device driver version.

 TECHNOLOGY  Device technology. It can be any one of the following values.

If the DC is the DC of an enhanced metafile, the device technology is that of the referenced device as specified to the CreateEnhMetaFile method. To determine whether it is an enhanced metafile DC, use the GetObjectType method.

 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. In a system with multiple display monitors, this value is the same for all monitors.

 LOGPIXELSY  Number of pixels per logical inch along the screen height. In a system with multiple display monitors, this value is the same for all monitors.

 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.

 PDEVICESIZE  Reserved.

 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-inch 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-by-11-inch 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-by-11-inch paper, that cannot print on the leftmost 0.25-inch 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-by-11-inch paper, that cannot print on the topmost 0.5-inch of paper, has a vertical physical offset of 300 device units.

 VREFRESH  Windows NT/2000: For display devices: the current vertical refresh rate of the device, in cycles per second (Hz). A vertical refresh rate value of 0 or 1 represents the display hardware's default refresh rate. This default rate is typically set by switches on a display card or computer motherboard, or by a configuration program that does not use Win32 display methods such as ChangeDisplaySettings.

 SCALINGFACTORX  Scaling factor for the x-axis of the printer.

 SCALINGFACTORY  Scaling factor for the y-axis of the printer.

 BLTALIGNMENT  Windows NT/2000: Preferred horizontal drawing alignment, expressed as a multiple of pixels. For best drawing performance, windows should be horizontally aligned to a multiple of this value. A value of zero indicates that the device is accelerated, and any alignment may be used.

 SHADEBLENDCAPS  Windows 98, Windows 2000: Value that indicates the shading and blending capabilities of the device.

 SB_CONST_ALPHA  Handles the SourceConstantAlpha member of the BLENDFUNCTION structure, which is referenced by the blendFunction parameter of the AlphaBlend method.

 RASTERCAPS  Value that indicates the raster capabilities of the device, as shown in the following table.

 CURVECAPS  Value that indicates the curve capabilities of the device, as shown in the following table:

 LINECAPS  Value that indicates the line capabilities of the device, as shown in the following table:

 POLYGONALCAPS  Value that indicates the polygon capabilities of the device, as shown in the following table.

 TEXTCAPS  Value that indicates the text capabilities of the device, as shown in the following table.

 COLORMGMTCAPS  Windows 2000: Value that indicates the color management capabilities of the device.

:M SetBackgroundMode: ( fMode -- fPreviousMode )

The SetBackgroundMode method sets the background mix mode of the specified device context. The background mix mode is used with text, hatched brushes, and pen styles that are not solid lines. Possible values for  fMode  are:

:M GetBackgroundMode: ( -- fMode )

The GetBackgroundMode method returns the current background mix mode for a specified device context. The background mix mode of a device context affects text, hatched brushes, and pen styles that are not solid lines.

:M SetBackgroundColor: ( colorref -- PreviousColorref )

The SetBackgroundColor method sets the current background color to the specified color value, or to the nearest physical color if the device cannot represent the specified color value.

Note:  colorref  can be a 'simple' colorref or the address of a pPen Object class !

:M GetBackgroundColor: ( -- colorref )

The GetBackgroundColor method returns the current background color for the specified device context.

:M SetROP:       ( nDrawMode -- nPreviousDrawMode )

The SetROP method sets the current foreground mix mode. GDI uses the foreground mix mode to combine pens and interiors of filled objects with the colors already on the screen. The foreground mix mode defines how colors from the brush or pen and the colors in the existing image are to be combined.

 nDrawMode  Specifies the mix mode. This parameter can be one of the following values. Mix mode Description

:M GetROP:       ( -- nDrawMode )

The GetROP method retrieves the foreground mix mode of the specified device context. The mix mode specifies how the pen or interior color and the color already on the screen are combined to yield a new color.

:M SetArcDirection: ( Direction -- OldDirection )

SetArcDirection sets the drawing direction to be used for arc and rectangle methods. Possible value for  Direction  are:

Only for Windows 98 and better.

:M GetArcDirection: ( -- Direction )

The GetArcDirection method retrieves the current arc direction for the specified device context. Arc and rectangle methods use the arc direction.

Only for Windows 98 and better.

Coordinate Space and Transformation

:M DPtoLP:      ( lpPoints nCount -- )

The DPtoLP method converts device coordinates into logical coordinates. The conversion depends on the mapping mode of the device context, the settings of the origins and extents for the window and viewport, and the world transformation.

 lpPoints  [in/out] Pointer to an array of POINT structures. The x- and y-coordinates contained in each POINT structure will be transformed.

 nCount  [in] Specifies the number of points in the array.

The DPtoLP method fails if the device coordinates exceed 27 bits, or if the converted logical coordinates exceed 32 bits. In the case of such an overflow, the results for all the points are undefined.

:M LPtoDP:      ( lpPoints nCount -- )

The LPtoDP method converts logical coordinates into device coordinates. The conversion depends on the mapping mode of the device context, the settings of the origins and extents for the window and viewport, and the world transformation.

 lpPoints  [in/out] Pointer to an array of POINT structures. The x- and y-coordinates contained in each POINT structure will be transformed.

 nCount  [in] Specifies the number of points in the array.

This method fails if the logical coordinates exceed 32 bits, or if the converted device coordinates exceed 27 bits. In the case of such an overflow, the results for all the points are undefined.

:M SetGraphicsMode: ( Mode -- PreviousMode )

The SetGraphicsMode method sets the graphics mode for the specified device context. Possible Values for Mode:

 GM_COMPATIBLE  Sets the graphics mode that is compatible with 16-bit Windows. This is the default mode. If this value is specified, the application can only modify the world-to-device transform by calling methods that set window and viewport extents and origins, but not by using SetWorldTransform or ModifyWorldTransform; calls to those methods will fail. Examples of methods that set window and viewport extents and origins are SetViewportExtEx and SetWindowExt.

 GM_ADVANCED  Windows NT/ 2000: Sets the advanced graphics mode that allows world transformations. This value must be specified if the application will set or modify the world transformation for the specified device context. In this mode all graphics, including text output, fully conform to the world-to-device transformation specified in the device context. Windows 95/98: The GM_ADVANCED value is not supported. When playing enhanced metafiles, Windows 95/98 attempts to make enhanced metafiles on Windows 95/98 look the same as they do on Windows NT/Windows 2000. To accomplish this, Windows 95/98 may simulate GM_ADVANCED mode when playing specific enhanced metafile records.

NOTE: Currently this class libary doesn't support wold transformation for the DC ! That means: CombineTransform(), GetWorldTransform(), ModifyWorldTransform() and SetWorldTransform() are not supported at the moment.

:M GetGraphicsMode: ( -- mode )

The GetGraphicsMode method retrieves the current graphics mode for the specified device context.

:M SetMapMode:  ( MapMode -- PerviousMapMode )

The SetMapMode method sets the mapping mode of the specified device context. The mapping mode defines the unit of measure used to transform page-space units into device-space units, and also defines the orientation of the device's x and y axes. Possible Values for MapMode are:

 MM_ANISOTROPIC  Logical units are mapped to arbitrary units with arbitrarily scaled axes. Use the SetWindowExt and SetViewportExt methods to specify the units, orientation, and scaling.

 MM_HIENGLISH  Each logical unit is mapped to 0.001 inch. Positive x is to the right; positive y is up.

 MM_HIMETRIC  Each logical unit is mapped to 0.01 millimeter. Positive x is to the right; positive y is up.

 MM_ISOTROPIC  Logical units are mapped to arbitrary units with equally scaled axes; that is, one unit along the x-axis is equal to one unit along the y-axis. Use the SetWindowExt and SetViewportExt methods to specify the units and the orientation of the axes. Graphics device interface (GDI) makes adjustments as necessary to ensure the x and y units remain the same size (When the window extent is set, the viewport will be adjusted to keep the units isotropic).

 MM_LOENGLISH  Each logical unit is mapped to 0.01 inch. Positive x is to the right; positive y is up.

 MM_LOMETRIC  Each logical unit is mapped to 0.1 millimeter. Positive x is to the right; positive y is up.

 MM_TEXT  Each logical unit is mapped to one device pixel. Positive x is to the right; positive y is down.

 MM_TWIPS  Each logical unit is mapped to one twentieth of a printer's point (1/1440 inch, also called a twip). Positive x is to the right; positive y is up.

:M GetMapMode:  ( -- MapMode )

The GetMapMode method retrieves the current mapping mode.

:M SetWindowOrg:  ( x y -- x1 y1 )

The SetWindowOrg method specifies which window point maps to the viewport origin (0,0).

This helps define the mapping from the logical coordinate space (also known as a window) to the device coordinate space (the viewport). SetWindowOrg specifies which logical point maps to the device point (0,0). It has the effect of shifting the axes so that the logical point (0,0) no longer refers to the upper-left corner.

This is related to the SetViewportOrg method. Generally, you will use one method or the other, but not both. Regardless of your use of SetWindowOrg and SetViewportOrg, the device point (0,0) is always the upper-left corner.

:M GetWindowOrg:  ( -- x y )

The GetWindowOrg method retrieves the x-coordinates and y-coordinates of the window origin for the specified device context.

:M SetViewportOrg: ( x y - x1 y1 )

The SetViewportOrg method specifies which device point maps to the window origin (0,0).

This method (along with SetViewportExt and SetWindowExt) helps define the mapping from the logical coordinate space (also known as a window) to the device coordinate space (the viewport). SetViewportOrg specifies which device point maps to the logical point (0,0). It has the effect of shifting the axes so that the logical point (0,0) no longer refers to the upper-left corner.

This is related to the SetViewportOrg method. Generally, you will use one method or the other, but not both. Regardless of your use of SetWindowOrg and SetViewportOrg, the device point (0,0) is always the upper-left corner.

:M GetViewportOrg: ( -- x y )

The GetViewportOrg method retrieves the x-coordinates and y-coordinates of the viewport origin for the specified device context.

:M OffsetViewportOrg: ( xOffest yOffset - xOffset1 yOffset1 )

The OffsetViewportOrg method modifies the viewport origin for a device context using the specified horizontal and vertical offsets. The new origin is the sum of the current origin and the horizontal and vertical offsets.

 xOffset  Specifies the horizontal offset, in device units.

 YOffset  Specifies the vertical offset, in device units.

:M OffsetWindowOrg: ( xOffest yOffset - xOffset1 yOffset1 )

The OffsetWindowOrg method modifies the window origin for a device context using the specified horizontal and vertical offsets.

 XOffset  Specifies the horizontal offset, in logical units.

 YOffset  Specifies the vertical offset, in logical units.

:M ScaleViewportExt: ( Xnum Xdenom Ynum Ydenom -- x y )

The ScaleViewportExt method modifies the viewport for a device context using the ratios formed by the specified multiplicands and divisors. It returns the the previous viewport extents, in device units.

The viewport extents are modified as follows:       xNewVE = (xOldVE * Xnum) / Xdenom       yNewVE = (yOldVE * Ynum) / Ydenom

:M ScaleWindowExtEx: ( Xnum Xdenom Ynum Ydenom -- x y )

The ScaleWindowExt method modifies the window for a device context using the ratios formed by the specified multiplicands and divisors. It returns the the previous window extents, in logical units.

The window extents are modified as follows:       xNewWE = (xOldWE * Xnum) / Xdenom       yNewWE = (yOldWE * Ynum) / Ydenom

:M SetViewportExt: ( XExtent yExtent -- XExtent1 yExtent1 )

The SetViewportExt method sets the horizontal and vertical extents of the viewport for a device context by using the specified values.

:M GetViewportExt: ( -- x y )

The GetViewportExt method retrieves the x-extent and y-extent of the current viewport for the specified device context.

:M SetWindowExt: ( XExtent YExtent -- XExtent1 YExtent1 )

The SetWindowExt method sets the horizontal and vertical extents of the window for a device context by using the specified values.

 XExtent  Specifies the window's horizontal extent in logical units.

 YExtent  Specifies the window's vertical extent in logical units.

Drawing

:M InvertRect:  ( left top right bottom  -- )

The InvertRect method inverts a rectangle in a window by performing a logical NOT operation on the color values for each pixel in the rectangle's interior.

 Filled Shapes Filled shapes are geometric forms that are outlined by using the current pen and filled by using the current brush.

:M Chord:       ( nLeftRect nTopRect nRightRect nBottomRect nXRadial1 nXRadial1 nYRadial1 nXRadial2 nYRadial2 -- )

The Chord method draws a chord (a region bounded by the intersection of an ellipse and a line segment, called a secant).

 nLeftRect  x-coord of upper-left corner of rectangle

 nTopRect  y-coord of upper-left corner of rectangle

 nRightRect  x-coord of lower-right corner of rectangle

 nBottomRect  y-coord of lower-right corner of rectangle

 nXRadial1  x-coord of first radial's endpoint

 nYRadial1  y-coord of first radial's endpoint

 nXRadial2  x-coord of second radial's endpoint

 nYRadial2  y-coord of second radial's endpoint

:M Ellipse:     ( nLeftRect nTopRect nRightRect nBottomRect -- )

The Ellipse method draws an ellipse. The center of the ellipse is the center of the specified bounding rectangle.

 nLeftRect  x-coord of upper-left corner of rectangle

 nTopRect  y-coord of upper-left corner of rectangle

 nRightRect  x-coord of lower-right corner of rectangle

 nBottomRect  y-coord of lower-right corner of rectangle

:M Pie:         ( nLeftRect nTopRect nRightRect nBottomRect nXRadial1 nYRadial1 nXRadial2 nYRadial2 -- )

The Pie method draws a pie-shaped wedge bounded by the intersection of an ellipse and two radials.

 nLeftRect  x-coord of upper-left corner of rectangle

 nTopRect  y-coord of upper-left corner of rectangle

 nRightRect  x-coord of lower-right corner of rectangle

 nBottomRect  y-coord of lower-right corner of rectangle

 nXRadial1  x-coord of first radial's endpoint

 nYRadial1  y-coord of first radial's endpoint

 nXRadial2  x-coord of second radial's endpoint

 nYRadial2  y-coord of second radial's endpoint

:M Rectangle:   ( nLeftRect nTopRect nRightRect nBottomRect -- )

The Rectangle method draws a rectangle.

 nLeftRect  x-coord of upper-left corner of rectangle

 nTopRect  y-coord of upper-left corner of rectangle

 nRightRect  x-coord of lower-right corner of rectangle

 nBottomRect  y-coord of lower-right corner of rectangle

:M RoundRect:   ( nLeftRect nTopRect nRightRect nBottomRect nWidth nHeight -- )

The RoundRect method draws a rectangle with rounded corners.

 nLeftRect  x-coord of upper-left corner of rectangle

 nTopRect  y-coord of upper-left corner of rectangle

 nRightRect  x-coord of lower-right corner of rectangle

 nBottomRect  y-coord of lower-right corner of rectangle

 nWidth  width of ellipse

 nHeight  height of ellipse

:M SetPolyFillMode: ( iPolyFillMode -- )

The SetPolyFillMode method sets the polygon fill mode for methods that fill polygons.

 iPolyFillMode  Specifies the new fill mode. This parameter can be one of the following values.

:M GetPolyFillMode: ( -- iPolyFillMode )

The GetPolyFillMode method retrieves the current polygon fill mode.

If the method succeeds, the return value specifies the polygon fill mode, which can be one of the following values.

If an error occurs, the return value is zero.

:M Polygon:     ( lpPoints nCount -- )

The Polygon 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.

 lpPoints  polygon vertices

 nCount  count of polygon vertices

:M PolyPolygon: ( lpPoints lpPolyCounts nCount -- )

The PolyPolygon method draws a series of closed polygons. Each polygon is outlined by using the current pen and filled by using the current brush and polygon fill mode. The polygons drawn by this method can overlap.

 lpPoints  array of vertices

 lpPolyCounts  array of count of vertices

 nCount  count of polygons

 The following methods are using an extra hBrush for filling

:M FillRect:    ( left top right bottom hBrush -- )

The FillRect method fills a rectangle by using the specified brush. This method includes the left and top borders, but excludes the right and bottom borders of the rectangle.

Note:  hBrush  can be a valid brush handle or the address of a GdiBrush class !

:M FrameRect:   ( left top right bottom hBrush -- )

The FrameRect method draws a border around the specified rectangle by using the specified brush. The width and height of the border are always one logical unit.

Note:  hBrush  can be a valid brush handle or the address of a GdiBrush class !

 Text output

:M SetTextAlign: ( fMode -- fPreviousMode )

The SetTextAlign method sets the text-alignment flags for the device context.

 fMode  Specifies the text alignment by using a mask of the values in the following list. Only one flag can be chosen from those that affect horizontal and vertical alignment. In addition, only one of the two flags that alter the current position can be chosen.

When the current font has a vertical default base line, as with Kanji, the following values must be used instead of TA_BASELINE and TA_CENTER.

The default values are TA_LEFT, TA_TOP, and TA_NOUPDATECP.

If the method fails, the return value is GDI_ERROR.

:M GetTextAlign: ( -- fMode )

The GetTextAlign method retrieves the text-alignment setting for the specified device context. If the method fails, the return value is GDI_ERROR.

:M SetTextColor: ( colorref -- PreviousColorref )

The SetTextColor method sets the text color for the specified device context to the specified color.

Note:  colorref  can be a 'simple' colorref or the address of a pPen Object class !

:M GetTextColor: ( -- colorref )

The GetTextColor method retrieves the current text color for the specified device context.

:M SetTextCharacterExtra: ( CharExtra -- OldCharExtra )

The SetTextCharacterExtra method sets the intercharacter spacing. Intercharacter spacing is added to each character, including break characters, when the system writes a line of text.

 CharExtra  Specifies the amount of extra space, in logical units, to be added to each character. If the current mapping mode is not MM_TEXT, the nCharExtra parameter is transformed and rounded to the nearest pixel.

:M GetTextCharacterExtra: ( -- CharExtra )

The GetTextCharacterExtra method retrieves the current intercharacter spacing for the specified device context.

:M GetTextExtent: ( addr len -- width height )

The GetTextExtent method computes the width and height of the specified string of text.

:M GetTextMetrics: ( -- addr len )

The GetTextMetrics method fills the specified buffer with the metrics for the currently selected font. Returns the address and length of the textmetric struct.

:M TextOut:     ( x y addr len -- )

The TextOut method writes a character string at the specified location, using the currently selected font, background color, and text color.

:M DrawText:    ( addr len rect format -- )

The DrawText method draws formatted text in the specified rectangle. It formats the text according to the specified method (expanding tabs, justifying characters, breaking lines, and so forth).

Possible values for  Format  are:

 DT_BOTTOM  Justifies the text to the bottom of the rectangle. This value is used only with the DT_SINGLELINE value.

 DT_CALCRECT  Determines the width and height of the rectangle. If there are multiple lines of text, DrawText uses the width of the rectangle pointed to by the lpRect parameter and extends the base of the rectangle to bound the last line of text. If there is only one line of text, DrawText modifies the right side of the rectangle so that it bounds the last character in the line. In either case, DrawText returns the height of the formatted text but does not draw the text.

 DT_CENTER  Centers text horizontally in the rectangle.

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

 DT_END_ELLIPSIS  For displayed text, if the end of a string does not fit in the rectangle, it is truncated and ellipses are added. If a word that is not at the end of the string goes beyond the limits of the rectangle, it is truncated without ellipses. The string is not modified unless the DT_MODIFYSTRING flag is specified. Compare with DT_PATH_ELLIPSIS and DT_WORD_ELLIPSIS.

 DT_EXPANDTABS  Expands tab characters. The default number of characters per tab is eight. The DT_WORD_ELLIPSIS, DT_PATH_ELLIPSIS, and DT_END_ELLIPSIS values cannot be used with the DT_EXPANDTABS value.

 DT_EXTERNALLEADING  Includes the font external leading in line height. Normally, external leading is not included in the height of a line of text.

 DT_HIDEPREFIX  Windows 2000: Ignores the ampersand (&) prefix character in the text. The letter that follows will not be underlined, but other mnemonic-prefix characters are still processed. For example:
input string:    "A&bc&&d"
normal:          "Abc&d"   
DT_HIDEPREFIX:   "Abc&d"

Compare with DT_NOPREFIX and DT_PREFIXONLY.

 DT_INTERNAL  Uses the system font to calculate text metrics.  DT_LEFT  Aligns text to the left.

 DT_MODIFYSTRING  Modifies the specified string to match the displayed text. This value has no effect unless DT_END_ELLIPSIS or DT_PATH_ELLIPSIS is specified.

 DT_NOCLIP  Draws without clipping. DrawText is somewhat faster when DT_NOCLIP is used.

 DT_NOFULLWIDTHCHARBREAK  Windows 98, Windows 2000: Prevents a line break at a DBCS (double-wide character string), so that the line breaking rule is equivalent to SBCS strings. For example, this can be used in Korean windows, for more readability of icon labels. This value has no effect unless DT_WORDBREAK is specified.

 DT_NOPREFIX  Turns off processing of prefix characters. Normally, DrawText interprets the mnemonic-prefix character & as a directive to underscore the character that follows, and the mnemonic-prefix characters && as a directive to print a single &. By specifying DT_NOPREFIX, this processing is turned off. For example,
input string:   "A&bc&&d"  
normal:         "Abc&d"    
DT_NOPREFIX:    "A&bc&&d"

Compare with DT_HIDEPREFIX and DT_PREFIXONLY.

 DT_PATH_ELLIPSIS  For displayed text, replaces characters in the middle of the string with ellipses so that the result fits in the specified rectangle. If the string contains backslash (\) characters, DT_PATH_ELLIPSIS preserves as much as possible of the text after the last backslash. The string is not modified unless the DT_MODIFYSTRING flag is specified. Compare with DT_END_ELLIPSIS and DT_WORD_ELLIPSIS.

 DT_PREFIXONLY    Windows 2000: Draws only an underline at the position of the character following the ampersand (&) prefix character. Does not draw any other characters in the string. For example,
input string:    "A&bc&&d"
normal:          "Abc&d"   
DT_PREFIXONLY:   " _   "

Compare with DT_HIDEPREFIX and DT_NOPREFIX.

 DT_RIGHT  Aligns text to the right.

 DT_RTLREADING  Layout in right-to-left reading order for bi-directional text when the font selected into the hdc is a Hebrew or Arabic font. The default reading order for all text is left-to-right.

 DT_SINGLELINE  Displays text on a single line only. Carriage returns and line feeds do not break the line.

 DT_TABSTOP  Sets tab stops. Bits 15–8 (high-order byte of the low-order word) of the uFormat parameter specify the number of characters for each tab. The default number of characters per tab is eight.The DT_CALCRECT, DT_EXTERNALLEADING, DT_INTERNAL, DT_NOCLIP, and DT_NOPREFIX values cannot be used with the DT_TABSTOP value.

 DT_TOP  Justifies the text to the top of the rectangle.

 DT_VCENTER  Centers text vertically. This value is used only with the DT_SINGLELINE value.

 DT_WORDBREAK  Breaks words. Lines are automatically broken between words if a word would extend past the edge of the rectangle specified by the lpRect parameter. A carriage return-line feed sequence also breaks the line.

 DT_WORD_ELLIPSIS  Truncates any word that does not fit in the rectangle and adds ellipses. Compare with DT_END_ELLIPSIS and DT_PATH_ELLIPSIS.

:M SetTabs:     ( a1 n1 -- )

Set tab positions. a1 is array of cells with offsets

:M SetTabSize:  ( n1 -- n2 )

Set the width of a tab. Returns the old width.

:M GetTabSize:  ( -- n1 )

Get the width of a tab.

:M TabbedTextOut: ( x y addr len -- width height )

The TabbedTextOut method writes a character string at a specified location, expanding tabs to the values specified in an array of tab-stop positions. Text is written in the currently selected font, background color, and text color.

If the method succeeds, the return value is the dimensions, in logical units, of the string.

 Line and Curve methods

:M Arc:         ( nLeftRect nTopRect nRightRect nBottomRect nXStartArc nYStartArc nXEndArc nYEndArc -- )

The Arc method draws an elliptical arc.

The arc is drawn using the current pen; it is not filled.

The current position is neither used nor updated by Arc.

Windows 95/98: The drawing direction is always counterclockwise.

Windows NT/2000: Use the GetArcDirection: and SetArcDirection: methods to get and set the current drawing direction for a device context. The default drawing direction is counterclockwise.

 nLeftRect  x-coord of rectangle's upper-left corner

 nTopRect  y-coord of rectangle's upper-left corner

 nRightRect  x-coord of rectangle's lower-right corner

 nBottomRect  y-coord of rectangle's lower-right corner

 nXStartArc  x-coord of first radial ending point

 nYStartArc  y-coord of first radial ending point

 nXEndArc  x-coord of second radial ending point

 nYEndArc  y-coord of second radial ending point

:M ArcTo:       ( nLeftRect nTopRect nRightRect nBottomRect nXRadial1 nYRadial1 nXRadial2 nYRadial2 -- )

The ArcTo method draws an elliptical arc. ArcTo is similar to the Arc method, except that the current position is updated.

The points ( nLeftRect ,  nTopRect ) and ( nRightRect ,  nBottomRect ) specify the bounding rectangle. An ellipse formed by the specified bounding rectangle defines the curve of the arc. The arc extends counterclockwise from the point where it intersects the radial line from the center of the bounding rectangle to the ( nXRadial1 ,  nYRadial1 ) point. The arc ends where it intersects the radial line from the center of the bounding rectangle to the ( nXRadial2,   nYRadial2 ) point. If the starting point and ending point are the same, a complete ellipse is drawn.

A line is drawn from the current position to the starting point of the arc.

If no error occurs, the current position is set to the ending point of the arc.

The arc is drawn using the current pen; it is not filled.

 nLeftRect  x-coord of rectangle's upper-left corner

 nTopRect  y-coord of rectangle's upper-left corner

 nRightRect  x-coord of rectangle's lower-right corner

 nBottomRect  y-coord of rectangle's lower-right corner

 nXRadial1  x-coord of first radial ending point

 nYRadial1  y-coord of first radial ending point

 nXRadial2  x-coord of second radial ending point

 nYRadial2  y-coord of second radial ending point

:M LineTo:      ( nXEnd nYEnd -- )

The LineTo method draws a line from the current position up to, but not including, the specified point.

The coordinates of the line's ending point are specified in logical units.

The line is drawn by using the current pen and, if the pen is a geometric pen, the current brush.

If LineTo succeeds, the current position is set to the specified ending point.

:M MoveTo:      ( x y -- x1 x2 )

The MoveTo method updates the current position to the specified point and returns the previous position.

:M GetCurrentPosition: ( -- x y )

The GetCurrentPosition method retrieves the current position in logical coordinates.

:M PolyBezier:  ( pPoints cPoints -- )

The PolyBezier method draws one or more Bézier curves.

 pPoints  Pointer to an array of POINT structures that contain the endpoints and control points of the curve(s).

 cPoints  Specifies the number of points in the pPoints array. This value must be one more than three times the number of curves to be drawn, because each Bézier curve requires two control points and an endpoint, and the initial curve requires an additional starting point.

The Polybezier method draws cubic Bézier curves by using the endpoints and control points specified by the pPoints parameter. 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 position is neither used nor updated by the PolyBezier method. The figure is not filled. This method draws lines by using the current pen.

:M PolyBezierTo: ( pPoints cPoints -- )

The PolyBezierTo method draws one or more Bézier curves.

 pPoints  Pointer to an array of POINT structures that contains the endpoints and control points.

 cPoints  Specifies the number of points in the pPoints array. This value must be three times the number of curves to be drawn, because each Bézier curve requires two control points and an ending point.

This method draws cubic Bézier curves by using the control points specified by the pPoints parameter. 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.

PolyBezierTo moves the current position to the ending point of the last Bézier curve. The figure is not filled. This method draws lines by using the current pen.

:M Polyline:    ( pPoints cPoints -- )

The Polyline method draws a series of line segments by connecting the points in the specified array.

 pPoints  Pointer to an array of POINT structures. Each structure in the array identifies a point in logical space.

 cPoints  Specifies the number of points in the array. This number must be greater than or equal to two.

The lines are drawn from the first point through subsequent points by using the current pen. Unlike the LineTo method, the Polyline method neither uses nor updates the current position.

:M PolylineTo:  ( pPoints cPoints -- )

The PolylineTo method draws one or more straight lines.

 pPoints  Pointer to an array of POINT structures that contains the vertices of the line.

 cCount  Specifies the number of points in the array.

A line is drawn from the current position to the first point specified by the pPoints parameter by using the current pen. For each additional line, the method draws from the ending point of the previous line to the next point specified by pPoints.

PolylineTo moves the current position to the ending point of the last line. If the line segments drawn by this method form a closed figure, the figure is not filled.

 Bitmap support

:M CreateCompatibleDC: ( -- hDC )

The CreateCompatibleDC method creates a memory device context compatible with the device.

:M CreateCompatibleBitmap: ( width height -- hBitmap )

The CreateCompatibleBitmap method creates a bitmap compatible with the device that is associated with the device context.

:M BitBlt:      ( nXDest nYDest nWidth nHeight hdcSrc nXSrc nYSrc dwRop -- )

The BitBlt method performs a bit-block transfer of the color data corresponding to a rectangle of pixels from the specified source device context into a destination device context.

 nXDest  x-coord of destination upper-left corner

 nYDest  y-coord of destination upper-left corner

 nWidth  width of destination rectangle

 nHeight  height of destination rectangle

 hdcSrc  handle to source DC

 nXSrc  x-coordinate of source upper-left corner

 nYSrc  y-coordinate of source upper-left corner

 dwRop

:M SetDIBColorTable: ( uStartIndex cEntries pColors -- )

The SetDIBColorTable method sets RGB (red, green, blue) color values in a range of entries in the color table of the DIB that is currently selected into a specified device context.

 uStartIndex  A zero-based color table index that specifies the first color table entry to set.

 cEntries  Specifies the number of color table entries to set.

 pColors  Pointer to an array of RGBQUAD structures containing new color information for the DIB's color table.

:M GetDIBColorTable: ( uStartIndex cEntries pColors -- )

The GetDIBColorTable method retrieves RGB (red, green, blue) color values from a range of entries in the color table of the DIB section bitmap that is currently selected into a specified device context.

 uStartIndex  A zero-based color table index that specifies the first color table entry to retrieve.

 cEntries  Specifies the number of color table entries to retrieve.

 pColors  Pointer to a buffer that receives an array of RGBQUAD data structures containing color information from the DIB's color table. The buffer must be large enough to contain as many RGBQUAD data structures as the value of cEntries.

The GetDIBColorTable method should be called to retrieve the color table for DIB section bitmaps that use 1, 4, or 8 bpp. The biBitCount member of a bitmap's associated BITMAPINFOHEADER structure specifies the number of bits-per-pixel. DIB section bitmaps with a biBitCount value greater than eight do not have a color table, but they do have associated color masks. Use the GetObject method to retrieve those color masks.

:M ExtFloodFill: ( nXStart nYStart crColor fuFillType -- )

The ExtFloodFill method fills an area of the display surface with the current brush.

 nXStart  Specifies the logical x-coordinate of the point where filling is to start.

 nYStart  Specifies the logical y-coordinate of the point where filling is to start.

 crColor  Specifies the color of the boundary or of the area to be filled. The interpretation of crColor depends on the value of the fuFillType parameter.

 fuFillType  Specifies the type of fill operation to be performed. This parameter must be one of the following values.

 FLOODFILLBORDER  The fill area is bounded by the color specified by the crColor parameter. This style is identical to the filling performed by the FloodFill method.

 FLOODFILLSURFACE  The fill area is defined by the color that is specified by crColor. Filling continues outward in all directions as long as the color is encountered. This style is useful for filling areas with multicolored boundaries.

 Path methods A path is one or more figures (or shapes) that are filled, outlined, or both filled and outlined. Win32-based applications use paths in many ways. Paths are used in drawing and painting applications. Computer-aided design (CAD) applications use paths to create unique clipping regions, to draw outlines of irregular shapes, and to fill the interiors of irregular shapes. An irregular shape is a shape composed of Bézier curves and straight lines. (A regular shape is an ellipse, a circle, a rectangle, or a polygon.)

:M BeginPath:   ( -- )

The BeginPath method opens a path bracket in the specified device context After a path bracket is open, an application can begin calling GDI drawing functions to define the points that lie in the path. An application can close an open path bracket by calling the EndPath method.

:M EndPath:     ( -- )

The EndPath method closes a path bracket and selects the path defined by the bracket into the specified device context.

:M AbortPath:     ( -- )

The AbortPath method closes and discards any paths in the specified device context. If there is an open path bracket in the given device context, the path bracket is closed and the path is discarded. If there is a closed path in the device context, the path is discarded.

:M CloseFigure:     ( -- )

The CloseFigure method closes an open figure in a path.

The CloseFigure method closes the figure by drawing a line from the current position to the first point of the figure (usually, the point specified by the most recent call to the MoveToEx function) and then connects the lines by using the line join style. If a figure is closed by using the LineTo function instead of CloseFigure, end caps are used to create the corner instead of a join.

The CloseFigure function should only be called if there is an open path bracket in the specified device context.

A figure in a path is open unless it is explicitly closed by using this function. (A figure can be open even if the current point and the starting point of the figure are the same.)

After a call to CloseFigure, adding a line or curve to the path starts a new figure.

:M FillPath:    ( -- )

The FillPath method closes any open figures in the current path and fills the path's interior by using the current brush and polygon-filling mode. After its interior is filled, the path is discarded from the DC

:M FlattenPath: ( -- )

The FlattenPath method transforms any curves in the path that is selected into the current device context (DC), turning each curve into a sequence of lines.

:M GetPath:     ( lpPoints lpTypes nSize -- n )

The GetPath method retrieves the coordinates defining the endpoints of lines and the control points of curves found in the path that is selected into the device context.  lpPoints  Pointer to an array of POINT structures that receives the line endpoints and curve control points.

 lpTypes  Pointer to an array of bytes that receives the vertex types. This parameter can be one of the following values.

 PT_MOVETO  Specifies that the corresponding point in the lpPoints parameter starts a disjoint figure.

 PT_LINETO  Specifies that the previous point and the corresponding point in lpPoints are the endpoints of a line.

 PT_BEZIERTO  Specifies that the corresponding point in lpPoints is a control point or ending point for a Bézier curve. PT_BEZIERTO values always occur in sets of three. The point in the path immediately preceding them defines the starting point for the Bézier curve. The first two PT_BEZIERTO points are the control points, and the third PT_BEZIERTO point is the ending (if hard-coded) point.

A PT_LINETO or PT_BEZIERTO value may be combined with the following value (by using the bitwise operator OR) to indicate that the corresponding point is the last point in a figure and the figure should be closed. Flag Description PT_CLOSEFIGURE Specifies that the figure is automatically closed after the corresponding line or curve is drawn. The figure is closed by drawing a line from the line or curve endpoint to the point corresponding to the last PT_MOVETO.

 nSize  Specifies the total number of POINT structures that can be stored in the array pointed to by lpPoints. This value must be the same as the number of bytes that can be placed in the array pointed to by lpTypes.

If the nSize parameter is nonzero, the return value is the number of points enumerated. If nSize is 0, the return value is the total number of points in the path (and GetPath writes nothing to the buffers). If nSize is nonzero and is less than the number of points in the path, the return value is -1.

:M PathToRegion:  ( -- )

The PathToRegion method creates a region from the path that is selected into the specified device context. The resulting region uses device coordinates. After PathToRegion converts a path into a region, the system discards the closed path from the device context.

:M StrokePath:  ( -- )

The StrokePath method renders the specified path by using the current pen.

:M StrokeAndFillPath:    ( -- )

The StrokeAndFillPath 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. The StrokeAndFillPath method has the same effect as closing all the open figures in the path, and stroking and filling the path separately, except that the filled region will not overlap the stroked region even if the pen is wide.

:M WidenPath:   ( -- )

The WidenPath function redefines the current path as the area that would be painted if the path were stroked using the pen currently selected into the given device context. The WidenPath function is successful only if the current pen is a geometric pen created by the ExtCreatePen function, or if the pen is created with the CreatePen function and has a width, in device units, of more than one. The device context identified by the hdc parameter must contain a closed path. Any Bézier curves in the path are converted to sequences of straight lines approximating the widened curves. As such, no Bézier curves remain in the path after WidenPath is called.

 Missing methods: SetPixel
GetPixel
GetStretchBltMode
AlphaBlend    W98 and w2k or later
GradientFill  W98 and w2k or later
SetDIBitsToDevice
SetStretchBltMode
StretchBlt
StretchDIBits
TransparentBlt W98 and w2k or later
PatBlt
AngleArc
SetMiterLimit
GetMiterLimit

;class

End of gdiDC class

Document $Id: gdiDC.htm,v 1.12 2007/05/26 10:24:13 dbu_de Exp $