< Home < Developers < Development Support < Documentation

## 55 Windows

Table of Contents | < Previous | Next > | Index

| Title - Palm OS® Programmer's API Reference Part II: System Management 55 Windows Window Data Structures CustomPatternType DrawStateType FrameBitsType FrameType IndexedColorType PatternType UnderlineModeType WindowFlagsType WindowType WinDrawOperation WinHandle WinLineType WinPtr Window Functions WinClipRectangle WinCopyRectangle WinCreateBitmapWindow WinCreateOffscreenWindow WinCreateWindow WinDeleteWindow WinDisplayToWindowPt WinDrawBitmap WinDrawChar WinDrawChars WinDrawGrayLine WinDrawGrayRectangleFrame WinDrawInvertedChars WinDrawLine WinDrawPixel WinDrawRectangle WinDrawRectangleFrame WinDrawTruncChars WinEraseChars WinEraseLine WinErasePixel WinEraseRectangle WinEraseRectangleFrame WinEraseWindow WinFillLine WinFillRectangle WinGetActiveWindow WinGetBitmap WinGetBounds WinGetClip WinGetDisplayExtent WinGetDisplayWindow WinGetDrawWindow WinGetDrawWindowBounds WinGetFirstWindow WinGetFramesRectangle WinGetPattern WinGetPatternType WinGetPixel WinGetPixelRGB WinGetWindowExtent WinGetWindowFrameRect WinIndexToRGB WinInvertChars WinInvertLine WinInvertPixel WinInvertRectangle WinInvertRectangleFrame WinModal WinPaintBitmap WinPaintChar WinPaintChars WinPaintLine WinPaintLines WinPaintPixel WinPaintPixels WinPaintRectangle WinPaintRectangleFrame WinPalette WinPopDrawState WinPushDrawState WinResetClip WinRestoreBits WinRGBToIndex WinSaveBits WinScreenLock WinScreenMode WinScreenUnlock WinScrollRectangle WinSetActiveWindow WinSetBackColor WinSetBackColorRGB WinSetBounds WinSetClip WinSetDrawMode WinSetDrawWindow WinSetForeColor WinSetForeColorRGB WinSetPattern WinSetPatternType WinSetTextColor WinSetTextColorRGB WinSetUnderlineMode WinValidateHandle WinWindowToDisplayPt |  |  |  | This chapter provides information about windows by discussing these topics: Window Data Structures Window Functions No resources are associated with window objects. The header file Window.h declares the API that this chapter describes. For more information on windows, see the section "Forms, Windows, and Dialogs" in the Palm OS Programmer's Companion, vol. I. ## Window Data Structures ## CustomPatternType The CustomPatternType type holds an 8-by-8 bit pattern that is one bit deep. Each byte specifies a row of the pattern. When drawing, a pattern is tiled to fill a specified region. This pattern is used by WinFillLine and WinFillRectangle. The PatternType specifies the name of the current pattern.
    typedef UInt8 CustomPatternType [8];
#### Compatibility In pre-3.5 systems, the CustomPatternType is an array of 4 16-bit words. Note the size of this data type has not changed. ## DrawStateType The DrawStateType structure defines the current drawing state, which is the Palm OS® implementation of a pen. This drawing state is saved with WinPushDrawState and restored with WinPopDrawState. WARNING! Palm, Inc. does not support or provide backward compatibility for the DrawStateType structure. Access it only through the functions described below. Never access its structure members directly, or your code may break in future versions. Use the information below for debugging purposes only.
    typedef struct DrawStateType {
      WinDrawOperation   transferMode;
      PatternType        pattern;
      UnderlineModeType  underlineMode;
      FontID             fontId;
      FontPtr            font;
      CustomPatternType  patternData;
      IndexedColorType   foreColor;
      IndexedColorType   backColor;
      IndexedColorType   textColor;
      RGBColorType       foreColorRGB;
      RGBColorType       backColorRGB;
      RGBColorType       textColorRGB;
    } DrawStateType;
#### Field Description #####
transferMode | The current transfer mode for color drawing. See WinDrawOperation. Use WinSetDrawMode to set this value.
pattern | The name of the current pattern. See PatternType. If set to customPattern, the patternData field contains the actual pattern. Use WinGetPatternType and WinSetPatternType to retrieve and set this value.
underlineMode | The current underline mode. See UnderlineModeType. Use WinSetUnderlineMode to set this value.
fontId | The ID of the current font. Use FntSetFont to set this value.
font | A pointer to the current font. Use FntSetFont to set this value.
patternData | The current pattern being used by the WinFill functions if pattern is customPattern. See CustomPatternType. Use WinGetPattern and WinSetPattern to retrieve and set this value.
foreColor | Index of the current color used for the foreground. Use WinSetForeColor to set this value.
backColor | Index of the current color used for the background. Use WinSetBackColor to set this value.
textColor | Index of the current color used for text. Use WinSetTextColor to set this value.
foreColorRGB | RGB value of the current color used for the foreground. Use WinSetForeColorRGB to set this value. Only valid for Palm OS 4.0.
backColorRGB | RGB value of the current color used for the background. Use WinSetBackColorRGB to set this value. Only valid for Palm OS 4.0.
textColorRGB | RGB value of the current color used for text. Use WinSetTextColorRGB to set this value. Only valid for Palm OS 4.0.
#### Compatibility This type is implemented only if 3.5 New Feature Set is present. ## FrameBitsType The FrameBitsType structure specifies attributes of a window's frame. WARNING! Palm, Inc. does not support or provide backward compatibility for the FrameBitsType bit field. Never access its bit field members directly, or your code may break in future versions. Use the information below for debugging purposes only.
    typedef union FrameBitsType {
      struct {
        UInt16 cornerDiam  : 8;
        UInt16 reserved_3  : 3;
        UInt16 threeD      : 1;
        UInt16 shadowWidth : 2;
        UInt16 width       : 2;
      } bits;
      UInt16 word;
    } FrameBitsType;
#### Field Descriptions #####
cornerDiam | Corner radius of frame; maximum is 38.
reserved_3 | Reserved.
threeD | Set this bit to draw a 3D button. This feature is not currently supported.
shadowWidth | Width of shadow.
width | Frame width.
word | Reserved.
## FrameType The FrameType type specifies a window frame style.
    typedef UInt16 FrameType;
The FrameType can be set to one of the defined frame types shown in the table below, or a custom frame type as defined by a FrameBitsType structure. #####
Constant | Value | Description
--- | --- | ---
noFrame | 0 | No frame
simpleFrame | 1 | Plain rectangular frame
rectangleFrame | 1 | Plain rectangular frame
simple3DFrame | 0x0012 | 3D frame with width of 2. This frame type is not supported.
roundFrame | 0x0401 | Round frame with width of 1.
boldRoundFrame | 0x0702 | Round frame with width of 2.
popupFrame | 0x0205 | Popup frame style with slight corner roundness, width of 1 and shadow of 1.
dialogFrame | 0x0302 | Dialog frame style with slight corner roundness and width of 2.
menuFrame | popupFrame | Same as popupFrame.
## IndexedColorType The IndexedColorType type is used to specify a color by its index value; that is, by its location in a color table. Color tables are defined by the ColorTableType structure, which is declared in Bitmap.h. The IndexedColorType can hold a 1, 2, 4, or 8-bit index.
    typedef UInt8 IndexedColorType;
#### Compatibility This type is implemented only if 3.5 New Feature Set is present. ## PatternType The PatternType enumerated type specifies a pattern for drawing. This type is returned by WinGetPatternType and is used as a parameter to the WinSetPatternType function.
    typedef enum { blackPattern, whitePattern,
    grayPattern, customPattern } PatternType;
#### Value Descriptions #####
blackPattern | Pattern with all bits on.
whitePattern | Pattern with all bits off.
grayPattern | Pattern with alternating on and off bits.
customPattern | Custom pattern specified by CustomPatternType.
These patterns all operate with current foreground and background color instead of black and white. In effect, blackPattern is only black if the current foreground color is black. whitePattern uses the current background color. grayPattern and customPattern uses a combination of background and foreground colors. ## UnderlineModeType The UnderlineModeType enumerated type specifies possible values for the underline mode stored in DrawStateType.
    typedef enum { noUnderline, grayUnderline,
    solidUnderline, colorUnderline } UnderlineModeType;
#### Value Descriptions #####
noUnderline | No underline.
grayUnderline | Underline is drawn using a dotted line in the current foreground color.
solidUnderline | Underline is drawn using a solid line in the foreground color.
colorUnderline | Underline is drawn using a solid line in the foreground color.
#### Compatibility The solidUnderline and colorUnderline options are only available in Palm OS 3.1 and higher. ## WindowFlagsType The WindowFlagsType specifies different window attributes. WARNING! Palm, Inc. does not support or provide backward compatibility for the WindowFlagsType bit field. Access it only through the functions described below. Never access its bit field members directly, or your code may break in future versions. Use the information below for debugging purposes only.
    typedef struct WindowFlagsType {
      UInt16 format:1;
      UInt16 offscreen:1;
      UInt16 modal:1;
      UInt16 focusable:1;
      UInt16 enabled:1;
      UInt16 visible:1;
      UInt16 dialog:1;
      UInt16 freeBitmap:1;
      UInt16 reserved :8;
    } WindowFlagsType;
#### Field Descriptions #####
format | If set, use the genericFormat. If 0, use screenFormat. Screen format is the native format of the video system; windows in this format can be copied to the display faster. The generic format is device-independent. A window cannot be enabled (that is, accept pen input) unless it uses screen format.
offscreen | If set, the window is offscreen. If 0, the window is onscreen.
modal | If set, the window is modal. If 0, the window is not modal. You set this value when you create the window. This value is returned by WinModal.
focusable | If set, the window can accept the focus. If 0, the window does not accept the focus. You set this value when you create the window.
enabled | If set, the window is enabled. If 0, the window is disabled.
visible | If set, the window is visible if it is onscreen. If 0, the window is not visible.
dialog | If set, the window is a form. If 0, the window is not a form. The FrmInitForm function sets this value.
freeBitmap | If set, free the bitmap when the window is freed. If 0, retain the bitmap after the window is freed.
reserved | Reserved for future use. Must be 0.
#### Compatibility In OS versions previous to 3.5, the freeBitmap flag was not present. Instead, a compressed flag was present, where 0 specified uncompressed and 1 specified compressed. This compressed flag is now part of the BitmapType. ## WindowType The WindowType structure represents a window. WARNING! Palm, Inc. does not support or provide backward compatibility for the WindowType structure. Access it only through the functions described below. Never access its structure members directly, or your code may break in future versions. Use the information below for debugging purposes only.
    typedef struct WindowType {
      Coord              displayWidthV20;
      Coord              displayHeightV20;
      void               *displayAddrV20;
      WindowFlagsType    windowFlags;
      RectangleType      windowBounds;
      AbsRectType        clippingBounds;
      BitmapPtr          bitmapP;
      FrameBitsType      frameType;
      DrawStateType      *drawStateP;
      struct WindowType     *nextWindow;
    } WindowType;
#### Field Descriptions #####
displayWidthV20 | Width of the window in pre OS 3.5 devices. In OS 3.5, use WinGetBounds to return the window width.
displayHeightV20 | Height of the window in pre OS 3.5 devices. In OS 3.5, use WinGetBounds to return the window height.
displayAddrV20 | Pointer to the window display memory buffer in pre OS 3.5 devices. In OS 3.5 or later, call WinGetBitmap and then BmpGetBits to obtain the window's memory buffer. WARNING! Writing directly to screen memory will not be supported in all devices.
windowFlags | Window attributes (see WindowFlagsType).
windowBounds | Display-relative bounds of the window. Use WinGetBounds and WinSetBounds to retrieve and set this value.
clippingBounds | Bounds for clipping any drawing within the window. Use WinGetClip and WinSetClip to retrieve and set this value.
bitmapP | Pointer to the window bitmap, which holds the window's contents. Use WinGetBitmap to retrieve this value.
frameType | Frame attributes; see FrameBitsType.
drawStateP | Pointer to a state of the current transfer mode, pattern mode, font, underline mode, and colors. See DrawStateType. Only one drawing state exists in the system. Each window points to the same structure.
nextWindow | Pointer to the next window in a linked list of windows. This linked list of windows is called the active window list. Do not change this field.
#### Compatibility In OS versions previous to 3.5, this structure is slightly different. Specifically, the bitmapP field is instead a viewOrigin field of type PointType and specified the window origin point on the display. The drawStateP was named gstate and was of type GraphicStatePtr. The complete definition is shown below:
    typedef struct WinTypeStruct {
      Word                   displayWidth;
      Word                   displayHeight;
      VoidPtr                displayAddr;
      WindowFlagsType        windowFlags;
      RectangleType          windowBounds;
      AbsRectType            clippingBounds;
      PointType              viewOrigin;
      FrameBitsType          frameType;
      GraphicStatePtr        gstate;
      struct WinTypeStruct     *nextWindow;
    } WindowType;
## WinDrawOperation The WinDrawOperation enumerated type specifies the transfer mode for color drawing. This type is used as a parameter to the WinCopyRectangle and WinSetDrawMode functions.
    typedef enum {winPaint, winErase, winMask,
    winInvert, winOverlay, winPaintInverse,
    winSwap} WinDrawOperation;
#### Value Descriptions #####
winPaint | Destination replaced with source pixels (copy mode).
winErase | Destination cleared where source pixels are off (AND mode).
winMask | Destination cleared where source pixels are on (AND NOT mode).
winInvert | Destination inverted where source pixels are on (XOR mode).
winOverlay | Destination set only where source pixels are on (OR mode).
winPaintInverse | Destination replaced with inverted source (copy NOT mode).
winSwap | Destination foreground and background colors are swapped, leaving any other colors unchanged (color invert operation).
For winErase, winMask, winInvert, and winOverlay, on means a pixel with an non-zero index (or for direct bitmaps, a non-zero RGB value), while off means a pixel with an index of 0 (or for direct bitmaps, an RGB value of 0). When drawing graphics data, the OS first converts the source data to the depth of the destination. For 1-bit bitmaps, rectangles, lines, text, and pixels, this operation uses the foreground color for on pixels and the background color for off pixels. For bitmaps with a depth greater than 1, the source bitmap's pixel values are used rather than the foreground and background colors. The OS then applies the logical operation described in this section. For winMask (AND NOT) and winPaintInverse (COPY NOT), the depth-converted source data is inverted before it is AND'ed with or COPY'ed to the destination data. winSwap is not a color invert operation, although a pair of winSwap operations will restore the original graphics data. This mode is used by the OS to select and deselect areas of the screen. It changes destination pixels matching the foreground color to the background color, and changes destination pixels matching the background color to the foreground color. It is a mode available for rectangles, lines, and pixels, but not text or bitmaps. This mode ignores the current pattern. #### Compatibility This type is implemented only if 3.5 New Feature Set is present. In earlier releases, this type is named ScrOperation and its values begin with the prefix scr rather than win. WinDrawOperation is fully compatible with ScrOperation. ## WinHandle The WinHandle type is a pointer to a WindowType structure. Note that this may change.
    typedef WindowType *WinHandle;
## WinLineType The WinLineType structure defines a line.
    typedef struct WinLineType {
      Coord x1;
      Coord y1;
      Coord x2;
      Coord y2;
    } WinLineType;
#### Field Descriptions #####
x1 | X coordinate of the first endpoint of the line.
y1 | Y coordinate of the first endpoint of the line.
x2 | X coordinate of the second endpoint of the line.
y2 | Y coordinate of the second endpoint of the line.
#### Compatibility This type is implemented only if 3.5 New Feature Set is present. ## WinPtr The WinPtr type is a pointer to a WindowType structure.
    typedef WindowType *WinPtr;
## Window Functions ## WinClipRectangle #### Purpose Shrink the rectangle to make it fit within the clipping region of the current draw window. #### Prototype void WinClipRectangle (RectangleType *rP) #### Parameters #####
<-> rP | Pointer to a structure holding the rectangle to clip. The rectangle returned is the intersection of the rectangle passed and the clipping bounds of the draw window.
#### Result Returns nothing. #### Comments This function does not change the clipping rectangle of the window. To modify the window's clipping rectangle, use the WinSetClip and WinResetClip functions. The draw window is the window to which all drawing functions send their output. It is returned by WinGetDrawWindow. #### See Also WinCopyRectangle, WinDrawRectangle, WinEraseRectangle, WinGetClip ## WinCopyRectangle #### Purpose Copy a rectangular region from one place to another (either between windows or within a single window). #### Prototype void WinCopyRectangle (WinHandle srcWin, WinHandle dstWin, const RectangleType *srcRect, Coord destX, Coord destY, WinDrawOperation mode) #### Parameters #####
-> srcWin | Window from which the rectangle is copied. If NULL, use the draw window.
#####
-> dstWin | Window to which the rectangle is copied. If NULL, use the draw window.
#####
-> srcRect | Bounds of the region to copy.
#####
-> destX | Top bound of the rectangle in destination window.
#####
-> destY | Left bound of the rectangle in destination window.
#####
-> mode | The method of transfer from the source to the destination window (see WinDrawOperation).
#### Result Returns nothing. #### Comments Copies the bits of the window inside the rectangle region. If the destination bitmap is compressed, the mode parameter must be winPaint, and the destination coordinates must be (0,0). If the width of the destination rectangle is less than 16 pixels or if the destination coordinates are not (0,0), then this function turns off compression for the destination bitmap. Normally, you do not copy to a compressed bitmap. Instead, you copy to an uncompressed bitmap and compress it afterwards. #### Compatibility In OS versions before 3.5, the mode parameter was defined as type ScrOperation. It is defined as type WinDrawOperation only if 3.5 New Feature Set is present. ScrOperation and WinDrawOperation are fully compatible with each other. In OS versions before 3.5, it was common practice to render a bitmap in an offscreen window and then use WinCopyRectangle to draw it on the screen. In version 3.5 and higher, the preferred method of doing this is to use WinDrawBitmap or WinPaintBitmap. #### See Also WinDrawBitmap ## WinCreateBitmapWindow #### Purpose Create a new offscreen window. #### Prototype WinHandle WinCreateBitmapWindow (BitmapType *bitmapP, UInt16 *error) #### Parameters #####
-> bitmapP | Pointer to a bitmap to associate with the window. (See BitmapType.)
#####
<- error | Pointer to any error this function encounters.
#### Result Returns the handle of the new window upon success, or NULL if an error occurs. The error parameter contains one of the following: #####
errNone | No error.
#####
sysErrParamErr | The bitmapP parameter is invalid. The bitmap must be uncompressed and it must have a valid pixel size (1, 2, 4, or 8). It must not be the screen bitmap.
#####
sysErrNoFreeResource | There is not enough memory to allocate a new window structure.
#### Comments Use WinCreateBitmapWindow if you want to draw into a previously created bitmap, such as a bitmap created using BmpCreate. This function generates a window wrapper for the specified bitmap. The newly created window is offscreen, uses the generic format (for device independence), and is added to the active window list. Use WinSetDrawWindow to make it the draw window, and then use the window drawing functions to modify the bitmap. When you use this function to create a window and then delete the window with WinDeleteWindow, the bitmap is not freed when the window is freed. WinCreateOffscreenWindow uses this function to create its offscreen window. If you call WinCreateOffscreenWindow instead of using this function, the bitmap is freed when WinDeleteWindow is called. The bitmap data will not be blitted properly if the depth of the screen is changed using WinScreenMode and the new window uses a bitmap that does not define the bitmap's color table. See WinScreenMode for information on how to work around this limitation. #### Compatibility Implemented only if 3.5 New Feature Set is present. #### See Also WinCreateWindow, WinCreateOffscreenWindow ## WinCreateOffscreenWindow #### Purpose Create a new offscreen window and add it to the window list. #### Prototype WinHandle WinCreateOffscreenWindow (Coord width, Coord height, WindowFormatType format, UInt16 *error) #### Parameters #####
-> width | Width of the window in pixels.
#####
-> height | Height of the window in pixels.
#####
-> format | Either screenFormat or genericFormat. In general, you should use genericFormat for offscreen windows.
#####
<- error | Pointer to any error this function encounters.
#### Result Returns the handle of the new window upon success, or NULL if an error occurs. The error parameter contains one of the following: #####
errNone | No error.
#####
sysErrParamErr | The width or height parameter is NULL or the current color table is invalid.
#####
sysErrNoFreeResource | There is not enough memory to complete the function.
The debug ROM gives a warning if you try to draw to a bad window address. #### Comments Windows created with this routine draw to a memory buffer instead of the display. Use this function for temporary drawing operations such as double-buffering or save-behind operations. The memory buffer has two formats: screen format and generic format. Screen format is the native format of the video system; windows in this format can be copied to the display faster. The generic format is device-independent. A window cannot be enabled (that is, accept pen input) unless it uses screen format. This function differs from WinCreateBitmapWindow in the following ways: WinCreateOffscreenWindow creates a new bitmap in the same depth as the current screen. WinCreateBitmapWindow uses the bitmap you pass in, which may or may not be in the same depth as the current screen. WinCreateOffscreenWindow uses the screen format you specify. WinCreateBitmapWindow always uses genericFormat for the format argument. When you delete the window created with WinCreateOffscreenWindow, its bitmap is freed along with the window. The bitmap used in the WinCreateBitmapWindow is not freed when the window is freed. The bitmap data will not be blitted properly if the depth of the screen is changed using WinScreenMode and the new window uses a bitmap that does not define the bitmap's color table. See WinScreenMode for information on how to work around this limitation. #### See Also WinCreateWindow, WinScreenMode, ## WinCreateWindow #### Purpose Create a new window and add it to the window list. #### Prototype WinHandle WinCreateWindow (const RectangleType *bounds, FrameType frame, Boolean modal, Boolean focusable, UInt16 *error) #### Parameters #####
-> bounds | Display-relative bounds of the window.
#####
-> frame | Type of frame around the window (see FrameType).
#####
-> modal | true if the window is modal.
#####
-> focusable | true if the window can be the active window.
#####
<- error | Pointer to any error encountered by this function.
#### Result Returns the handle of the new window upon success, or NULL if an error occurs. The error parameter contains one of the following: #####
errNone | No error.
#####
sysErrNoFreeResource | There is not enough memory to complete the operation.
#### Comments Windows created by this routine draw to the display. See WinCreateOffscreenWindow for information on drawing off screen. You typically don't call this function directly. Instead, you use FrmInitForm to create form windows from a resource. Forms are much more flexible and have better system support. All forms are windows, but not all windows are forms. The window is created with the bounds and frame type that you specify and uses the bitmap and drawing state of the current draw window. Its clipping region is reset according to the bounds you specify. All window flags are set to 0 except for the modal and focusable flags, which you pass as a parameter to this function. Specifically, newly created windows are disabled and invisible. You must specifically enable the window before the window can accept input. You can do so with WinSetActiveWindow. #### See Also WinDeleteWindow ## WinDeleteWindow #### Purpose Remove a window from the window list and free the memory used by the window. #### Prototype void WinDeleteWindow (WinHandle winHandle, Boolean eraseIt) #### Parameters #####
-> winHandle | Handle of window to delete.
#####
-> eraseIt | If true, the window is erased before it is deleted. If false, the window is not erased.
#### Result Returns nothing. #### Comments This function frees all memory associated with the window. Windows created using WinCreateOffscreenWindow have their bitmaps freed; windows created using WinCreateWindow or WinCreateBitmapWindow do not. The eraseIt parameter affects onscreen windows only; offscreen windows are never erased. As a performance optimization, you might set eraseIt to false for an onscreen window if you know that you are going to immediately redraw the area anyway. For example, when the form manager closes a form dialog, it restores the area with the save-behind bits it had stored for that form. For this reason, when the form manager deletes the dialog window, it passes false for eraseIt because the entire area will be redrawn. ## WinDisplayToWindowPt #### Purpose Convert a display-relative coordinate to a window-relative coordinate. The coordinate returned is relative to the display window. #### Prototype void WinDisplayToWindowPt (Coord *extentX, Coord *extentY) #### Parameters #####
<-> extentX | Pointer to x coordinate to convert.
#####
<-> extentY | Pointer to y coordinate to convert.
#### Result Returns nothing. #### See Also WinWindowToDisplayPt ## WinDrawBitmap #### Purpose Draw a bitmap at the given coordinates in winPaint mode (see WinDrawOperation for mode details). #### Prototype void WinDrawBitmap (BitmapPtr bitmapP, Coord x, Coord y) #### Parameters #####
-> bitmapP | Pointer to a bitmap.
#####
-> x | The x coordinate of the top-left corner.
#####
-> y | The y coordinate of the top-left corner.
#### Result Returns nothing. #### Comments If the bitmap has multiple depths (is a bitmap family), the closest match less than or equal to the current draw window depth is used. If such a bitmap does not exist, the bitmap with the closest match greater than the draw window depth is used. If the bitmap has its own color table, color conversion to the draw window color table will be applied (on OS 3.5 or later). This color conversion is slow and not recommended. Instead of including a color table in the bitmap, consider using WinPalette to change the system color table, draw the bitmap, and then change the system color table back when the bitmap is no longer visible. This function differs from WinPaintBitmap in that this function always uses winPaint mode (copy mode) as the transfer mode. WinPaintBitmap uses the current drawing state transfer mode. #### See Also WinEraseRectangle ## WinDrawChar #### Purpose Draw the specified character in the draw window. #### Prototype void WinDrawChar (WChar theChar, Coord x, Coord y) #### Parameters #####
-> theChar | The character to draw. This may be either a single-byte character or a multi-byte character.
#####
-> x | x coordinate of the location where the character is to be drawn (left bound).
#####
-> y | y coordinate of the location where the character is to be drawn (top bound).
#### Result Returns nothing. #### Comments Before calling this function, call WinSetUnderlineMode and FntSetFont to set the desired underline and font to draw the characters. This function differs from WinPaintChar in that this function always uses winPaint mode (see WinDrawOperation). This means the on bits are drawn in the text color, the off bits are in the background color, and underlines are in the foreground color. WinPaintChar uses the current drawing state transfer mode instead of winPaint. #### Compatibility Implemented only if 3.1 New Feature Set is present. To use this function in code intended to be run on earlier versions of Palm OS, link with the PalmOSGlue library and call WinGlueDrawChar. For more information, see Chapter 76, "PalmOSGlue Library." #### See Also WinDrawChars, WinDrawInvertedChars, WinDrawTruncChars, WinEraseChars, WinInvertChars, WinPaintChars ## WinDrawChars #### Purpose Draw the specified characters in the draw window. #### Prototype void WinDrawChars (const Char *chars, Int16 len, Coord x, Coord y) #### Parameters #####
-> chars | Pointer to the characters to draw.
#####
-> len | Length in bytes of the characters to draw.
#####
-> x | x coordinate of the first character to draw (left bound).
#####
-> y | y coordinate of the first character to draw (top bound).
#### Result Returns nothing. #### Comments This function is useful for printing non-editable status or warning messages on the screen. Before calling this function, call WinSetUnderlineMode and FntSetFont to set the desired underline and font to draw the characters. This function differs from WinPaintChars in that this function always uses winPaint mode (see WinDrawOperation). This means the on bits are drawn in the text color, the off bits are in the background color, and underlines are in the foreground color. WinPaintChar uses the current drawing state transfer mode instead of winPaint. #### See Also WinDrawChar, WinDrawInvertedChars, WinDrawTruncChars, WinEraseChars, WinInvertChars, WinPaintChar ## WinDrawGrayLine #### Purpose Draw a dashed line in the draw window. #### Prototype void WinDrawGrayLine (Coord x1, Coord y1, Coord x2, Coord y2) #### Parameters #####
-> x1 | x coordinate of line start point.
#####
-> y1 | y coordinate of line start point.
#####
-> x2 | x coordinate of line endpoint.
#####
-> y2 | y coordinate of line endpoint.
#### Result Returns nothing. #### Comments This routine does not draw in the gray color; it draws with alternating foreground and background pixels. That is, it uses the grayPattern pattern type. #### See Also WinDrawLine, WinEraseLine, WinFillLine, WinInvertLine, WinPaintLine, WinPaintLines ## WinDrawGrayRectangleFrame #### Purpose Draw a gray rectangular frame in the draw window. #### Prototype void WinDrawGrayRectangleFrame (FrameType frame, const RectangleType *rP) #### Parameters #####
-> frame | Type of frame to draw (see FrameType).
#####
-> rP | Pointer to the rectangle to frame.
#### Result Returns nothing. #### Comments This routine does not draw in the gray color; it draws with alternating foreground and background pixels. The standard gray pattern is not used by this routine; rather, the frame is drawn so that the top-left pixel of the frame is always on. #### See Also WinDrawRectangleFrame, WinEraseRectangleFrame, WinGetFramesRectangle, WinInvertRectangleFrame, WinPaintRectangleFrame ## WinDrawInvertedChars #### Purpose Draw the specified characters inverted (background color) in the draw window. #### Prototype void WinDrawInvertedChars (const Char *chars, Int16 len, Coord x, Coord y) #### Parameters #####
-> chars | Pointer to the characters to draw.
#####
-> len | Length in bytes of the characters to draw.
#####
-> x | x coordinate of the first character to draw (left bound).
#####
-> y | y coordinate of the first character to draw (top bound).
#### Result Returns nothing. #### Comments This routine draws the on bits and any underline in the background color and the off bits in the text color. (Black and white uses copy NOT mode.) This is the standard function for drawing inverted text. Before calling this function, consider calling WinSetUnderlineMode and FntSetFont. #### See Also WinDrawChar, WinDrawChars, WinDrawTruncChars, WinEraseChars, WinInvertChars, WinPaintChar, WinPaintChars ## WinDrawLine #### Purpose Draw a line in the draw window using the current foreground color. #### Prototype void WinDrawLine (Coord x1, Coord y1, Coord x2, Coord y2) #### Parameters #####
-> x1 | x coordinate of line start point.
#####
-> y1 | y coordinate of line start point.
#####
-> x2 | x coordinate of line endpoint.
#####
-> y2 | y coordinate of line endpoint.
#### Result Returns nothing. #### Comments This function differs from WinPaintLine in that it always uses winPaint mode (see WinDrawOperation). WinPaintLine uses the current drawing state transfer mode instead of winPaint. #### See Also WinDrawGrayLine, WinEraseLine, WinFillLine, WinInvertLine, WinPaintLine, WinPaintLines ## WinDrawPixel #### Purpose Draw a pixel in the draw window using the current foreground color. #### Prototype void WinDrawPixel (Coord x, Coord y) #### Parameters #####
-> x | Pointer to the x coordinate of a pixel.
#####
-> y | Pointer to the y coordinate of a pixel.
#### Result Returns nothing. May display a fatal error message if the draw window's bitmap is compressed. #### Compatibility Implemented only if 3.5 New Feature Set is present. #### See Also WinErasePixel, WinInvertPixel, WinPaintPixel, WinPaintPixels ## WinDrawRectangle #### Purpose Draw a rectangle in the draw window using the current foreground color. #### Prototype void WinDrawRectangle (const RectangleType *rP, UInt16 cornerDiam) #### Parameters #####
-> rP | Pointer to the rectangle to draw.
#####
-> cornerDiam | Radius of rounded corners. Specify zero for square corners.
#### Result Returns nothing. #### Comments The cornerDiam parameter specifies the radius of four imaginary circles used to form the rounded corners. An imaginary circle is placed within each corner tangent to the rectangle on two sides. This function differs from WinPaintRectangle in that it always uses winPaint mode (see WinDrawOperation). WinPaintRectangle uses the current drawing state transfer mode instead of winPaint. #### See Also WinEraseRectangle, WinFillRectangle, WinInvertRectangle ## WinDrawRectangleFrame #### Purpose Draw a rectangular frame in the draw window using the current foreground color. #### Prototype void WinDrawRectangleFrame (FrameType frame, const RectangleType *rP) #### Parameters #####
-> frame | Type of frame to draw (see FrameType).
#####
-> rP | Pointer to the rectangle to frame.
#### Result Returns nothing. #### Comments The frame is drawn outside the specified rectangle. This function differs from WinPaintRectangleFrame in that it always uses winPaint mode (see WinDrawOperation). WinPaintRectangleFrame uses the current drawing state transfer mode instead of winPaint. #### See Also WinDrawGrayRectangleFrame, WinEraseRectangleFrame, WinGetFramesRectangle, WinInvertRectangleFrame ## WinDrawTruncChars #### Purpose Draw the specified characters in the draw window, truncating the characters to the specified width. #### Prototype void WinDrawTruncChars (const Char *chars, Int16 len, Coord x, Coord y, Coord maxWidth) #### Parameters #####
-> chars | Pointer to the characters to draw.
#####
-> len | Length in bytes of the characters to draw.
#####
-> x | x coordinate of the first character to draw (left bound).
#####
-> y | y coordinate of the first character to draw (top bound).
#####
-> maxWidth | Maximum width in pixels of the characters that are to be drawn.
#### Result Returns nothing. #### Comments Before calling this function, consider calling WinSetUnderlineMode and FntSetFont. If drawing all of the specified characters requires more space than maxWidth allows, WinDrawTruncChars draws one less than the number of characters that can fit in maxWidth and then draws an ellipsis (...) in the remaining space. (If the boundary characters are narrower than the ellipsis, more than one character may be dropped to make room.) If maxWidth is narrower than the width of an ellipsis, nothing is drawn. Use this function to truncate text that may contain multi-byte characters. #### Compatibility Implemented only if 3.1 New Feature Set is present. To use this function in code intended to be run on earlier versions of Palm OS, link with the PalmOSGlue library and call WinGlueDrawTruncChars. For more information, see Chapter 76, "PalmOSGlue Library." #### See Also WinDrawChar, WinDrawChars, WinDrawInvertedChars, WinEraseChars, WinInvertChars, WinPaintChar, WinPaintChars ## WinEraseChars #### Purpose Erase the specified characters in the draw window. #### Prototype void WinEraseChars (const Char *chars, Int16 len, Coord x, Coord y) #### Parameters #####
-> chars | Pointer to the characters to erase.
#####
-> len | Length in bytes of the characters to erase.
#####
-> x | x coordinate of the first character to erase (left bound).
#####
-> y | y coordinate of the first character to erase (top bound).
#### Result Returns nothing. #### Comments The winMask transfer mode is used to erase the characters. See WinDrawOperation for more information. This has the effect of erasing only the on bits for the characters rather than the entire text rectangle. This function only works if the foreground color is black and the background color is white. #### See Also WinDrawChar, WinDrawChars, WinDrawInvertedChars, WinDrawTruncChars, WinInvertChars, WinPaintChar, WinPaintChars ## WinEraseLine #### Purpose Draw a line in the draw window using the current background color. #### Prototype void WinEraseLine (Coord x1, Coord y1, Coord x2, Coord y2) #### Parameters #####
-> x1 | x coordinate of line start point.
#####
-> y1 | y coordinate of line start point.
#####
-> x2 | x coordinate of line endpoint.
#####
-> y2 | y coordinate of line endpoint.
#### Result Returns nothing. #### See Also WinDrawGrayLine, WinDrawLine, WinFillLine, WinInvertLine, WinPaintLine, WinPaintLines ## WinErasePixel #### Purpose Draw a pixel in the draw window using the current background color. #### Prototype void WinErasePixel (Coord x, Coord y) #### Parameters #####
-> x | Pointer to the x coordinate of a pixel.
#####
-> y | Pointer to the y coordinate of a pixel.
#### Result Returns nothing. #### Compatibility Implemented only if 3.5 New Feature Set is present. #### See Also WinDrawPixel, WinInvertPixel, WinPaintPixel, WinPaintPixels ## WinEraseRectangle #### Purpose Draw a rectangle in the draw window using the current background color. #### Prototype void WinEraseRectangle (const RectangleType *rP, UInt16 cornerDiam) #### Parameters #####
-> rP | Pointer to the rectangle to erase.
#####
-> cornerDiam | Radius of rounded corners. Specify zero for square corners.
#### Result Returns nothing. #### Comments The cornerDiam parameter specifies the radius of four imaginary circles used to form the rounded corners. An imaginary circle is placed within each corner tangent to the rectangle on two sides. #### See Also WinDrawRectangle, WinFillRectangle, WinInvertRectangle, WinPaintRectangle ## WinEraseRectangleFrame #### Purpose Draw a rectangular frame in the draw window using the current background color. #### Prototype void WinEraseRectangleFrame (FrameType frame, const RectangleType *rP) #### Parameters #####
-> frame | Type of frame to draw (see FrameType).
#####
-> rP | Pointer to the rectangle to frame.
#### Result Returns nothing. #### See Also WinDrawGrayRectangleFrame, WinDrawRectangleFrame, WinGetFramesRectangle, WinInvertRectangleFrame, WinPaintRectangleFrame ## WinEraseWindow #### Purpose Erase the contents of the draw window. #### Prototype void WinEraseWindow (void) #### Parameters #####
None.
#### Result Returns nothing. #### Comments WinEraseRectangle is used to erase the window. This routine doesn't erase the frame around the draw window. See WinEraseRectangleFrame and WinGetWindowFrameRect. ## WinFillLine #### Purpose Fill a line in the draw window with the current pattern. #### Prototype void WinFillLine (Coord x1, Coord y1, Coord x2, Coord y2) #### Parameters #####
-> x1 | x coordinate of line start point.
#####
-> y1 | y coordinate of line start point.
#####
-> x2 | x coordinate of line endpoint.
#####
-> y2 | y coordinate of line endpoint.
#### Result Returns nothing. #### Comments You can set the current pattern with WinSetPattern. #### See Also WinDrawGrayLine, WinDrawLine, WinEraseLine, WinInvertLine, WinPaintLine, WinPaintLines ## WinFillRectangle #### Purpose Draw a rectangle in the draw window with current pattern. #### Prototype void WinFillRectangle (const RectangleType *rP, UInt16 cornerDiam) #### Parameters #####
-> rP | Pointer to the rectangle to draw.
#####
-> cornerDiam | Radius of rounded corners. Specify zero for square corners.
#### Result Returns nothing. #### Comments You can set the current pattern with WinSetPattern. The cornerDiam parameter specifies the radius of four imaginary circles used to form the rounded corners. An imaginary circle is placed within each corner tangent to the rectangle on two sides. #### See Also WinDrawRectangle, WinEraseRectangle, WinInvertRectangle, WinPaintRectangle ## WinGetActiveWindow #### Purpose Return the window handle of the active window. #### Prototype WinHandle WinGetActiveWindow (void) #### Parameters #####
None.
#### Result Returns the handle of the active window. All user input is directed to the active window. #### See Also WinSetActiveWindow, WinGetDisplayWindow, WinGetFirstWindow, WinGetDrawWindow ## WinGetBitmap #### Purpose Return a pointer to a window's bitmap, which holds the window contents. #### Prototype BitmapType *WinGetBitmap (WinHandle winHandle) #### Parameters #####
-> winHandle | Handle of window from which to get the bitmap.
#### Result Returns a pointer to the bitmap or NULL if winHandle is invalid. #### Comments For onscreen windows, the bitmap returned always represents the whole screen. Thus, the top-left corner of the returned bitmap may not be the top-left corner of the window. #### Compatibility Implemented only if 3.5 New Feature Set is present. ## WinGetBounds #### Purpose Return the bounds of the current draw window in display-relative coordinates. #### Prototype void WinGetBounds (WinHandle winH, RectangleType *rP) #### Parameters #####
-> winH | Handle to a window.
#####
<- rP | Pointer to a rectangle.
#### Result Returns nothing. #### Comments This function returns in rP the bounds of the window represented by winH. This corresponds to the convention used by WinSetBounds, because it takes a window handle as an argument. Prior to Palm OS 4.0, WinGetBounds returned the bounds of the draw window, and did not take a window handle as an argument. If an application needed to determine the bounds of an arbitrary window, the application would call WinSetDrawWindow to temporarily set the draw window to the desired window, then WinGetBounds would be called to get the bounds of the draw window, then WinSetDrawWindow would be called again to restore the draw window. This is no longer necessary. #### Compatibility Implemented only if 4.0 New Feature Set is not present. As of Palm OS 4.0, applications should use WinGetDrawWindowBounds. #### See Also WinGetWindowExtent, WinGetDrawWindowBounds ## WinGetClip #### Purpose Return the clipping rectangle of the draw window. #### Prototype void WinGetClip (RectangleType *rP) #### Parameters #####
<- rP | Pointer to a structure to hold the clipping bounds.
#### Result Returns nothing. #### See Also WinSetClip ## WinGetDisplayExtent #### Purpose Return the width and height of the display (the screen). #### Prototype void WinGetDisplayExtent (Coord *extentX, Coord *extentY) #### Parameters #####
<- extentX | Pointer to the width of the display in pixels.
#####
<- extentY | Pointer to the height of the display in pixels.
#### Result Returns nothing. ## WinGetDisplayWindow #### Purpose Return the window handle of the display (screen) window. #### Prototype WinHandle WinGetDisplayWindow (void) #### Parameters None. #### Result Returns the handle of display window. #### Comments The display window is created by the system at start-up; it has the same size as the Palm OS drawable area of the physical display (screen). #### See Also WinGetDisplayExtent, WinGetActiveWindow, WinGetDrawWindow ## WinGetDrawWindow #### Purpose Return the window handle of the current draw window. #### Prototype WinHandle WinGetDrawWindow (void) #### Parameters None. #### Result Returns handle of draw window. #### See Also WinGetDisplayWindow, WinGetActiveWindow, WinSetDrawWindow ## New WinGetDrawWindowBounds #### Purpose Return the bounds of the draw window. #### Prototype void WinGetDrawWindowBounds (RectangleType *rP) #### Parameters <- rP Pointer to the window bounds. #### Result Returns nothing. #### Comments A pointer to the bounds of the draw window is returned. This function is equivalent to WinGetBounds that was in Palm OS prior to 4.0. #### See Also WinGetBounds ## WinGetFirstWindow #### Purpose Return a pointer to the first window in the linked list of windows. #### Prototype WinHandle WinGetFirstWindow (void) #### Parameters None. #### Result Returns handle of first window. #### Comments This function is usually used by the system only. #### See Also WinGetActiveWindow ## WinGetFramesRectangle #### Purpose Return the rectangle that includes a rectangle together with the specified frame around it. #### Prototype void WinGetFramesRectangle (FrameType frame, const RectangleType *rP, RectangleType *obscuredRect) #### Parameters #####
-> frame | Type of rectangle frame (see FrameType).
#####
-> rP | Pointer to the rectangle to frame.
#####
<- obscuredRect | Pointer to the rectangle that includes both the specified rectangle and its frame.
#### Result Returns nothing. #### Comments Frames are always drawn around (outside) a rectangle. #### See Also WinGetWindowFrameRect, WinGetBounds ## WinGetPattern #### Purpose Return the current fill pattern. #### Prototype void WinGetPattern (CustomPatternType *patternP) #### Parameters #####
<- patternP | Buffer where the current pattern is returned (see CustomPatternType).
#### Result Returns nothing. #### Comments The fill pattern is used by WinFillLine and WinFillRectangle. This function returns the value of patternData in the current drawing state. (See DrawStateType.) The patternData field is only set if the pattern field is customPattern. Therefore, it's a good idea to use WinGetPatternType instead of this function on systems that support WinGetPatternType. #### See Also WinSetPattern ## WinGetPatternType #### Purpose Return the current pattern type. #### Prototype PatternType WinGetPatternType (void) #### Parameters #####
None.
#### Result Returns the current draw window pattern type (see PatternType). If the return value is customPattern, you can retrieve the pattern with WinGetPattern. #### Comments The fill pattern is used by WinFillLine and WinFillRectangle. #### Compatibility Implemented only if 3.5 New Feature Set is present. #### See Also WinSetPatternType ## WinGetPixel #### Purpose Return the color value of a pixel in the current draw window. #### Prototype IndexedColorType WinGetPixel (Coord x, Coord y) #### Parameters #####
-> x | Pointer to the x coordinate of a pixel.
#####
-> y | Pointer to the y coordinate of a pixel.
#### Result Returns the indexed color value of the pixel. See IndexedColorType. A return value of 0 means either that the coordinates do not lie in the current draw window or that they do and the color of that pixel is index 0 (typically white). #### Compatibility Implemented only if 3.5 New Feature Set is present. #### See Also WinIndexToRGB ## New WinGetPixelRGB #### Purpose Return the RGB color values of a pixel in the current draw window. #### Prototype Err WinGetPixelRGB (Coord x, Coord y, RGBColorType *rgbP) #### Parameters #####
-> x | Pointer to the x coordinate of a pixel.
#####
-> y | Pointer to the y coordinate of a pixel.
#####
<- rgbP | RGB color components of the pixel.
#### Result Returns errNone or sysErrParamErr. sysErrParamErr is returned when the x or y arguments are < 0 or when they are outside the bounds of the draw window. #### Comments The RGB color values of the pixel are returned as an RGBColorType. This function can be used with both indexed or direct color modes. A return value of sysErrParamErr means that the coordinates do not lie in the current draw window. #### Compatibility Implemented only if 4.0 New Feature Set is present. ## WinGetWindowExtent #### Purpose Return the width and height of the current draw window. #### Prototype void WinGetWindowExtent (Coord *extentX, Coord *extentY) #### Parameters #####
<- extentX | Pointer to the width in pixels of the draw window.
#####
<- extentY | Pointer to the height in pixels of the draw window.
#### Result Returns nothing. #### See Also WinGetBounds, WinGetWindowFrameRect, ## WinGetWindowFrameRect #### Purpose Return a rectangle, in display-relative coordinates, that defines the size and location of a window and its frame. #### Prototype void WinGetWindowFrameRect (WinHandle winHandle, RectangleType *r) #### Parameters #####
-> winHandle | Handle of window whose coordinates are desired.
#####
<- r | Pointer to the coordinates of the window.
#### Result Returns nothing. #### See Also WinGetBounds ## WinIndexToRGB #### Purpose Convert an index in the currently active color table to an RGB value. #### Prototype void WinIndexToRGB (IndexedColorType i, RGBColorType *rgbP) #### Parameters #####
-> i | A color index value. See IndexedColorType.
#####
<- rgbP | Pointer to an RGB color value corresponding to the index value i. See RGBColorType.
#### Result Returns nothing. #### Compatibility Implemented only if 3.5 New Feature Set is present. #### See Also WinRGBToIndex ## WinInvertChars #### Purpose Invert the specified characters in the draw window. #### Prototype void WinInvertChars (const Char *chars, Int16 len, Coord x, Coord y) #### Parameters #####
-> chars | Pointer to the characters to invert.
#####
-> len | Length in bytes of the characters to invert.
#####
-> x | x coordinate of the first character to invert (left bound).
#####
-> y | y coordinate of the first character to invert (top bound).
#### Result Returns nothing. #### Comments This function applies the winInvert operation of WinDrawOperation to the characters in the draw window. To perform color inverting, use WinSetTextColor and WinSetBackColor to choose the desired colors, and call WinPaintChar. #### See Also WinDrawChar, WinDrawChars, WinDrawInvertedChars, WinDrawTruncChars, WinEraseChars, WinPaintChar, WinPaintChars ## WinInvertLine #### Purpose Invert a line in the draw window (using the WinDrawOperation winInvert). #### Prototype void WinInvertLine (Coord x1, Coord y1, Coord x2, Coord y2) #### Parameters #####
-> x1 | x coordinate of line start point.
#####
-> y1 | y coordinate of line start point.
#####
-> x2 | x coordinate of line endpoint.
#####
-> y2 | y coordinate of line endpoint.
#### Result Returns nothing. #### See Also WinDrawGrayLine, WinDrawLine, WinEraseLine, WinFillLine, WinPaintLine, WinPaintLines ## WinInvertPixel #### Purpose Invert a pixel in the draw window (using the WinDrawOperation winInvert). #### Prototype void WinInvertPixel (Coord x, Coord y) #### Parameters #####
-> x | Pointer to the x coordinate of a pixel.
#####
-> y | Pointer to the y coordinate of a pixel.
#### Result Returns nothing. #### Compatibility Implemented only if 3.5 New Feature Set is present. #### See Also WinDrawPixel, WinErasePixel, WinPaintPixel, WinPaintPixels ## WinInvertRectangle #### Purpose Invert a rectangle in the draw window (using the WinDrawOperation winInvert). #### Prototype void WinInvertRectangle (const RectangleType *rP, UInt16 cornerDiam) #### Parameters #####
-> rP | Pointer to the rectangle to invert.
#####
-> cornerDiam | Radius of rounded corners. Specify zero for square corners.
#### Result Returns nothing. #### Comments The cornerDiam parameter specifies the radius of four imaginary circles used to form the rounded corners. An imaginary circle is placed within each corner tangent to the rectangle on two sides. The operating system itself does not use the inverting routines. Instead, it uses the winSwap transfer mode, or it changes the color selection and uses the WinPaint... routines. #### See Also WinDrawRectangle, WinEraseRectangle, WinFillRectangle, WinPaintRectangle ## WinInvertRectangleFrame #### Purpose Invert a rectangular frame in the draw window (using the WinDrawOperation winInvert). #### Prototype void WinInvertRectangleFrame (FrameType frame, const RectangleType *rP) #### Parameters #####
-> frame | Type of frame to draw (see FrameType).
#####
-> rP | Pointer to the rectangle to frame.
#### Result Returns nothing. #### See Also WinDrawGrayRectangleFrame, WinDrawRectangleFrame, WinEraseRectangleFrame, WinGetFramesRectangle, WinPaintRectangleFrame ## WinModal #### Purpose Return true if the specified window is modal. #### Prototype Boolean WinModal (WinHandle winHandle) #### Parameters #####
-> winHandle | Handle of a window.
#### Result Returns true if the window is modal, otherwise false. #### Comments A window is modal if it cannot lose the focus. #### See Also FrmAlert, FrmCustomAlert, FrmDoDialog ## WinPaintBitmap #### Purpose Draw a bitmap in the current draw window at the specified coordinates with the current draw mode. #### Prototype void WinPaintBitmap (BitmapType *bitmapP, Coord x, Coord y) #### Parameters #####
-> bitmapP | Pointer to a bitmap.
#####
-> x | The x coordinate of the top-left corner.
#####
-> y | The y coordinate of the top-left corner.
#### Result Returns nothing. #### Comments If the bitmap has multiple depths (is a bitmap family), the closest match less than or equal to the current draw window depth is used. If such a bitmap does not exist, the bitmap with the closest match greater than the draw window depth is used. Using WinPaintBitmap is now recommended instead of the previous practice of rendering bitmaps into an offscreen window and then using WinCopyRectangle to draw them on screen. The current draw mode is set by WinSetDrawMode. If the bitmap has its own color table, color conversion to the draw window color table will be applied (on OS 3.5 or later). This color conversion is slow and not recommended. Instead of including a color table in the bitmap, consider using WinPalette to change the system color table, draw the bitmap, and then change the system color table back when the bitmap is no longer visible. #### Compatibility Implemented only if 3.5 New Feature Set is present. #### See Also WinDrawBitmap, WinEraseRectangle ## WinPaintChar #### Purpose Draw a character in the draw window using the current drawing state. #### Prototype void WinPaintChar (WChar theChar, Coord x, Coord y) #### Parameters #####
-> theChar | The character to draw. This may be either a single-byte character or a multi-byte character.
#####
-> x | x coordinate of the location where the character is to be drawn (left bound).
#####
-> y | y coordinate of the location where the character is to be drawn (top bound).
#### Result Returns nothing. #### See Also WinPaintChar draws the on bits in the text color and the off bits in the background color, with underlines (if any) drawn in the foreground color using the current drawing mode. This function uses the current drawing state, which is stored in a DrawStateType structure. See the description of that structure to learn the functions you can call to set the drawing state to the values you want. #### Compatibility Implemented only if 3.5 New Feature Set is present. #### See Also WinDrawChar, WinDrawChars, WinDrawInvertedChars, WinDrawTruncChars, WinEraseChars, WinInvertChars, WinPaintChars ## WinPaintChars #### Purpose Draw the specified characters in the draw window with the current draw state. #### Prototype void WinPaintChars (const Char *chars, Int16 len, Coord x, Coord y) #### Parameters #####
-> chars | Pointer to the characters to draw.
#####
-> len | Length in bytes of the characters to draw.
#####
-> x | x coordinate of the first character to draw (left bound).
#####
-> y | y coordinate of the first character to draw (top bound).
#### Result Returns nothing. #### Comments WinPaintChars draws the on bits in the text color and the off bits in the background color, with underlines (if any) drawn in the foreground color using the current drawing mode. This function uses the current drawing state, which is stored in a DrawStateType structure. See the description of that structure to learn the functions you can call to set the drawing state to the state you want. Before calling this function, consider calling WinSetUnderlineMode and FntSetFont. #### Compatibility Implemented only if 3.5 New Feature Set is present. #### See Also WinDrawChar, WinDrawChars, WinDrawInvertedChars, WinDrawTruncChars, WinEraseChars, WinInvertChars, WinPaintChar ## WinPaintLine #### Purpose Draw a line in the draw window using the current drawing state. #### Prototype void WinPaintLine (Coord x1, Coord y1, Coord x2, Coord y2) #### Parameters #####
-> x1 | x coordinate of line beginning point.
#####
-> y1 | y coordinate of line beginning point.
#####
-> x2 | x coordinate of line endpoint.
#####
-> y2 | y coordinate of line endpoint.
#### Result Returns nothing. #### Comments This function uses the current drawing state, which is stored in a DrawStateType structure. See the description of that structure to learn the functions you can call to set the drawing state to the state you want. #### Compatibility Implemented only if 3.5 New Feature Set is present. #### See Also WinDrawLine, WinDrawGrayLine, WinEraseLine, WinFillLine, WinInvertLine, WinPaintLines ## WinPaintLines #### Purpose Draw several lines in the draw window using the current drawing state. #### Prototype void WinPaintLines (UInt16 numLines, WinLineType lines[]) #### Parameters #####
-> numLines | Number of lines to paint.
#####
-> lines | Array of lines. See WinLineType.
#### Result Returns nothing. #### Comments This function uses the current drawing state, which is stored in a DrawStateType structure. See the description of that structure to learn the functions you can call to set the drawing state to the state you want. #### Compatibility Implemented only if 3.5 New Feature Set is present. #### See Also WinDrawLine, WinDrawGrayLine, WinEraseLine, WinFillLine, WinInvertLine, WinPaintLine ## WinPaintPixel #### Purpose Render a pixel in the draw window using the current drawing state. #### Purpose void WinPaintPixel (Coord x, Coord y) #### Parameters #####
-> x | Pointer to the x coordinate of a pixel.
#####
-> y | Pointer to the y coordinate of a pixel.
#### Result Returns nothing. #### Comments This function uses the current drawing state, which is stored in a DrawStateType structure. See the description of that structure to learn the functions you can call to set the drawing state to the state you want. #### Compatibility Implemented only if 3.5 New Feature Set is present. #### See Also WinDrawPixel, WinErasePixel, WinInvertPixel, WinPaintPixels ## WinPaintPixels #### Purpose Render several pixels in the draw window using the current drawing state. #### Prototype void WinPaintPixels (UInt16 numPoints, PointType pts[]) #### Parameters #####
-> numPoints | Number of pixels to paint.
#####
-> pts | Array of pixels.
#### Result Returns nothing. #### Comments This function uses the current drawing state, which is stored in a DrawStateType structure. See the description of that structure to learn the functions you can call to set the drawing state to the state you want. #### Compatibility Implemented only if 3.5 New Feature Set is present. #### See Also WinDrawPixel, WinErasePixel, WinInvertPixel, WinPaintPixel ## WinPaintRectangle #### Purpose Draw a rectangle in the draw window using the current drawing state. #### Prototype void WinPaintRectangle (const RectangleType *rP, UInt16 cornerDiam) #### Parameters #####
-> rP | Pointer to the rectangle to draw.
#####
-> cornerDiam | Radius of rounded corners. Specify zero for square corners.
#### Result Returns nothing. #### Comments The cornerDiam parameter specifies the radius of four imaginary circles used to form the rounded corners. An imaginary circle is placed within each corner tangent to the rectangle on two sides. This function uses the current drawing state, which is stored in a DrawStateType structure. See the description of that structure to learn the functions you can call to set the drawing state to the state you want. #### Compatibility Implemented only if 3.5 New Feature Set is present. #### See Also WinDrawRectangle, WinEraseRectangle, WinFillRectangle, WinInvertRectangle ## WinPaintRectangleFrame #### Purpose Draw a rectangular frame in the draw window using the current drawing state. #### Prototype void WinPaintRectangleFrame (FrameType frame, const RectangleType *rP) #### Parameters #####
-> frame | Type of frame to draw (see FrameType).
#####
-> rP | Pointer to the rectangle to frame.
#### Result Returns nothing. #### Comments The frame is drawn outside the specified rectangle. This function uses the current drawing state, which is stored in a DrawStateType structure. See the description of that structure to learn the functions you can call to set the drawing state to the state you want. #### Compatibility Implemented only if 3.5 New Feature Set is present. #### See Also WinDrawGrayRectangleFrame, WinDrawRectangleFrame, WinEraseRectangleFrame, WinGetFramesRectangle, WinInvertRectangleFrame ## WinPalette #### Purpose Set or retrieve the palette for the draw window. #### Prototype Err WinPalette (UInt8 operation, Int16 startIndex, UInt16 paletteEntries, RGBColorType *tableP) #### Parameters #####
-> operation | Specify one of the following values:
#####
winPaletteGet | Retrieve the palette. Entries are read from the palette beginning at startIndex and placed into tableP beginning at index 0.
#####
winPaletteSet | Set the palette. Entries from tableP (beginning at index 0) are set into the palette beginning at startIndex in the palette.
#####
winPaletteSetToDefault | Set the palette to the default system palette.
#####
-> startIndex | Identifies where in the palette to start reading or writing. Specify WinUseTableIndexes to indicate that the entries are not to be set or read sequentially; instead, the index value in each RGBColorType entry in tableP determines which slot in the palette is to be set or read. You can use this technique to get or set several discontiguous palette entries with a single function call.
#####
-> paletteEntries | Number of palette entries to get or set.
#####
<-> tableP | A pointer to a buffer of RGBColorType entries that is either read from or written to, depending on the operation parameter; the table entries from 0 to paletteEntries - 1 are affected by this routine.
#### Result Returns one of the following values: #####
errNone | Success.
#####
winErrPalette | The current draw window does not have a color table, a set operation has overflowed the color table, or one of the entries in tableP has an invalid index value
#####
sysErrParamErr | The startIndex value is invalid.
#### Comments Here are some examples of how this routine works: If startIndex is 0 and paletteEntries is 10, the first 10 elements of the palette will be set from tableP or will be copied into tableP. If startIndex is 10 and paletteEntries is 5, then entries 10, 11, 12, 13, and 14 in the palette will be set from or copied to elements 0, 1, 2, 3, and 4 in tableP. If startIndex is WinUseTableIndexes and paletteEntries is 1, then the index value in the RGBColorType of element 0 of tableP will be read from or copied to tableP; in this case, the index field of the RGBColorType will not change. During a set operation, this function broadcasts the sysNotifyDisplayChangeEvent to notify any interested observer that the color palette has changed. One use for this function is if you need to display a bitmap that uses a color table other than the one in use by the system. You can attach a custom color table to a bitmap, and if you do, the bitmap is drawn using that color table. However, this is a performance drain. As an optimization, you can use WinPalette to change the system color table to match that used by the bitmap, display the bitmap, and use WinPalette to reset the color table when the bitmap is no longer visible. #### Compatibility Implemented only if 3.5 New Feature Set is present. ## WinPopDrawState #### Purpose Restore the draw state values to the last saved set on the stack. #### Prototype void WinPopDrawState (void) #### Parameters #####
None.
#### Result Returns nothing. #### Comments Use this routine to restore the draw state saved by the previous call to WinPushDrawState. After you call this function, the current draw window's drawStateP field points to the restored drawing state. #### Compatibility Implemented only if 3.5 New Feature Set is present. ## WinPushDrawState #### Purpose Save the current draw state values onto the draw state stack. #### Prototype void WinPushDrawState (void) #### Parameters #####
None.
#### Result Returns nothing. #### Comments Use this routine to save the current draw state before making changes to it using the functions listed in the DrawStateType structure's description. Call WinPopDrawState to restore the saved settings. #### Compatibility Implemented only if 3.5 New Feature Set is present. ## WinResetClip #### Purpose Reset the clipping rectangle of the draw window to the portion of the draw window that is within the bounds of the display. #### Prototype void WinResetClip (void) #### Parameters #####
None.
#### Result Returns nothing. #### See Also WinSetClip ## WinRestoreBits #### Purpose Copy the contents of the specified window to the draw window and delete the passed window. #### Prototype void WinRestoreBits (WinHandle winHandle, Coord destX, Coord destY) #### Parameters #####
-> winHandle | Handle of window to copy and delete.
#####
-> destX | x coordinate in the draw window to copy to.
#####
-> destY | y coordinate in the draw window to copy to.
#### Result Returns nothing. #### Comments This routine is generally used to restore a region of the display that was saved with WinSaveBits. #### See Also WinSaveBits ## WinRGBToIndex #### Purpose Convert an RGB value to the index of the closest color in the currently active color lookup table (CLUT). #### Prototype IndexedColorType WinRGBToIndex (const RGBColorType *rgbP) #### Parameters #####
-> rgbP | Pointer to an RGB color value.
#### Result Returns the index of the closest matching color in the CLUT. #### Comments Palm OS 3.5 supports a maximum of 256 colors. The number of possible RGB colors greatly exceeds this amount. For this reason, an exact match may not be available for rgbP. If there is no exact RGB match, then a luminance best-fit is used if the color lookup table is entirely gray scale (red, green, and blue values for each entry are identical), or a shortest-distance fit in RGB space is used if the palette contains colors. RGB shortest distance may not always produce the actual closest perceptible color, but it's relatively fast and works for the system palette. WinRGBToIndex uses the draw window's color table to return the appropriate color table index. If the draw window does not have a color table, the default color table of the current screen is used. If the draw window does not have a color table, and if the depth of the draw window and the depth of the screen are different, this function will return an inappropriate index. If this situation exists, the application should either define a color table for the draw window, or use WinScreenMode to set the screen depth to the same depth as the draw window before calling WinRGBToIndex. NOTE: The bitmap data will not be blitted properly if the depth of the screen is changed using WinScreenMode and the new window uses a bitmap that does not define the bitmap's color table. See WinScreenMode for information on how to work around this limitation. #### Compatibility Implemented only if 3.5 New Feature Set is present. #### See Also WinIndexToRGB, WinScreenMode ## WinSaveBits #### Purpose Create an offscreen window and copy the specified region from the draw window to the offscreen window. #### Prototype WinHandle WinSaveBits (const RectangleType *source, UInt16 *error) #### Parameters #####
-> source | Pointer to the bounds of the region to save, relative to the display.
#####
<- error | Pointer to any error encountered by this function.
#### Result Returns the handle of the window containing the saved image, or zero if an error occurred. #### Comments The offscreen window is the same size as the region to copy. This function tries to copy the window's bitmap using compressed format if possible. It may display a fatal error message if an error occurs when it tries to shrink the pointer for the compressed bits. #### See Also WinRestoreBits ## WinScreenLock #### Purpose "Lock" the current screen by switching the UI concept of the screen base address to an area that is not reflected on the display. #### Prototype UInt8 *WinScreenLock (WinLockInitType initMode) #### Parameters #####
-> initMode | Indicates how to initialize the new screen area. Specify one of the following values:
#####
winLockCopy | Copy old screen to new.
#####
winLockErase | Erase new screen to white.
#####
winLockDontCare | Don't do anything
#### Result Returns a pointer to the new screen base address, or NULL if this routine fails. #### Comments This routine can be used to "freeze" the display while doing lengthy drawing operations to avoid a flickering effect. Call WinScreenUnlock to unlock the display and cause it to be updated with any changes. The screen must be unlocked as many times as it is locked to actually update the display. Because this function copies the screen, using it is a relatively expensive operation. #### Compatibility Implemented only if 3.5 New Feature Set is present. ## WinScreenMode #### Purpose Sets or returns display parameters, including display geometry, bit depth, and color support. #### Prototype Err WinScreenMode (WinScreenModeOperation operation, UInt32 *widthP, UInt32 *heightP, UInt32 *depthP, Boolean *enableColorP) #### Parameters The widthP, heightP, depthP, and enableColorP parameters are used in different ways for different operations. See Comments at the end of this description for details. #####
-> operation | The work this function is to perform, as specified by one of the following selectors:
#####
winScreenModeGet | Return the current settings for the display.
#####
winScreenModeGetDefaults | Return the default settings for the display.
#####
winScreenModeGetSupportedDepths | Return in depthP a hexadecimal value indicating the supported screen depths. The binary representation of this value defines a bitfield in which the value 1 indicates support for a particular display depth. The position representing a particular bit depth corresponds to the value 2(bitDepth-1). See the Example at the end of this function description for more information.
#####
winScreenModeGetSupportsColor | Return true as the value of the enableColorP parameter when color mode can be enabled.
#####
winScreenModeSet | Change display settings to the values specified by the other arguments to the WinScreenMode function.
#####
winScreenModeSetToDefaults | Change display settings to default values.
#####
<-> widthP | Pointer to new/old screen width.
#####
<-> heightP | Pointer to new/old screen height.
#####
<-> depthP | Pointer to new/old/available screen depth.
#####
<-> enableColorP | Pass true to enable color drawing mode.
#### Result If no error, returns values as specified by the operation argument. Various invalid arguments may cause this function to return a sysErrParamErr result code. In rare cases, a failed allocation can cause this function to return a memErrNotEnoughSpace error. #### Comments The widthP, heightP, depthP, and enableColorP parameters are used in different ways for different operations. All "get" operations overwrite these values with a result when the function returns. The winScreenModeSet operation changes current display parameters when passed valid argument values that are not NULL pointers. The winScreenModeSetToDefaults operation ignores values passed for all of these parameters. Table 55.1 summarizes parameter usage for each operation this function performs. #####
Table 55.1 Use of parameters to WinScreenMode function
Operation winScreenMode... | widthP | heightP | depthP | enableColorP
--- | --- | --- | --- | ---
...Get | returned | returned | returned | returned
...GetDefaults | returned | returned | returned | returned
...GetSupportedDepths | pass in | pass in | returned | pass in
...GetSupportsColor | pass in | pass in | pass in | returned
...Set | pass in | pass in | pass in | pass in
...SetToDefaults | ignored | ignored | ignored | ignored
This function ignores NULL pointer arguments to the widthP, heightP, depthP, and enableColorP parameters; thus, you can pass a NULL pointer for any of these values to leave the current value unchanged. Similarly, when getting values, this function does not return a value for any NULL pointer argument. If you change the display depth, it is recommended that you restore it to its previous state when your application closes, even though the system sets display parameters back to their default values when launching an application. Note that none of the other operations interprets the depth parameter the same way that winScreenModeGetSupportedDepths does. For example, to set the display depth to 8-bit mode, you use 8 (decimal) for the display depth, not 0x80 (128 decimal). When a window is created, and if the window's associated bitmap does not have its own color table, the window will use the system's default color translation tables when a blitting operation occurs to that window. When the system's bit depth changes, the system's default color translation tables are recalculated based on the new screen depth. When the blit occurs at the new screen depth to the offscreen window, the color translation tables are out of sync. To workaround this system limitation, developers should either: allocate offscreen windows after changing the depth, or use WinCreateBitmapWindow so that it uses a bitmap with a defined color table. The latter workaround causes the system to perform color matching when blitting, so the first workaround may be preferred. #### Compatibility Implemented only if 3.5 New Feature Set is present. In OS versions prior to 3.5, this function is called ScrDisplayMode. The prototype for ScrDisplayMode is similar to WinScreenMode:
    Err ScrDisplayMode ( ScrDisplayModeOperation operation,
    DWordPtr widthP, DWordPtr heightP,
    DWordPtr depthP, BooleanPtr enableColorP)
The only other difference between ScrDisplayMode and WinScreenMode is that the ScrDisplayModeOperation constants begin with the prefix scrDisplayMode rather than winScreenMode. #### Example Here are some additional examples of return values provided by the winScreenModeGetSupportedDepths mode of the WinScreenMode function. This function indicates support for 4-bit drawing by returning a value of 0x08, or 23, which corresponds to a binary value of 1000. Support for bit depths of 2 and 1 is indicated by a return value of 0x03. Support for bit depths of 4, 2, and 1 is indicated by 0x0B, which is a binary value of 1011. Support for bit depths of 16, 8, 4 and 2 is indicated by 0x808A. The figure immediately following depicts this final example graphically. ## WinScreenUnlock #### Purpose Unlock the screen and update the display. #### Prototype void WinScreenUnlock (void) #### Parameters #####
None.
#### Result Returns nothing. #### Comments The screen must be unlocked as many times as it is locked to actually update the display. #### Compatibility Implemented only if 3.5 New Feature Set is present. #### See Also WinScreenLock ## WinScrollRectangle #### Purpose Scroll a rectangle in the draw window. #### Prototype void WinScrollRectangle (const RectangleType *rP, WinDirectionType direction, Coord distance, RectangleType *vacatedP) #### Parameters #####
-> rP | Pointer to the rectangle to scroll.
#####
-> direction | Direction to scroll (winUp, winDown, winLeft, or winRight).
#####
-> distance | Distance to scroll in pixels.
#####
<- vacatedP | Pointer to the rectangle that needs to be redrawn because it has been vacated as a result of the scroll.
#### Result Returns nothing. #### Comments The rectangle scrolls within its own bounds. Any portion of the rectangle that is scrolled outside its bounds is clipped. ## WinSetActiveWindow #### Purpose Make a window the active window. #### Prototype void WinSetActiveWindow (WinHandle winHandle) #### Parameters #####
-> winHandle | Handle of a window.
#### Result Returns nothing. #### Comments The active window is not actually set in this routine; flags are set to indicate that a window is being exited and another window is being entered. The routine EvtGetEvent sends a winExitEvent and a winEnterEvent when it detects these flags. The active window is set by EvtGetEvent when it sends the winEnterEvent. The draw window is also set to the new active window when the active window is changed. The window is enabled before it is made active. All user input is directed to the active window. #### See Also WinGetActiveWindow, EvtGetEvent ## WinSetBackColor #### Purpose Set the background color to use in subsequent draw operations. #### Prototype IndexedColorType WinSetBackColor (IndexedColorType backColor) #### Parameters #####
-> backColor | Color to set; specify a value of type IndexedColorType.
#### Result Returns the previous background color index. #### Comments This function changes the current drawing state. If necessary, use WinPushDrawState to preserve the current drawing state before you set this function and use WinPopDrawState to restore it later. To set the foreground color to a predefined UI color default, use UIColorGetTableEntryIndex as an input to this function. For example:
    curColor = WinSetBackColor
    (UIColorGetTableEntryIndex(UIFieldBackground));
#### Compatibility Implemented only if 3.5 New Feature Set is present. #### See Also WinSetForeColor, WinSetTextColor ## New WinSetBackColorRGB #### Purpose Set the background color to use in subsequent draw operations. #### Prototype void WinSetBackColorRGB (const RGBColorType *newRgbP, RGBColorType *prevRgbP) #### Parameters #####
-> newRgbP | Color to set; specify a value of type RGBColorType.
#####
<- prevRgbP | Previous color; specify a value of type RGBColorType.
#### Result Returns nothing #### Comments This function takes new and previous RGBColorType arguments. It is okay to set newRgbP or prevRgbP to NULL. If an application only wants to get the current color, the newRgbP argument is set to NULL. If the application does not care about the previous color, prevRgbP can be set to NULL. This function sets the backColorRGB field of the DrawStateType structure to the value specified by newRgbP. It then sets the index field of newRgbP to the 8 bit system palette entry that most closely matches the RGB components. Finally, it sets the backColor index field of DrawStateType to this index value. This function changes the current drawing state. If necessary, use WinPushDrawState to preserve the current drawing state before you set this function and use WinPopDrawState to restore it later. #### Compatibility Implemented only if 4.0 New Feature Set is present. #### See Also WinSetForeColorRGB, WinSetTextColorRGB ## WinSetBounds #### Purpose Set the bounds of the window to display-relative coordinates. #### Prototype void WinSetBounds (WinHandle winHandle, const RectangleType *rP) #### Parameters #####
-> winHandle | Handle for the window for which to set the bounds.
#####
-> rP | Pointer to a rectangle to use for bounds.
#### Result #####
Returns nothing.
#### Comments A visible window cannot have its bounds modified. #### Compatibility Implemented only if 2.0 New Feature Set is present. #### See Also WinGetBounds ## WinSetClip #### Purpose Set the clipping rectangle of the draw window. #### Prototype void WinSetClip (const RectangleType *rP) #### Parameters #####
-> rP | Pointer to a structure holding the clipping bounds.
#### Result Returns nothing. #### See Also WinClipRectangle, WinSetClip, WinGetClip ## WinSetDrawMode #### Purpose Set the transfer mode to use in subsequent draw operations. #### Prototype WinDrawOperation WinSetDrawMode (WinDrawOperation newMode) #### Parameters #####
-> newMode | Transfer mode to set; specify one of the WinDrawOperation values.
#### Result Returns the previous transfer mode. #### Comments This function changes the current drawing state. If necessary, use WinPushDrawState to preserve the current drawing state before you set this function and use WinPopDrawState to restore it later. #### Compatibility Implemented only if 3.5 New Feature Set is present. ## WinSetDrawWindow #### Purpose Set the draw window. (All drawing operations are relative to the draw window.) #### Prototype WinHandle WinSetDrawWindow (WinHandle winHandle) #### Parameters #####
-> winHandle | Handle of a window.
#### Result Returns the previous draw window. #### Compatibility OS versions before 3.5 allowed you to use NULL as a parameter to this function to set the draw window to the display window (or screen window). In version 3.5 and higher, this practice is discouraged. If winHandle is NULL, the debug ROM sets the draw window to badDrawWindowValue, and you are warned if you try to draw to it. #### See Also WinGetDrawWindow, WinSetActiveWindow ## WinSetForeColor #### Purpose Set the foreground color to use in subsequent draw operations. #### Prototype IndexedColorType WinSetForeColor (IndexedColorType foreColor) #### Parameters #####
-> foreColor | Color to set; specify a value of type IndexedColorType.
#### Result Returns the previous foreground color index. #### Comments This function changes the current drawing state. If necessary, use WinPushDrawState to preserve the current drawing state before you set this function and use WinPopDrawState to restore it later. To set the foreground color to a predefined UI color default, use UIColorGetTableEntryIndex as an input to this function. For example:
    curColor = WinSetForeColor
      (UIColorGetTableEntryIndex
      (UIObjectForeground));
#### Compatibility Implemented only if 3.5 New Feature Set is present. #### See Also WinSetBackColor, WinSetTextColor ## New WinSetForeColorRGB #### Purpose Set the foreground color to use in subsequent draw operations. #### Prototype void WinSetForeColorRGB (const RGBColorType *newRgbP, RGBColorType *prevRgbP) #### Parameters #####
-> newRgbP | Color to set; specify a value of type RGBColorType.
#####
<- prevRgbP | Previous color; specify a value of type RGBColorType.
#### Result Returns nothing. #### Comments This function takes new and previous RGBColorType arguments. It is okay to set newRgbP or prevRgbP to NULL. If an application only wants to get the current color, the newRgbP argument is set to NULL. If the application does not care about the previous color, prevRgbP can be set to NULL. This function sets the foreColorRGB field of the DrawStateType structure to the value specified by newRgbP. It then sets the index field of newRgbP to the 8 bit system palette entry that most closely matches the RGB components. Finally, it sets the foreColor index field of DrawStateType to this index value. This function changes the current drawing state. If necessary, use WinPushDrawState to preserve the current drawing state before you set this function and use WinPopDrawState to restore it later. #### Compatibility Implemented only if 4.0 New Feature Set is present. #### See Also WinSetBackColorRGB, WinSetTextColorRGB ## WinSetPattern #### Purpose Set the current fill pattern. #### Prototype void WinSetPattern (const CustomPatternType *patternP) #### Parameters #####
-> patternP | Pattern to set (see CustomPatternType).
#### Result Returns nothing. #### Comments The fill pattern is used by WinFillLine and WinFillRectangle. This function changes the current drawing state. If necessary, use WinPushDrawState to preserve the current drawing state before you set this function and use WinPopDrawState to restore it later. #### See Also WinGetPattern ## WinSetPatternType #### Purpose Set the current pattern type. #### Prototype void WinSetPatternType (PatternType newPattern) #### Parameters #####
-> newPattern | Pattern type to set for the draw window (see PatternType).
#### Result Returns nothing. #### Comments This function sets the pattern field of the drawing state to newPattern and sets the patternData field to NULL. To set patternData to a custom pattern use WinSetPattern. The fill pattern is used by WinFillLine and WinFillRectangle. This function changes the current drawing state. If necessary, use WinPushDrawState to preserve the current drawing state before you set this function and use WinPopDrawState to restore it later. #### Compatibility Implemented only if 3.5 New Feature Set is present. #### See Also WinGetPatternType ## WinSetTextColor #### Purpose Set the color to use for drawing characters in subsequent draw operations. #### Prototype IndexedColorType WinSetTextColor (IndexedColorType textColor) #### Parameters #####
-> textColor | Color to set; specify a value of type IndexedColorType.
#### Result Returns the previous text color index. #### Comments This function changes the current drawing state. If necessary, use WinPushDrawState to preserve the current drawing state before you set this function and use WinPopDrawState to restore it later. To set the foreground color to a predefined UI color default, use UIColorGetTableEntryIndex as an input to this function. For example:
    curColor = WinSetTextColor
      (UIColorGetTableEntryIndex(UIFieldText));
#### Compatibility Implemented only if 3.5 New Feature Set is present. #### See Also WinSetBackColor, WinSetForeColor ## New WinSetTextColorRGB #### Purpose Set the color to use for drawing characters in subsequent draw operations. #### Prototype void WinSetTextColorRGB (const RGBColorType *newRgbP, RGBColorType *prevRgbP) #### Parameters #####
-> newRgbP | Color to set; specify a value of type RGBColorType.
#####
<- prevRgbP | Previous color; specify a value of type RGBColorType.
#### Result Returns nothing. #### Comments This function takes new and previous RGBColorType arguments. It is okay to set newRgbP or prevRgbP to NULL. If an application only wants to get the current color, the newRgbP argument is set to NULL. If the application does not care about the previous color, prevRgbP can be set to NULL. This function sets the textColorRGB field of the DrawStateType structure to the value specified by newRgbP. It then sets the index field of newRgbP to the 8 bit system palette entry that most closely matches the RGB components. Finally, it sets the textColor index field of DrawStateType to this index value. This function changes the current drawing state. If necessary, use WinPushDrawState to preserve the current drawing state before you set this function and use WinPopDrawState to restore it later. #### Compatibility Implemented only if 4.0 New Feature Set is present. #### See Also WinSetBackColorRGB, WinSetForeColorRGB ## WinSetUnderlineMode #### Purpose Set the graphic state to enable or disable the underlining of characters. #### Prototype UnderlineModeType WinSetUnderlineMode (UnderlineModeType mode) #### Parameters #####
<-> mode | New underline mode type; see UnderlineModeType.
#### Result Returns the previous underline mode type. #### Comments This function changes the current drawing state. If necessary, use WinPushDrawState to preserve the current drawing state before you set this function and use WinPopDrawState to restore it later. #### See Also WinDrawChars ## WinValidateHandle #### Purpose Return true if the specified handle references a valid window object. #### Prototype Boolean WinValidateHandle (WinHandle winHandle) #### Parameters #####
-> winHandle | The handle to be tested.
#### Result Returns true if the specified handle references a non-NULL pointer to a window in the active window list, false if the handle references a window whose values are out of sync with the current system state. #### Comments For debugging purposes only. Do not include this function in commercial applications. #### Compatibility Implemented only if 3.0 New Feature Set is present. #### See Also FrmValidatePtr, FrmRemoveObject ## WinWindowToDisplayPt #### Purpose Convert a window-relative coordinate to a display-relative coordinate. #### Prototype void WinWindowToDisplayPt (Coord *extentX, Coord *extentY) #### Parameters #####
<-> extentX | Pointer to x coordinate to convert.
#####
<-> extentY | Pointer to y coordinate to convert.
#### Result Returns nothing. #### Comments The coordinate passed is assumed to be relative to the draw window. #### See Also WinDisplayToWindowPt |