This chapter provides information about windows by discussing these topics:
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 "Drawing on the Palm Powered Handheld" in the Palm OS Programmer's Companion, vol. I.
Window Data Structures
CustomPatternType Typedef
Purpose
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.
Prototype
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.
DrawStateFlagsType Struct
Purpose
The DrawStateFlagsType structure defines a set of flags that control how bitmaps and text are scaled. Use WinSetScalingMode()
to set these flags, and WinGetScalingMode()
to obtain the values of these flags.
WARNING! PalmSource, Inc. does not support or provide backward compatibility for the
DrawStateFlagsType
structure. Never access its structure members directly, or your code may break in future versions. Use the information below for debugging purposes only.
Prototype
typedef struct DrawStateFlagsType { UInt16 unscaledBitmaps:1; UInt16 unscaledText:1; UInt16 unpaddedText:1; UInt16 reserved:13; } DrawStateFlagsType;
Fields
-
unscaledBitmaps
- If set, low-density bitmaps are used, unscaled.
-
unscaledText
- If set, low density fonts are used, unscaled.
-
unpaddedText
- If set, padding pixels aren't inserted between text glyphs.
-
reserved
- Reserved for future use.
Compatibility
Defined only if the 1.5x Display Feature Set is present.
DrawStateType Struct
Purpose
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! PalmSource, Inc. does not support or provide backward compatibility for the
DrawStateType
structure. Never access its structure members directly, or your code may break in future versions. Use the information below for debugging purposes only.
Prototype
typedef struct DrawStateType { WinDrawOperation transferMode; PatternType pattern; UnderlineModeType underlineMode; FontID fontId; FontPtr font; CustomPatternType patternData; IndexedColorType foreColor; IndexedColorType backColor; IndexedColorType textColor; UInt8 reserved; RGBColorType foreColorRGB; RGBColorType backColorRGB; RGBColorType textColorRGB; UInt16 coordinateSystem; DrawStateFlagsType flags; Fixed16 scale; Fixed16 ntvToActiveScale; Fixed16 stdToActiveScale; Fixed16 activeToStdScale; } DrawStateType;
Fields
-
transferMode
- The current transfer mode for color drawing. See
WinDrawOperation
. UseWinSetDrawMode()
to set this value. -
pattern
- The name of the current pattern. See
PatternType
. If set tocustomPattern
, thepatternData
field contains the actual pattern. UseWinGetPatternType()
andWinSetPatternType()
to retrieve and set this value. -
underlineMode
- The current underline mode. See
UnderlineModeType
. UseWinSetUnderlineMode()
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 ifpattern
iscustomPattern
. SeeCustomPatternType
. UseWinGetPattern()
andWinSetPattern()
to retrieve and set this value. -
foreColor
- Index of the current color used for the foreground. Use
WinSetForeColor()
to set this value. This field is only valid for indexed color bitmaps. -
backColor
- Index of the current color used for the background. Use
WinSetBackColor()
to set this value. This field is only valid for indexed color bitmaps. -
textColor
- Index of the current color used for text. Use
WinSetTextColor()
to set this value. This field is only valid for indexed color bitmaps. -
reserved
- Reserved for future use.
-
foreColorRGB
- RGB value of the current color used for the foreground. Use
WinSetForeColorRGB()
to set this value. This field is only valid for Palm OS 4.0 or later, and only valid for direct color bitmaps. -
backColorRGB
- RGB value of the current color used for the background. Use
WinSetBackColorRGB()
to set this value. This field is only valid for Palm OS 4.0 or later, and only valid for direct color bitmaps. -
textColorRGB
- RGB value of the current color used for text. Use
WinSetTextColorRGB()
to set this value. This field is only valid for Palm OS 4.0 or later, and only valid for direct color bitmaps. -
coordinateSystem
- Active coordinate system.
-
flags
- A
DrawStateFlagsType
structure, the contents of which control the scaling of bitmaps and text. -
scale
- A fixed point value used to convert from the draw window's active coordinate system to native coordinates. This field is defined only if the High-Density Display Feature Set is present.
-
ntvToActiveScale
- A fixed point value used to convert from the native coordinate system to the draw window's active coordinate system. This field is defined only if the High-Density Display Feature Set is present.
-
stdToActiveScale
- A fixed point value used to convert from the standard coordinate system to the draw window's active coordinate system. This field is used internally to convert font metrics, which are stored as standard coordinates. This field is defined only if the High-Density Display Feature Set is present.
-
activeToStdScale
- The inverse of
stdToActive
; the active-to-standard scaling factor. This field is defined only if the High-Density Display Feature Set is present.
Compatibility
This type is implemented only if 3.5 New Feature Set is present. The scale
, ntvToActiveScale
, stdToActiveScale
, and activeToStdScale
fields are defined only if the High-Density Display Feature Set is present. The flags
field is defined only if the 1.5x Display Feature Set is present; otherwise, the contents of flags
are reserved.
FrameBitsType Struct
Purpose
The FrameBitsType
structure specifies attributes of a window's frame.
WARNING! PalmSource, 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.
Prototype
typedef union FrameBitsType { struct { UInt16 cornerDiam : 8; UInt16 reserved_3 : 3; UInt16 threeD : 1; UInt16 shadowWidth : 2; UInt16 width : 2; } bits; UInt16 word; } FrameBitsType;
Fields
-
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 Typedef
Purpose
The FrameType
type specifies a window frame style.
Prototype
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.
Popup frame style with slight corner roundness, width of 1 and shadow of 1. |
||
Dialog frame style with slight corner roundness and width of 2. |
||
IndexedColorType Typedef
Purpose
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.
Prototype
typedef UInt8 IndexedColorType;
Compatibility
This type is implemented only if 3.5 New Feature Set is present.
PatternType Enum
Purpose
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.
Prototype
typedef enum { blackPattern, whitePattern, grayPattern, customPattern, lightGrayPattern, darkGrayPattern } PatternType;
Constants
-
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
. -
lightGrayPattern
- Pattern with one out of four bits in each row turned on. This value is defined only if the High-Density Display Feature Set is present.
-
darkGrayPattern
- Pattern with one out of four bits in each row turned off. This value is defined only if the High-Density Display Feature Set is present.
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.
Patterns are expanded to the destination bit depth by the blitter when drawing patterned lines and filled rectangles.
The three standard gray patterns—grayPattern
, lightGrayPattern
, and darkGrayPattern
—are always drawn by the blitter using the screen density to improve the appearance of gray fills. Custom patterns, however, are stretched as appropriate by the blitter based on the destination density.
Compatibility
The lightGrayPattern
and darkGrayPattern
values are defined only if the High-Density Display Feature Set is present.
UnderlineModeType Enum
Purpose
The UnderlineModeType
enumerated type specifies possible values for the underline mode stored in DrawStateType
.
Prototype
typedef enum { noUnderline, grayUnderline, solidUnderline, colorUnderline } UnderlineModeType;
Constants
-
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 Struct
Purpose
The WindowFlagsType
specifies different window attributes.
WARNING! PalmSource, 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.
Prototype
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;
Fields
-
format
- If set, use the
genericFormat
. If 0, usescreenFormat
. - 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
.
WindowFormatType Enum
Purpose
Use this enumeration to specify the window format when creating an offscreen window with the WinCreateOffscreenWindow()
function.
Prototype
typedef enum { screenFormat = 0, genericFormat, nativeFormat } WindowFormatType;
Constants
-
screenFormat
- The window's bitmap is allocated using the hardware screen's depth, but for backward compatibility the bitmap associated with the offscreen window is always low density, and the window always uses a coordinate system that directly maps offscreen pixels to coordinates.
-
genericFormat
- Like
screenFormat
, except thatgenericFormat
offscreen windows do not accept pen input. -
nativeFormat
- Reflects the actual hardware screen format in all ways, including screen depth, density, and pixel format. Applications must always use the graphic API when drawing to a
nativeFormat
offscreen window: directly accessing offscreen pixels will produce undefined results. When using this format, the width and height arguments must be specified using the active coordinate system. LikegenericFormat
,nativeFormat
offscreen windows do not accept pen input.
Compatibility
WindowFormatType
is defined only if the High-Density Display Feature Set is present.
WindowType Struct
Purpose
The WindowType
structure represents a window.
WARNING! PalmSource, 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.
Prototype
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;
Fields
-
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 thenBmpGetBits()
to obtain the window's memory buffer. - 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()
andWinSetBounds()
to retrieve and set this value. -
clippingBounds
- Bounds for clipping any drawing within the window. Use
WinGetClip()
andWinSetClip()
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 Enum
Purpose
The WinDrawOperation
enumerated type specifies the transfer mode for color drawing. This type is used as a parameter to the WinCopyRectangle()
and WinSetDrawMode()
functions.
Prototype
typedef enum {winPaint, winErase, winMask, winInvert, winOverlay, winPaintInverse, winSwap} WinDrawOperation;
Constants
-
winPaint
- Write color-matched source pixels to the destination. If a bitmap's
hasTransparency
flag is set,winPaint
behaves likewinOverlay
instead. -
winErase
- Write
backColor
if the source pixel is transparent. -
winMask
- Write
backColor
if the source pixel is not transparent. -
winInvert
- Bitwise XOR the color-matched source pixel onto the destination. This mode does not honor the transparent color in any way.
-
winOverlay
- Write color-matched source pixel to the destination if the source pixel is not transparent. Transparent pixels are skipped. For a 1-bit display, the "off" bits are considered to be the transparent color. Note that this definition of
winOverlay
is new for Palm OS Garnet; in Palm OS 4.x, the destination is set (only) where the source pixels are "on." -
winPaintInverse
- Invert the source pixel color and then proceed as with
winPaint
. -
winSwap
- Swap the
backColor
andforeColor
destination colors if the source is a pattern (the type of pattern is disregarded). If the source is a bitmap, then the bitmap is transferred usingwinPaint
mode instead.
Note that 2-bit, 4-bit, and 8-bit source bitmaps that don't have a color table inherit the system default color table for their given depth. 1-bit sources (bitmap, text, and patterns) that don't have a color table are given a color table where entry 0 is the backColor
and entry 1 is the foreColor
(textColor
for text).
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.
The Transparent Color
As of Palm OS 4.0, bitmaps have a hasTransparency
flag and may designate a transparent color. These concepts are augmented somewhat in Palm OS Garnet to make the transfer modes more consistent:
- Bitmaps that don't specify any transparent color (text, patterns, and version 0 bitmaps) are assumed to have a transparent color of index 0 and the
hasTransparency
bit is assumed to befalse
. - When the
hasTransparency
flag is set and the transfer mode iswinPaint
, only the non-transparent pixels are copied to the destination. With text and patterns, the Palm OS assumes that the "off" bits are the ones designated as transparent and acts as if thehasTransparency
flag is always false. This assumption retains backwards compatibility and unifies the use of transparency across all source data.
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
. Transparency is only available if 4.0 New Feature Set is present, and as mentioned in "The Transparent Color" the behavior of the window drawing modes—winOverlay
in particular—changes slightly if 5.0 New Feature Set is present.
WinHandle Typedef
Purpose
The WinHandle
type is a pointer to a WindowType
structure. Note that this may change.
Prototype
typedef WindowType *WinHandle;
WinLineType Struct
Purpose
The WinLineType
structure defines a line.
Prototype
typedef struct WinLineType { Coord x1; Coord y1; Coord x2; Coord y2; } WinLineType;
Fields
-
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 Typedef
Purpose
The WinPtr
type is a pointer to a WindowType
structure.
Prototype
typedef WindowType *WinPtr;
Window Constants
If the 5.0 New Feature Set or the High-Density Display Feature Set are present, the following constants are defined:
Window Coordinate System Constants
These constants specify the coordinate system to be used when drawing within a given window:
IMPORTANT: Not all coordinate systems listed in the above table are supported in this version of the High-Density Display Feature Set. For Palm OS Garnet, only
kCoordinatesNative
, kCoordinatesStandard
, and kCoordinatesDouble
are supported.
Pass one of these constants as an argument to WinSetCoordinateSystem()
. These values are returned by WinGetCoordinateSystem()
.
Compatibility
Defined only if the High-Density Display Feature Set is present.
Window Functions
WinClipRectangle Function
Purpose
Shrink the rectangle to make it fit within the clipping region of the current draw window.
Declared In
Window.h
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.
Returns
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 Function
Purpose
Copy a rectangular region from one place to another (either between windows or within a single window).
Declared In
Window.h
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
- Left bound of the rectangle in destination window.
-
→
destY
- Top bound of the rectangle in destination window.
-
→
mode
- The method of transfer from the source to the destination window (see
WinDrawOperation
).
Returns
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
WinCreateBitmapWindow Function
Purpose
Create a new offscreen window.
Declared In
Window.h
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.
Returns
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 Function
Purpose
Create a new offscreen window and add it to the window list.
Declared In
Window.h
Prototype
WinHandle WinCreateOffscreenWindow ( Coord width, Coord height, WindowFormatType format, UInt16 *error )
Parameters
-
→
width
- Width of the window in pixels. The coordinate system you use for this parameter depends upon the value of
format
. -
→
height
- Height of the window in pixels. The coordinate system you use for this parameter depends upon the value of
format
. -
→
format
- One of the window formats defined by
WindowFormatType
. -
←
error
- Pointer to any error this function encounters.
Returns
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
orheight
parameter isNULL
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 usesgenericFormat
for the format argument. - When you delete the window created with
WinCreateOffscreenWindow
, its bitmap is freed along with the window. The bitmap used in theWinCreateBitmapWindow
is not freed when the window is freed.
Note that if you aren't directly accessing the bits of an offscreen window's bitmap but are just using the APIs, you can always pass nativeFormat
for the screen format even on pre-Palm OS Garnet handhelds and things will work as expected. If you need direct access to the bits of the offscreen window's bitmap, however, call BmpCreate()
and then call WinCreateBitmapWindow
. Because you created the bitmap, you know its format and thus can safely manipulate its bits. Calling WinCreateOffscreenWindow
with a format
argument of nativeFormat
can result in a bitmap with an unexpected format: the endianness, number of bits per pixel, and so on would match the screen and therefore be fastest to draw, but your application wouldn't be able to manipulate the pixels directly.
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 Function
Purpose
Create a new window and add it to the window list.
Declared In
Window.h
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.
Returns
Returns the handle of the new window upon success, or NULL
if an error occurs. The error
parameter contains one of the following:
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 Function
Purpose
Remove a window from the window list and free the memory used by the window.
Declared In
Window.h
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. Iffalse
, the window is not erased.
Returns
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 Function
Purpose
Convert a display-relative coordinate to a window-relative coordinate. The coordinate returned is relative to the display window.
Declared In
Window.h
Prototype
void WinDisplayToWindowPt ( Coord *extentX, Coord *extentY )
Parameters
Returns
See Also
WinDrawBitmap Function
Purpose
Draw a bitmap at the given coordinates in winPaint
mode (see WinDrawOperation
for mode details).
Declared In
Window.h
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.
Returns
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
WinDrawChar Function
Purpose
Draw the specified character in the draw window.
Declared In
Window.h
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).
Returns
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 80, "PalmOSGlue Library."
NOTE: Though this function is new in the 3.1 New Feature Set, due to a bug in the 3.1 implementation, when running on Palm OS 3.1 you must link with the PalmOSGlue library and call
WinGlueDrawChar
, rather than calling WinDrawChar
.
See Also
WinDrawChars()
, WinDrawInvertedChars()
, WinDrawTruncChars()
, WinEraseChars()
, WinInvertChars()
, WinPaintChars()
WinDrawChars Function
Purpose
Draw the specified characters in the draw window.
Declared In
Window.h
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).
Returns
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 Function
Purpose
Draw a dashed line in the draw window.
Declared In
Window.h
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.
Returns
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 Function
Purpose
Draw a gray rectangular frame in the draw window.
Declared In
Window.h
Prototype
void WinDrawGrayRectangleFrame ( FrameType frame, const RectangleType *rP )
Parameters
-
→
frame
- Type of frame to draw (see
FrameType
). -
→
rP
- Pointer to the rectangle to frame.
Returns
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 Function
Purpose
Draw the specified characters inverted (background color) in the draw window.
Declared In
Window.h
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).
Returns
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 Function
Purpose
Draw a line in the draw window using the current foreground color.
Declared In
Window.h
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.
Returns
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 Function
Purpose
Draw a pixel in the draw window using the current foreground color.
Declared In
Window.h
Prototype
void WinDrawPixel ( Coord x, Coord y )
Parameters
Returns
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 Function
Purpose
Draw a rectangle in the draw window using the current foreground color.
Declared In
Window.h
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.
Returns
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 Function
Purpose
Draw a rectangular frame in the draw window using the current foreground color.
Declared In
Window.h
Prototype
void WinDrawRectangleFrame ( FrameType frame, const RectangleType *rP )
Parameters
-
→
frame
- Type of frame to draw (see
FrameType
). -
→
rP
- Pointer to the rectangle to frame.
Returns
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 Function
Purpose
Draw the specified characters in the draw window, truncating the characters to the specified width.
Declared In
Window.h
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.
Returns
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 80, "PalmOSGlue Library."
NOTE: Though this function is new in the 3.1 New Feature Set, due to a bug in the 3.1 implementation, when running on Palm OS 3.1 you must link with the PalmOSGlue library and call
WinGlueDrawTruncChars
, rather than calling WinDrawTruncChars
.
See Also
WinDrawChar()
, WinDrawChars()
, WinDrawInvertedChars()
, WinEraseChars()
, WinInvertChars()
, WinPaintChar()
, WinPaintChars()
WinEraseChars Function
Purpose
Erase the specified characters in the draw window.
Declared In
Window.h
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).
Returns
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 Function
Purpose
Draw a line in the draw window using the current background color.
Declared In
Window.h
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.
Returns
See Also
WinDrawGrayLine()
, WinDrawLine()
, WinFillLine()
, WinInvertLine()
, WinPaintLine()
, WinPaintLines()
WinErasePixel Function
Purpose
Draw a pixel in the draw window using the current background color.
Declared In
Window.h
Prototype
void WinErasePixel ( Coord x, Coord y )
Parameters
Returns
Compatibility
Implemented only if 3.5 New Feature Set is present.
See Also
WinDrawPixel()
, WinInvertPixel()
, WinPaintPixel()
, WinPaintPixels()
WinEraseRectangle Function
Purpose
Draw a rectangle in the draw window using the current background color.
Declared In
Window.h
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.
Returns
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 Function
Purpose
Draw a rectangular frame in the draw window using the current background color.
Declared In
Window.h
Prototype
void WinEraseRectangleFrame ( FrameType frame, const RectangleType *rP )
Parameters
-
→
frame
- Type of frame to draw (see
FrameType
). -
→
rP
- Pointer to the rectangle to frame.
Returns
See Also
WinDrawGrayRectangleFrame()
, WinDrawRectangleFrame()
, WinGetFramesRectangle()
, WinInvertRectangleFrame()
, WinPaintRectangleFrame()
WinEraseWindow Function
Purpose
Erase the contents of the draw window.
Declared In
Window.h
Prototype
void WinEraseWindow ( void )
Parameters
Returns
Comments
WinEraseRectangle()
is used to erase the window. This routine doesn't erase the frame around the draw window. See WinEraseRectangleFrame()
and WinGetWindowFrameRect()
.
WinFillLine Function
Purpose
Fill a line in the draw window with the current pattern.
Declared In
Window.h
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.
Returns
Comments
You can set the current pattern with WinSetPattern()
.
See Also
WinDrawGrayLine()
, WinDrawLine()
, WinEraseLine()
, WinInvertLine()
, WinPaintLine()
, WinPaintLines()
WinFillRectangle Function
Purpose
Draw a rectangle in the draw window with current pattern.
Declared In
Window.h
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.
Returns
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 Function
Purpose
Return the window handle of the active window.
Declared In
Window.h
Prototype
WinHandle WinGetActiveWindow ( void )
Parameters
Returns
Returns the handle of the active window. All user input is directed to the active window.
See Also
WinSetActiveWindow()
, WinGetDisplayWindow()
, WinGetFirstWindow()
, WinGetDrawWindow()
WinGetBitmap Function
Purpose
Return a pointer to a window's bitmap, which holds the window contents.
Declared In
Window.h
Prototype
BitmapType *WinGetBitmap ( WinHandle winHandle )
Parameters
Returns
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 Function
Purpose
Return the bounds of a window in display-relative coordinates.
Declared In
Window.h
Prototype
void WinGetBounds ( WinHandle winH, RectangleType *rP )
Parameters
Returns
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.
Compatibility
The implementation of this function changed in Palm OS version 4.0. If 4.0 New Feature Set is present, it works as documented here.
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.
As of Palm OS 4.0, an application should use WinGetDrawWindowBounds()
to get the bounds of the draw window.
See Also
WinGetWindowExtent()
, WinGetDrawWindowBounds()
WinGetClip Function
Purpose
Return the clipping rectangle of the draw window.
Declared In
Window.h
Prototype
void WinGetClip ( RectangleType *rP )
Parameters
Returns
See Also
WinGetCoordinateSystem Function
Purpose
Declared In
Window.h
Prototype
UInt16 WinGetCoordinateSystem ( void )
Parameters
Returns
Returns a value representing the current coordinate system. See "Window Coordinate System Constants" for the values that this function can return.
Comments
Use this function to determine the active coordinate system. Armed with this information, an application can properly initialize graphic primitive coordinates and dimensions, or can modify the coordinate system with WinSetCoordinateSystem()
.
Compatibility
Implemented only if the High-Density Display Feature Set is present.
See Also
WinGetDisplayExtent Function
Purpose
Return the width and height of the display (the screen).
Declared In
Window.h
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.
Returns
WinGetDisplayWindow Function
Purpose
Return the window handle of the display (screen) window.
Declared In
Window.h
Prototype
WinHandle WinGetDisplayWindow ( void )
Parameters
Returns
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 Function
Purpose
Return the window handle of the current draw window.
Declared In
Window.h
Prototype
WinHandle WinGetDrawWindow ( void )
Parameters
Returns
Returns handle of draw window.
See Also
WinGetDisplayWindow()
, WinGetActiveWindow()
, WinSetDrawWindow()
WinGetDrawWindowBounds Function
Purpose
Return the bounds of the draw window.
Declared In
Window.h
Prototype
void WinGetDrawWindowBounds ( RectangleType *rP )
Parameters
Returns
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
WinGetFirstWindow Function
Purpose
Return a pointer to the first window in the linked list of windows.
Declared In
Window.h
Prototype
WinHandle WinGetFirstWindow ( void )
Parameters
Returns
Returns handle of first window.
Comments
This function is usually used by the system only.
Compatibility
If Palm OS Cobalt Feature Set is present this function is unimplemented.
See Also
WinGetFramesRectangle Function
Purpose
Return the rectangle that includes a rectangle together with the specified frame around it.
Declared In
Window.h
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.
Returns
Comments
Frames are always drawn around (outside) a rectangle.
See Also
WinGetWindowFrameRect()
, WinGetBounds()
WinGetPattern Function
Purpose
Return the current fill pattern.
Declared In
Window.h
Prototype
void WinGetPattern ( CustomPatternType *patternP )
Parameters
-
←
patternP
- Buffer where the current pattern is returned (see
CustomPatternType
).
Returns
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
WinGetPatternType Function
Purpose
Return the current pattern type.
Declared In
Window.h
Prototype
PatternType WinGetPatternType ( void )
Parameters
Returns
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
WinGetPixel Function
Purpose
Return the color value of a pixel in the current draw window.
Declared In
Window.h
Prototype
IndexedColorType WinGetPixel ( Coord x, Coord y )
Parameters
Returns
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
WinGetPixelRGB Function
Purpose
Return the RGB color values of a pixel in the current draw window.
Declared In
Window.h
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.
Returns
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.
WinGetScalingMode Function
Purpose
Declared In
Window.h
Prototype
UInt32 WinGetScalingMode ( void )
Parameters
Returns
Returns the current scaling mode. See the description of WinSetScalingMode()
for information on interpreting the returned scaling mode value.
Compatibility
Implemented only if the 1.5x Display Feature Set is present.
WinGetSupportedDensity Function
Purpose
Enumerate the various display densities supported by the blitter.
Declared In
Window.h
Prototype
Err WinGetSupportedDensity ( UInt16 *densityP )
Parameters
-
↔ densityP
- Pointer to a supported density value. Set this value to zero before calling this function for the first time. Subsequent calls cause this value to be set to one of the display densities supported by the handheld.
Returns
Returns errNone
unless the value you supply in *densityP
isn't a supported density and isn't zero, in which case this function returns SysErrParamErr
.
Comments
Initialize *densityP
to zero before your application calls this function for the first time. Repeated calls to WinGetSupportedDensity
will cause the value pointed to by densityP
to change; these values represent the supported display densities, in order from low to high density. After the last supported density value, this function sets *densityP
back to zero.
NOTE: The densities reported by this function are those that are supported by the blitter. These densities are not necessarily supported by the underlying hardware. A handheld with a low-density screen that is able to scale high-density bitmaps will report that it can handle both high and low density bitmaps. Use
WinScreenGetAttribute()
to determine the density of the handheld's screen.
Density values are defined in Bitmap.h
; see the DensityType
enum. Only those values supported by a given handheld will be returned by WinGetSupportedDensity
,. For example, on a handheld with a double-density display this function returns kDensityLow
, followed by kDensityDouble
, followed by 0. For each supported density, the inverse scaling factor is supported. In this example, the blitter supports pixel-doubling low-density data for a double-density destination, and the blitter supports pixel-halving high-density data for a low-density destination.
The value pointed to by densityP
should only be zero or one of the density values supported by the handheld. If it has any other value when you call WinGetSupportedDensity
, this function will simply return sysErrParamErr
.
Compatibility
Implemented only if the High-Density Display Feature Set is present.
WinGetWindowExtent Function
Purpose
Return the width and height of the current draw window.
Declared In
Window.h
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.
Returns
See Also
WinGetBounds()
, WinGetWindowFrameRect()
,
WinGetWindowFrameRect Function
Purpose
Return a rectangle, in display-relative coordinates, that defines the size and location of a window and its frame.
Declared In
Window.h
Prototype
void WinGetWindowFrameRect ( WinHandle winHandle, RectangleType *r )
Parameters
-
→
winHandle
- Handle of window whose coordinates are desired.
-
←
r
- Pointer to the coordinates of the window.
Returns
See Also
WinIndexToRGB Function
Purpose
Convert an index in the currently active color table to an RGB value.
Declared In
Window.h
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
. SeeRGBColorType
.
Returns
Compatibility
Implemented only if 3.5 New Feature Set is present.
See Also
WinInvertChars Function
Purpose
Invert the specified characters in the draw window.
Declared In
Window.h
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).
Returns
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 Function
Purpose
Invert a line in the draw window (using the WinDrawOperation
winInvert
).
Declared In
Window.h
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.
Returns
See Also
WinDrawGrayLine()
, WinDrawLine()
, WinEraseLine()
, WinFillLine()
, WinPaintLine()
, WinPaintLines()
WinInvertPixel Function
Purpose
Invert a pixel in the draw window (using the WinDrawOperation
winInvert
).
Declared In
Window.h
Prototype
void WinInvertPixel ( Coord x, Coord y )
Parameters
Returns
Compatibility
Implemented only if 3.5 New Feature Set is present.
See Also
WinDrawPixel()
, WinErasePixel()
, WinPaintPixel()
, WinPaintPixels()
WinInvertRectangle Function
Purpose
Invert a rectangle in the draw window (using the WinDrawOperation
winInvert
).
Declared In
Window.h
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.
Returns
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 Function
Purpose
Invert a rectangular frame in the draw window (using the WinDrawOperation
winInvert
).
Declared In
Window.h
Prototype
void WinInvertRectangleFrame ( FrameType frame, const RectangleType *rP )
Parameters
-
→
frame
- Type of frame to draw (see
FrameType
). -
→
rP
- Pointer to the rectangle to frame.
Returns
See Also
WinDrawGrayRectangleFrame()
, WinDrawRectangleFrame()
, WinEraseRectangleFrame()
, WinGetFramesRectangle()
, WinPaintRectangleFrame()
WinModal Function
Purpose
Return true
if the specified window is modal.
Declared In
Window.h
Prototype
Boolean WinModal ( WinHandle winHandle )
Parameters
Returns
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 Function
Purpose
Draw a bitmap in the current draw window at the specified coordinates with the current draw mode.
Declared In
Window.h
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.
Returns
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()
, WinPaintTiledBitmap()
WinPaintChar Function
Purpose
Draw a character in the draw window using the current drawing state.
Declared In
Window.h
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).
Returns
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 Function
Purpose
Draw the specified characters in the draw window with the current draw state.
Declared In
Window.h
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).
Returns
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 Function
Purpose
Draw a line in the draw window using the current drawing state.
Declared In
Window.h
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.
Returns
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 Function
Purpose
Draw several lines in the draw window using the current drawing state.
Declared In
Window.h
Prototype
void WinPaintLines ( UInt16 numLines, WinLineType lines[] )
Parameters
-
→
numLines
- Number of lines to paint.
-
→ lines
- Array of lines. See
WinLineType
.
Returns
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 Function
Purpose
Render a pixel in the draw window using the current drawing state.
Declared In
Window.h
Prototype
void WinPaintPixel ( Coord x, Coord y )
Parameters
Returns
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 Function
Purpose
Render several pixels in the draw window using the current drawing state.
Declared In
Window.h
Prototype
void WinPaintPixels ( UInt16 numPoints, PointType pts[] )
Parameters
Returns
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 Function
Purpose
Draw a rectangle in the draw window using the current drawing state.
Declared In
Window.h
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.
Returns
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 Function
Purpose
Draw a rectangular frame in the draw window using the current drawing state.
Declared In
Window.h
Prototype
void WinPaintRectangleFrame ( FrameType frame, const RectangleType *rP )
Parameters
-
→
frame
- Type of frame to draw (see
FrameType
). -
→
rP
- Pointer to the rectangle to frame.
Returns
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()
, WinPaintRoundedRectangleFrame()
WinPaintRoundedRectangleFrame Function
Purpose
Draw a rectangular frame with rounded corners in the draw window using the current drawing state.
Declared In
Window.h
Prototype
void WinPaintRoundedRectangleFrame ( const RectangleType *rP, Coord width, Coord cornerRadius, Coord shadowWidth )
Parameters
-
→ rP
- Pointer to the rectangle to frame.
-
→ width
- The width of the frame, interpreted using the active coordinate system.
-
→ cornerRadius
- The radius of the rectangle's rounded corners, interpreted using the active coordinate system.
-
→ shadowWidth
- The shadow offset, interpreted using the active coordinate system.
Returns
Comments
This function allows you to draw a rectangle with a frame width and corner radius specified in the active coordinate system. It is necessary because WinPaintRectangleFrame()
doesn't allow you to draw rounded rectangles with a frame width greater than 2. Note that because there isn't a function that parallels either WinDrawRectangleFrame()
, WinEraseRectangleFrame()
, or WinInvertRectangleFrame()
, you must set the drawing mode and colors as appropriate and use WinPaintRoundedRectangleFrame
to achieve the desired effect.
Compatibility
Implemented only if the High-Density Display Feature Set is present.
WinPaintTiledBitmap Function
Purpose
Fill a rectangle with a pattern defined by a bitmap.
Declared In
Window.h
Prototype
void WinPaintTiledBitmap ( BitmapType *bitmapP, RectangleType *rectP )
Parameters
-
→ bitmapP
- Pointer to the bitmap that contains the desired pattern.
-
→ rectP
- Pointer to the rectangle that is to be filled.
Returns
Returns nothing. On a debug ROM, if either bitmapP
or rectP
are NULL
, an error is displayed.
Comments
This function makes it possible for an application to define a pattern that is larger than the standard 8 by 8 custom pattern, and to define high-density custom patterns.
The pattern is scaled by the blitter using the density of bitmapP
and the density of the screen bitmap. bitmapP
can be a bitmap family; if it is, the Window Manager selects a bitmap using the same algorithm used by WinPaintBitmap()
. As with other patterns, the tiled pattern is anchored to the window's origin.
If bitmapP
does not match the depth or density of the destination bitmap, the blitter converts the bitmap using a temporary buffer. Note that if there isn't enough heap space for the temporary buffer, WinPaintTiledBitmap
will be slow.
Compatibility
Implemented only if the High-Density Display Feature Set is present.
WinPalette Function
Purpose
Set or retrieve the palette for the draw window.
Declared In
Window.h
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 intotableP
beginning at index 0. -
winPaletteSet
- Set the palette. Entries from
tableP
(beginning at index 0) are set into the palette beginning atstartIndex
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, theindex
value in eachRGBColorType
entry intableP
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 theoperation
parameter; the table entries from 0 topaletteEntries
– 1 are affected by this routine.
Returns
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 andpaletteEntries
is 10, the first 10 elements of the palette will be set fromtableP
or will be copied intotableP
. - If
startIndex
is 10 andpaletteEntries
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 intableP
. - If
startIndex
isWinUseTableIndexes
andpaletteEntries
is 1, then the index value in theRGBColorType
of element 0 oftableP
will be read from or copied totableP
; in this case, theindex
field of theRGBColorType
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 Function
Purpose
Restore the draw state values to the last saved set on the stack.
Declared In
Window.h
Prototype
void WinPopDrawState ( void )
Parameters
Returns
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 Function
Purpose
Save the current draw state values onto the draw state stack.
Declared In
Window.h
Prototype
void WinPushDrawState ( void )
Parameters
Returns
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 Function
Purpose
Reset the clipping rectangle of the draw window to the portion of the draw window that is within the bounds of the display.
Declared In
Window.h
Prototype
void WinResetClip ( void )
Parameters
Returns
See Also
WinRestoreBits Function
Purpose
Copy the contents of the specified window to the draw window and delete the passed window.
Declared In
Window.h
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.
Returns
Comments
This routine is generally used to restore a region of the display that was saved with WinSaveBit()
.
See Also
WinRGBToIndex Function
Purpose
Convert an RGB value to the index of the closest color in the currently active color lookup table (CLUT).
Declared In
Window.h
Prototype
IndexedColorType WinRGBToIndex ( const RGBColorType *rgbP )
Parameters
Returns
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()
WinSaveBit Function
Purpose
Create an offscreen window and copy the specified region from the draw window to the offscreen window.
Declared In
Window.h
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.
Returns
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
WinScaleCoord Function
Purpose
Convert a single coordinate from the standard coordinate system to the active coordinate system.
Declared In
Window.h
Prototype
Coord WinScaleCoord ( Coord coord, Boolean ceiling )
Parameters
-
→ coord
- A coordinate in the standard coordinate system.
-
→ ceiling
- Pass
true
to round up,false
to truncate the fractional part when scaling.
Returns
Returns the coordinate scaled to the active coordinate system.
Comments
This function converts a coordinate by multiplying it by the coordinate scaling factor, and then truncating or rounding the result to an integer value depending on the value of ceiling
.
If the active coordinate system is kCoordinatesStandard
, the returned coordinate is equal to the supplied coordinate.
Compatibility
Implemented only if the High-Density Display Feature Set is present.
On Palm OS Cobalt, the scaling algorithm is slightly different. After the coordinate scale factor is applied, what happens next depends upon the value of ceiling
:
use lfloorf()
function when scaleFactor > 1
use lceilf()
function when scaleFactor < 1
use lceilf()
function when scaleFactor > 1
use lfloorf()
function when scaleFactor < 1
The objective of this algorithm is to ensure that for any Coord
, Point
, or Rectangle
"x", x = unscaled(scaled(x)).
See Also
WinScalePoint()
, WinScaleRectangle()
, WinUnscaleCoord()
WinScalePoint Function
Purpose
Convert a point from the standard coordinate system to the active coordinate system.
Declared In
Window.h
Prototype
void WinScalePoint ( PointType *pointP, Boolean ceiling )
Parameters
-
↔ pointP
- Pointer to a
PointType
structure that, before the call, should contain a point's standard coordinate system coordinates. After this function is called thePointType
structure contains the coordinates of the point scaled to the active coordinate system. -
→ ceiling
- Pass
true
to round up,false
to truncate the fractional part when scaling.
Returns
Returns nothing. The coordinates of the point indicated by pointP
are converted to the active coordinate system.
Comments
This function converts a point by multiplying its x and y coordinates by the coordinate scaling factor and then truncating or rounding the results depending on the value of ceiling
.
If the active coordinate system is kCoordinatesStandard
, pointP
is not changed by this function.
Compatibility
Implemented only if the High-Density Display Feature Set is present.
On Palm OS Cobalt, the scaling algorithm is slightly different. After the coordinate scale factor is applied, what happens next depends upon the value of ceiling
:
use lfloorf()
function when scaleFactor > 1
use lceilf()
function when scaleFactor < 1
use lceilf()
function when scaleFactor > 1
use lfloorf()
function when scaleFactor < 1
The objective of this algorithm is to ensure that for any Coord
, Point
, or Rectangle
"x", x = unscaled(scaled(x)).
See Also
WinScaleCoord()
, WinScaleRectangle()
, WinUnscalePoint()
WinScaleRectangle Function
Purpose
Convert a rectangle from the standard coordinate system to the active coordinate system.
Declared In
Window.h
Prototype
void WinScaleRectangle ( RectangleType *rectP )
Parameters
-
↔ rectP
- Pointer to a
RectangleType
structure that, before the call, should contain a rectangle's standard coordinate system coordinates. After this function is called theRectangleType
structure contains the coordinates of the rectangle scaled to the active coordinate system.
Returns
Returns nothing. The coordinates of the rectangle indicated by rectP
are converted to the native coordinate system.
Comments
This function scales the rectangle's topLeft
and extent
points by multiplying their x
and y
coordinates by the coordinate scaling factor. All values are then truncated, but if either topLeft.x
or extent.x
had a fractional part, extent.x
is incremented by 1 (and, similarly, if either topLeft.y
or extent.y
had a fractional part, extent.y
is incremented by 1).
If the active coordinate system is kCoordinatesStandard
, rectP
is not changed by this function.
You can use this function when your gadget handler draws using a more precise coordinate system than the Form Manager and needs to convert the form-based bounds of the gadget to the high-density bounds used by the gadget's drawing function.
Compatibility
Implemented only if the High-Density Display Feature Set is present.
See Also
WinScaleCoord()
, WinScalePoint()
, WinUnscaleRectangle()
WinScreenGetAttribute Function
Purpose
Get various attributes of the screen.
Declared In
Window.h
Prototype
Err WinScreenGetAttribute ( WinScreenAttrType selector, UInt32 *attrP )
Parameters
-
→ selector
- A value indicating which attribute to return. See the description of
WinScreenAttrType
in the Comments section, below, for the values you can supply to this parameter. -
← attrP
- Pointer to a
UInt32
into which the specified attribute value is placed by this function.
Returns
Returns errNone
if the function successfully retrieved the specified attribute, or sysErrParamErr
if selector
doesn't represent a screen attribute.
Comments
This function returns many of the attributes that can be obtained with WinScreenMode()
. Unlike WinScreenMode
, however, this function can also return the number of bytes used by each row in the screen buffer as well as the number of pixels per inch on the screen's x and y axes.
Unlike WinScreenMode
, you cannot set any attributes with this function. Also, you cannot use this function to obtain the "color enabled" attribute. And unlike WinScreenMode
, this function always returns the true screen dimensions; WinScreenMode
converts the dimensions to the active coordinate system.
Applications can use the screen resolution information to make intelligent decisions about how to draw primitives on Palm Powered handhelds with different screen resolutions.
WinScreenAttrType
This enum defines the selectors that can be used with the WinScreenGetAttribute()
function.
Prototype
typedef enum { winScreenWidth, winScreenHeight, winScreenRowBytes, winScreenDepth, winScreenAllDepths, winScreenDensity, winScreenPixelFormat, winScreenResolutionX, winScreenResolutionY } WinScreenAttrType;
Constants
-
winScreenWidth
- The width of the screen, in pixels.
-
winScreenHeight
- The height of the screen, in pixels.
-
winScreenRowBytes
- The number of bytes used by each row in the screen buffer.
-
winScreenDepth
- The screen depth.
-
winScreenAllDepths
- All screen depths (in bitmap format).
-
winScreenDensity
- The screen bitmap's density.
-
winScreenPixelFormat
- The
PixelFormatType
appropriate for the screen. -
winScreenResolutionX
- The number of pixels per inch along the screen's x axis.
-
winScreenResolutionY
- The number of pixels per inch along the screen's y axis.
Compatibility
Implemented only if the High-Density Display Feature Set is present.
See Also
WinScreenLock Function
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.
Declared In
Window.h
Prototype
UInt8 *WinScreenLock ( WinLockInitType initMode )
Parameters
Returns
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 Function
Purpose
Sets or returns display parameters, including display geometry, bit depth, and color support.
Declared In
Window.h
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 value2
(bitDepth-1). See the Example at the end of this function description for more information. -
winScreenModeGetSupportsColor
- Return
true
as the value of theenableColorP
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. For backward compatibility, when
operation
iswinScreenModeGet
orwinScreenModeGetDefaults
, a single-density width is returned, even if the handheld has a double-density display. UseWinScreenGetAttribute()
to retrieve the true hardware dimensions of the display. -
↔ heightP
- Pointer to new/old screen height. For backward compatibility, when
operation
iswinScreenModeGet
orwinScreenModeGetDefaults
, a single-density height is returned, even if the handheld has a double-density display. UseWinScreenGetAttribute()
to retrieve the true hardware dimensions of the display. -
↔
depthP
- Pointer to new/old/available screen depth.
-
↔ enableColorP
- Pass
true
to enable color drawing mode. The returned value (when using an operation that returns a value through this parameter) simply indicates whether or not the hardware supports color; its value does not change based on the current screen depth.
Returns
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 59.1 summarizes parameter usage for each operation this function performs.
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 work around 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.
See Also
WinScreenUnlock Function
Purpose
Unlock the screen and update the display.
Declared In
Window.h
Prototype
void WinScreenUnlock ( void )
Parameters
Returns
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
WinScrollRectangle Function
Purpose
Scroll a rectangle in the draw window.
Declared In
Window.h
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
, orwinRight
). -
→
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.
Returns
Comments
The rectangle scrolls within its own bounds. Any portion of the rectangle that is scrolled outside its bounds is clipped.
WinSetActiveWindow Function
Purpose
Make a window the active window.
Declared In
Window.h
Prototype
void WinSetActiveWindow ( WinHandle winHandle )
Parameters
Returns
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 Function
Purpose
Set the background color to use in subsequent draw operations.
Declared In
Window.h
Prototype
IndexedColorType WinSetBackColor ( IndexedColorType backColor )
Parameters
-
→ backColor
- Color to set; specify a value of type
IndexedColorType
.
Returns
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()
WinSetBackColorRGB Function
Purpose
Set the background color to use in subsequent draw operations.
Declared In
Window.h
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
.
Returns
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 backColorRGB
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 Function
Purpose
Set the bounds of the window to display-relative coordinates.
Declared In
Window.h
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.
Returns
Comments
A visible window cannot have its bounds modified.
Compatibility
Implemented only if 2.0 New Feature Set is present.
See Also
WinSetClip Function
Purpose
Set the clipping rectangle of the draw window.
Declared In
Window.h
Prototype
void WinSetClip ( const RectangleType *rP )
Parameters
Returns
See Also
WinClipRectangle()
, WinSetClip()
, WinGetClip()
WinSetConstraintsSize Function
Purpose
Sets the maximum, preferred, and minimum size constraints for a window.
Declared In
Window.h
Prototype
Err WinSetConstraintsSize ( WinHandle winHandle, Coord minH, Coord prefH, Coord maxH, Coord minW, Coord prefW, Coord maxW )
Parameters
-
→
winHandle
- A handle to a window.
-
→
minH
- The minimum height to which this window can be sized in standard coordinates. This value must be less than or equal to 160 pixels.
-
→
prefH
- The preferred height for this window in standard coordinates.
-
→
maxH
- The maximum height for this window in standard coordinates.
-
→
minW
- The minimum width for the window in standard coordinates.
-
→
prefW
- The preferred width for the window in standard coordinates.
-
→
maxW
- The maximum width for the window in standard coordinates.
Returns
Returns one of the following error codes:
-
errNone
- Success.
-
pinErrNoSoftInputArea
- There is no dynamic input area on this device.
-
pinErrInvalidParam
- You have specified an invalid parameter.
Comments
Applications must call this function in response to a frmLoadEvent
or frmOpenEvent
to set the size constraints for the window. If the application does not call this function, it is assumed that both the minimum and maximum values for the window are 160 pixels by 160 pixels.
Compatibility
Implemented only if the Pen Input Manager Feature Set is present.
WinSetCoordinateSystem Function
Purpose
Establish the coordinate system to be used for subsequent drawing operations.
Declared In
Window.h
Prototype
UInt16 WinSetCoordinateSystem ( UInt16 coordSys )
Parameters
-
→ coordSys
- The desired coordinate system. Supply one of the values defined in "Window Coordinate System Constants."
Returns
Returns the previous coordinate system value.
Comments
This function modifies the scale
field in the draw state (a DrawStateType
structure). As when making other modifications to a window's draw state, applications should call WinPushDrawState()
before modifying the coordinate system. To restore the coordinate system, your application can then call WinPopDrawState()
.
To calculate the draw state scale
field, the Window Manager divides the density of the bitmap associated with the draw window by coordSys
. If coordSys
is kCoordinatesNative
, the Window Manager sets the scale field to 1.0, which to enables 1-to-1 mapping of coordinates to pixels.
If you supply a value of kCoordinatesStandard
for coordSys
, subsequent drawing will use the standard coordinate system.
Compatibility
Implemented only if the High-Density Display Feature Set is present.
See Also
WinSetDrawMode Function
Purpose
Set the transfer mode to use in subsequent draw operations.
Declared In
Window.h
Prototype
WinDrawOperation WinSetDrawMode ( WinDrawOperation newMode )
Parameters
-
→
newMode
- Transfer mode to set; specify one of the
WinDrawOperation
values.
Returns
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 Function
Purpose
Set the draw window. (All drawing operations are relative to the draw window.)
Declared In
Window.h
Prototype
WinHandle WinSetDrawWindow ( WinHandle winHandle )
Parameters
Returns
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 Function
Purpose
Set the foreground color to use in subsequent draw operations.
Declared In
Window.h
Prototype
IndexedColorType WinSetForeColor ( IndexedColorType foreColor )
Parameters
-
→ foreColor
- Color to set; specify a value of type
IndexedColorType
.
Returns
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()
WinSetForeColorRGB Function
Purpose
Set the foreground color to use in subsequent draw operations.
Declared In
Window.h
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
.
Returns
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 foreColorRGB
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 Function
Purpose
Declared In
Window.h
Prototype
void WinSetPattern ( const CustomPatternType *patternP )
Parameters
-
→
patternP
- Pattern to set (see
CustomPatternType
).
Returns
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
WinSetPatternType Function
Purpose
Declared In
Window.h
Prototype
void WinSetPatternType ( PatternType newPattern )
Parameters
-
→ newPattern
- Pattern type to set for the draw window (see
PatternType
).
Returns
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
WinSetScalingMode Function
Purpose
Controls the scaling of bitmaps and fonts, and the spacing between text glyphs.
Declared In
Window.h
Prototype
UInt32 WinSetScalingMode ( UInt32 mode )
Parameters
-
→
mode
- Specifies whether bitmaps and fonts should be scaled, and whether text glyphs should be aligned on standard coordinates. See the Comments section, below, for details on how to construct the
mode
value.
Returns
Returns the previous scaling mode.
Comments
If you need to display a large, low-density bitmap—for instance, a map or a photograph—you can use WinSetScalingMode
to draw your bitmap unscaled, allowing the user to see more of the bitmap at one time. If you want to draw more, but smaller, text on a handheld that has a high-density display (including 1.5 and double-density), you can use WinSetScalingMode
to draw text unscaled. Finally, when the window coordinate system is set to kCoordinatesOneAndAHalf
you can use this function to draw text without padding pixels between glyphs, resulting in more consistent kerning for text.
On a handheld with a high-density display, if the bitmap being drawn, or the font being used, is part of a family that contains both low- and high-density members, WinSetScalingMode
controls which member is used. If kTextScalingOff
is set, for instance, the low-density font is used, unscaled, when drawing subsequent text.
Scaling Mode Values
Depending on how bitmaps and text should be scaled, OR the appropriate constants from the following table to construct the appropriate scaling mode value.
Turning bitmap scaling off causes the blitter to draw the low-density bitmap family member, unscaled, when the application subsequently calls |
||
Turning text scaling off causes the blitter to render text using the low-density family member of the appropriate font, unscaled, when the application subsequently draws text (even if the font family contains a font who's density matches the window's). This results in smaller-sized text being drawn on the screen. |
||
When text padding is turned off, the blitter does not insert pixels between glyphs in order to align glyphs on standard coordinates. (Text padding is on by default.) By setting the |
When an application calls WinSetCoordinateSystem()
to use native coordinates for a high-density window, the operating system turns off text padding. When an application calls WinSetCoordinateSystem
to use standard coordinates, the operating system turns text padding on. To use standard coordinates with pixel padding turned off, or to use native coordinates with pixel padding turned on, call WinSetScalingMode
after calling WinSetCoordinateSystem()
. Note that using standard coordinates with padding off is not recommended since the Font Manager API that measures character widths will return inaccurate widths.
The scaling mode flags are part of the window's draw state. In order to ensure that the draw state is properly restored, save that state using WinPushDrawState()
before calling functions that alter the draw state—such as WinSetScalingMode
or WinSetCoordinateSystem
. After drawing is completed, restore the draw state with WinPopDrawState()
.
When an application quits, the draw state is restored to the default settings.
Compatibility
Implemented only if the 1.5x Display Feature Set is present.
See Also
WinSetTextColor Function
Purpose
Set the color to use for drawing characters in subsequent draw operations.
Declared In
Window.h
Prototype
IndexedColorType WinSetTextColor ( IndexedColorType textColor )
Parameters
-
→ textColor
- Color to set; specify a value of type
IndexedColorType
.
Returns
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()
WinSetTextColorRGB Function
Purpose
Set the color to use for drawing characters in subsequent draw operations.
Declared In
Window.h
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
.
Returns
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 textColorRGB
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 Function
Purpose
Set the graphic state to enable or disable the underlining of characters.
Declared In
Window.h
Prototype
UnderlineModeType WinSetUnderlineMode ( UnderlineModeType mode )
Parameters
-
↔
mode
- New underline mode type; see
UnderlineModeType
.
Returns
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
WinUnscaleCoord Function
Purpose
Convert a single coordinate from the active coordinate system to the standard coordinate system.
Declared In
Window.h
Prototype
Coord WinUnscaleCoord ( Coord coord, Boolean ceiling )
Parameters
-
→ coord
- A coordinate in the active coordinate system.
-
→ ceiling
- Pass
true
to round up,false
to truncate the fractional part when scaling.
Returns
Returns the coordinate scaled to the standard coordinate system.
Comments
This function converts a coordinate by dividing it by the coordinate scaling factor, truncating or rounding the result to an integer value depending on the value of ceiling
.
If the active coordinate system is kCoordinatesStandard
, the returned coordinate is equal to the supplied coordinate.
Compatibility
Implemented only if the High-Density Display Feature Set is present.
On Palm OS Cobalt, the scaling algorithm is slightly different. After the coordinate scale factor is applied, what happens next depends upon the value of ceiling
:
use lfloorf()
function when scaleFactor > 1
use lceilf()
function when scaleFactor < 1
use lceilf()
function when scaleFactor > 1
use lfloorf()
function when scaleFactor < 1
The objective of this algorithm is to ensure that for any Coord
, Point
, or Rectangle
"x", x = unscaled(scaled(x)).
See Also
WinScaleCoord()
, WinUnscalePoint()
, WinUnscaleRectangle()
WinUnscalePoint Function
Purpose
Convert a point from the active coordinate system to the standard coordinate system.
Declared In
Window.h
Prototype
void WinUnscalePoint ( PointType *pointP, Boolean ceiling )
Parameters
-
↔ pointP
- Pointer to a
PointType
structure that, before the call, should contain a point's coordinates using the active coordinate system. After this function is called thePointType
structure contains the coordinates of the point scaled to the standard coordinate system. -
→ ceiling
- Pass
true
to round up,false
to truncate the fractional part when scaling.
Returns
Returns nothing. The coordinates of the point indicated by pointP
are converted to the standard coordinate system.
Comments
This function converts a point by dividing its x and y coordinates by the coordinate scaling factor, truncating or rounding the results to integer values depending on the value of ceiling
. For instance, the input coordinates (11, 13) are transformed to (6, 7) if the input values represent native coordinates on a handheld with a double-density screen and ceiling
is set to true
. If ceiling
is set to false
, the same input coordinates are transformed to (5, 6).
If the active coordinate system is kCoordinatesStandard
, pointP
is not changed by this function.
Compatibility
Implemented only if the High-Density Display Feature Set is present.
On Palm OS Cobalt, the scaling algorithm is slightly different. After the coordinate scale factor is applied, what happens next depends upon the value of ceiling
:
use lfloorf()
function when scaleFactor > 1
use lceilf()
function when scaleFactor < 1
use lceilf()
function when scaleFactor > 1
use lfloorf()
function when scaleFactor < 1
The objective of this algorithm is to ensure that for any Coord
, Point
, or Rectangle
"x", x = unscaled(scaled(x)).
See Also
WinScalePoint()
, WinUnscaleCoord()
, WinUnscaleRectangle()
WinUnscaleRectangle Function
Purpose
Convert a rectangle from the active coordinate system to the standard coordinate system.
Declared In
Window.h
Prototype
void WinUnscaleRectangle ( RectangleType *rectP )
Parameters
-
↔ rectP
- Pointer to a
RectangleType
structure that, before the call, should contain a rectangle's coordinates using the active coordinate system. After this function is called theRectangleType
structure contains the coordinates of the rectangle scaled to the standard coordinate system.
Returns
Returns nothing. The coordinates of the rectangle indicated by rectP
are converted to the standard coordinate system.
Comments
This function scales the rectangle's topLeft
and extent
points by dividing their x
and y
coordinates by the coordinate scaling factor. All values are then truncated, but if either topLeft.x
or extent.x
had a fractional part, extent.x
is incremented by 1 (and, similarly, if either topLeft.y
or extent.y
had a fractional part, extent.y
is incremented by 1).
If the active coordinate system is kCoordinatesStandard
, rectP
is not changed by this function.
Compatibility
Implemented only if the High-Density Display Feature Set is present.
See Also
WinScaleRectangle()
, WinUnscaleCoord()
, WinUnscalePoint()
WinValidateHandle Function
Purpose
Return true
if the specified handle references a valid window object.
Declared In
Window.h
Prototype
Boolean WinValidateHandle ( WinHandle winHandle )
Parameters
Returns
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 Function
Purpose
Convert a window-relative coordinate to a display-relative coordinate.
Declared In
Window.h
Prototype
void WinWindowToDisplayPt ( Coord *extentX, Coord *extentY )
Parameters
Returns
Comments
The coordinate passed is assumed to be relative to the draw window.