This chapter provides information about windows by discussing these topics:
Window Structures and Types
Window Constants
Window Events
Window Manager Notifications
Window Management Functions and Macros
Window Drawing Functions and Macros
Application-Defined Functions
The header files Window.h
and CmnDrawingTypes.h
declare the API that this chapter describes. Chapter 1, "The Display," Chapter 2, "Working with Forms and Dialogs," and Chapter 8, "Drawing," describe some window-related concepts.
Window Structures and Types
CustomPatternType Typedef
Purpose
Declared In
CmnDrawingTypes.h
Prototype
typedef uint8_t CustomPatternType[8];
Comments
CustomPatternType
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.
See Also
WinFillLine()
, WinFillRectangle()
, PatternType
FrameBitsType Struct
Purpose
Specifies attributes of a window's frame.
Declared In
Window.h
Prototype
typedef union FrameBitsType { struct oldBitsTag { uint16_t cornerDiam : 8; uint16_t reserved_3 : 3; uint16_t threeD : 1; uint16_t shadowWidth : 2; uint16_t width : 2; } bits; uint16_t word; } FrameBitsType
Fields
-
cornerDiam
- The 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
- The width of the shadow.
-
width
- The frame width.
-
word
- Reserved.
See Also
IndexedColorType Typedef
Purpose
Specifies a color by its index value; that is, by its location in a color table.
Declared In
CmnDrawingTypes.h
Prototype
typedef uint8_t IndexedColorType;
Comments
Color tables are defined by the ColorTableType
structure, which is declared in CmnBitmapTypes.h
. The IndexedColorType
can hold a 1, 2, 4, or 8-bit index.
WinConstraintsType Struct
Purpose
Specifies a window's position and sizing requirements.
Declared In
Window.h
Prototype
typedef struct WinConstraintsType { uint32_t x_flags; int16_t x_pos; int16_t x_min; int16_t x_pref; int16_t x_max; uint32_t y_flags; int16_t y_pos; int16_t y_min; int16_t y_pref; int16_t y_max; } WinConstraintsType
Fields
-
x_flags
- Currently unused. Set this to 0.
-
x_pos
- The position, given in standard coordinates, of the left side of the window. Use the
winUndefConstraint
constant for this value to have the system place the window. -
x_min
- The minimum possible width of the window in standard coordinates.
-
x_pref
- The preferred width of the window in standard coordinates.
-
x_max
- The maximum width of the window in standard coordinates.
-
y_flags
- Currently unused. Set this to 0.
-
y_pos
- The position of the top of the window in standard coordinates. Use the
winUndefConstraint
constant for this value to have the system place the window. -
y_min
- The minimum height that the window should ever be made in standard coordinates.
-
y_pref
- The preferred height for this window in standard coordinates.
-
y_max
- The maximum height for the window in standard coordinates.
Comments
You set a window's size constraints when you add a WINDOW_CONSTRAINTS_RESOURCE
to a form or when you programmatically create a window using WinCreateWindowWithConstraints()
. The actual size of the window is negotiated at run time taking into account the size requirements for the active pinlet in the input area, the status bar, and any other panel that is being displayed.
These constraints should specify a window's ideal sizes independent of the screen's actual size. It's the Window Manager's job to take the screen size into consideration when actually sizing the window.
For example, consider a window showing a scrolling list of text. This window should report its minimum height as being the smallest size it can be while still being usable. For many applications, the minimum height is 160, which is also the default for legacy-mode windows. The window's preferred size should be the height required to display all of the text it contains. The maximum height could be one of two possibilities. If the text is not editable, it should be the same as the preferred height. If the text is editable, it will probably be the constant winMaxConstraint
, which means make the window as large as possible because the user can use that extra space for editing.
See Also
WinSetConstraints()
, "Constraint Constants"
WinHandle Typedef
Purpose
Provides the handle to a window.
Declared In
Window.h
Prototype
struct WindowType
typedef struct WindowType *WinHandle;
Comments
A window is an abstract drawing region. Typically, you don't work with windows directly. You work with forms instead. You might work with windows if your application needs custom drawing.
Compatibility
The WindowType
structure is no longer public and has changed significantly from its definition in earlier releases. Do not attempt to access the WindowType
structure.
See Also
FrmGetWindowHandle()
, WinGetActiveWindow()
, WinGetDrawWindow()
WinLineType Struct
Purpose
Declared In
Window.h
Prototype
typedef struct WinLineType { Coord x1; Coord y1; Coord x2; Coord y2; } WinLineType
Fields
See Also
Window Constants
Constraint Constants
Purpose
Special values for the fields in WinConstraintsType
.
Declared In
Window.h
Constants
-
#define winUndefConstraint SHRT_MIN //–32768
- Specifies an undefined constraint. The system decides the value of this constraint. Undefined constraints are most commonly used for the position values so that the Window Manager positions the window at the preferred location.
-
#define winMaxConstraint SHRT_MAX // 32767
- Specifies a value that means "as large as possible."
Coordinate System Constants
Purpose
Specifies the coordinate system to be used when drawing with a given window.
Declared In
Window.h
Constants
-
#define kCoordinatesNative 0
- Use the bitmap's or screen's native coordinate system; this enables a 1-to-1 correspondence between coordinates and pixels.
- If you use the native coordinate system, keep in mind that Palm Powered™ devices come in a variety of screen densities. Do not assume that native coordinates always means double-density.
-
#define kCoordinatesStandard 72
- On a single-density handheld (that contains a 160 X 160 screen), there is one screen pixel per standard coordinate. On a high-density screen, there is more than one screen pixel per standard coordinate.
-
#define kCoordinatesOneAndAHalf 108
- One and a half times the standard coordinate system.
-
#define kCoordinatesDouble 144
- Twice the standard coordinate system.
-
#define kCoordinatesTriple 216
- Three times the standard coordinate system.
-
#define kCoordinatesQuadruple 288
- Four times the standard coordinate system.
See Also
WinSetCoordinateSystem()
, WinGetCoordinateSystem()
, GcSetCoordinateSystem()
FrameType Typedef
Purpose
Specifies a window frame style.
Declared In
Window.h
Prototype
typedef UInt16 FrameType;
Constants
-
#define noFrame 0x0000
- No frame.
-
#define simpleFrame 0x0001
- A plain rectangular frame.
-
#define rectangleFrame simpleFrame
- A plain rectangular frame.
-
#define simple3DFrame 0x0012
- 3D frame with width of 2. This frame type is not supported.
-
#define roundFrame 0x0401
- A round frame with width of 1.
-
#define boldRoundFrame 0x0702
- A round frame with width of 2.
-
#define popupFrame 0x0205
- Pop-up frame style with slight corner roundness, width of 1 and shadow of 1.
-
#define dialogFrame 0x0302
- Dialog frame style with slight corner roundness and width of 2.
-
#define menuFrame popupFrame
- Same as
popupFrame.
Comments
The FrameType
can be set to one of the defined frame types listed here or to a custom frame type as defined by a FrameBitsType
structure.
See Also
WinGetFrameType()
, WinSetFrameType()
PatternType Enum
Purpose
Specifies a pattern for drawing.
Declared In
CmnDrawingTypes.h
Constants
-
blackPattern
- All bits on.
-
whitePattern
- All bits off.
-
grayPattern
- Alternating on and off bits.
-
customPattern
- Custom pattern specified by
CustomPatternType
. -
lightGrayPattern
- One out of four bits in each row turned on.
-
darkGrayPattern
- One out of four bits in each row turned off.
Comments
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 when drawing patterned lines and filled rectangles.
The three standard gray patterns—grayPattern
, lightGrayPattern
, and darkGrayPattern
—are always drawn using the screen density to improve the appearance of gray fills. Custom patterns, however, are stretched as appropriate based on the destination density.
See Also
WinGetPatternType()
, WinSetPatternType()
Other Patterns
Purpose
Declared In
CmnDrawingTypes.h
Constants
-
#define noPattern blackPattern
- The shape is filled with no special pattern. Only the current color.
-
#define grayHLinePattern 0xAA
- The system uses this to draw a gray diagonal line.
-
#define grayHLinePatternOdd 0x55
- The system uses this to draw a gray diagonal line.
Scaling Mode Constants
Purpose
Constants used to construct a scaling mode that is passed to WinSetScalingMode()
.
Declared In
Window.h
Constants
-
#define kBitmapScalingOff 1
- Turns bitmap scaling off, which causes the rendering system to draw the low-density bitmap family member, unscaled, when the application calls one of the bitmap drawing functions (even if the bitmap family contains a bitmap whose density matches the window's). This causes your bitmaps to be drawn smaller, as if they were being viewed from a distance.
-
#define kTextScalingOff 2
- Turns text scaling off, which causes the rendering system 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 whose density matches the window's). This results in smaller-sized text being drawn on the screen.
-
#define kTextPaddingOff 4
- Turns off text padding. When text padding is turned off, the rendering system does not insert pixels between glyphs in order to align glyphs on standard coordinates. (Text padding is on by default.) By setting the
kTextPaddingOff
bit, an application can lay out text using high density coordinates and preserve the native font's internal kerning. This unpadded mode provides the best appearance of text, but requires the application to use the high-density coordinate system. - Currently, setting
kTextPaddingOff
has no effect.
See Also
UnderlineModeType Enum
Purpose
Specifies possible values for the underline mode stored in the drawing state.
Declared In
CmnDrawingTypes.h
Constants
-
noUnderline
- No underline.
-
grayUnderline
- A dotted line in the current foreground color.
-
solidUnderline
- A solid line in the foreground color.
-
colorUnderline
- A solid line in the foreground color.
-
thinUnderline
- A thin single-pixel solid line in the foreground color.
WinDirectionType Typedef
Purpose
Specifies a scrolling direction.
Declared In
Window.h
Prototype
typedef Enum8 WinDirectionType;
Constants
See Also
WinScrollRectangle()
, FldScrollable()
, FldScrollField()
, LstScrollList()
WinDrawOperation Enum
Purpose
Specifies the transfer mode for color drawing.
Declared In
CmnDrawingTypes.h
Constants
-
winPaint
- Write color-matched source pixels to the destination. If a bitmap's
bmpFlagsHasTransparency
flag is set,winPaint
behaves likewinOverlay
instead. -
winErase
- Write using the background color if the source pixel is transparent.
-
winMask
- Write using the background color 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.
-
winPaintInverse
- Invert the source pixel color and then proceed as with
winPaint
. -
winSwap
- Swap the background color and foreground color 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 using
winPaint
mode instead.
Comments
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 background color and entry 1 is the foreground color (text color 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
Bitmaps have a bmpFlagsHasTransparency
flag and may designate a transparent color:
- 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
bmpFlagsHasTransparency
bit is assumed to befalse
. - When the
bmpFlagsHasTransparency
flag is set and the transfer mode iswinPaint
, only the non-transparent pixels are copied to the destination. With text and patterns, Palm OS® assumes that the "off" bits are the ones designated as transparent and acts as if thebmpFlagsHasTransparency
flag is alwaysfalse
. This assumption retains backwards compatibility and unifies the use of transparency across all source data.
Compatibility
winInvert
, winErase
, winMask
, winPaintInverse
, and winSwap
are deprecated in Palm OS Cobalt. winInvert
and winSwap
do not work when drawing text, drawing unfilled rectangles, or drawing to update-based windows. When you try to use them in these instances, nothing is drawn to the screen.
See Also
WinCopyRectangle()
, WinSetDrawMode()
WinFlagsType Enum
Purpose
Specifies how the window looks and behaves. These flags are passed as arguments to WinCreateWindowWithConstraints()
when creating a window.
Declared In
Window.h
Constants
-
winFlagModal = 0x00000001
- The window is modal. When a modal window is the topmost window, it receives the pen down events and keystrokes for the window that it obscures, even when it is not the same size as that window.
-
winFlagNonFocusable = 0x00000002
- The window cannot become the active window.
-
winFlagBackBuffer = 0x00000004
- The window is back-buffered. A back-buffered window draws into a memory region. The system does not update the screen until the application returns to its event loop or it calls
WinFlush()
. Legacy windows and transitional windows are back-buffered. -
winFlagVisibilityEvents = 0x00000008
- The window receives the
winVisibilityChangedEvent
when anything obscures the window or when a previously obscured window is revealed. -
winLayerMask = 0x000000f0
- A mask value defining all of the layer constants.
-
winLayerNormal = 0x00000000
- Used for application windows.
-
winLayerPriority = 0x00000010
- Used for system dialogs.
-
winLayerSlip = 0x00000040
- Used for the slip windows created by the status bar.
-
winLayerSecurity = 0x00000050
- Used for password dialogs and other security-related dialogs.
-
winLayerSystem = 0x00000020
- Used for the dynamic input area, the status bar, and catastrophic system messages such as the low battery alert dialog
-
winLayerMenu = 0x00000030
- Used for menus.
See Also
WindowFormatType Enum
Purpose
Specifies the window format when creating an off-screen window with the WinCreateOffscreenWindow()
function.
Declared In
Window.h
Constants
-
screenFormat = 0
- The window's bitmap is allocated using the hardware screen's depth, but for backward compatibility the bitmap associated with the off-screen window is always low density, and the window always uses a coordinate system that directly maps off-screen pixels to coordinates.
-
genericFormat
- Like
screenFormat
. -
nativeFormat
- Reflects the actual hardware screen format in all ways, including screen depth, density, and pixel format. Applications must always use the APIs when drawing to a
nativeFormat
off-screen window: directly accessing off-screen pixels will produce undefined results. When using this format, the width and height arguments must be specified using the active coordinate system.
Miscellaneous Constants
Purpose
Other Window Manager constants.
Declared In
Window.h
Constants
-
#define DrawStateStackSize 7
- The maximum size of the draw state stack that is grown with
WinPushDrawState()
and shrunk withWinPopDrawState()
. -
#define invalidWindowHandle 0
- Specifies an invalid window handle.
-
#define kWinVersion 10
- The current version of the Window Manager. The feature constant
sysFtrNumWinVersion
is set to this value.
Window Events
sysClearUIEvent
Purpose
Sent to all threads outside of the application's main UI thread to indicate that the application is about to be exited. This event allows background threads to close dialogs or remove any other user interface that they display.
Declared In
Event.h
Prototype
Comments
SysHandleEvent()
handles the sysClearUIEvent
for you by transforming it into an appStopEvent
in any threads that are displaying a user interface but are not the main UI thread.
Most applications do not need to respond to this event. You only should do so if your application displays a dialog from a background thread and you don't want that dialog erased with the rest of the application's user interface. In that case, you should intercept the sysClearUIEvent
before the call SysHandleEvent()
and ignore it.
winEnterEvent
Purpose
Sent when a window becomes the active window. This can happen in two ways: a call to WinSetActiveWindow()
is issued (FrmSetActiveForm()
does this), or the user taps within the bounds of a window (such as a menu window) that is visible but not active.
For this event, the EventType
data
field contains the structure shown in the Prototype section, below.
Declared In
Event.h
Prototype
struct _WinEnterEventType { WinHandle enterWindow; WinHandle exitWindow; }
Fields
-
enterWindow
- The handle to the window being entered. This may be the window for a form, a menu, or some other type of window.
-
exitWindow
- The handle to the window being exited if there is currently an active window, or 0 if there is no active window.
Comments
winEnterEvent
and winExitEvent
are only sent for windows created using the UI Library. If the user taps the status bar, for example, the application receives only the winFocusLostEvent
, not the winExitEvent
.
winEnterEvent
and winExitEvent
are typically received when the active window within a thread changes. For example, when the user displays the menu, the application receives a winExitEvent
for the current form's window and a winEnterEvent
for the menu's window. When the menu is dismissed, the application receives the winExitEvent
for the menu's window followed by the winEnterEvent
for the form's window.
winExitEvent
Purpose
Sent when a window is deactivated. A window is deactivated when another window becomes the active window.
For this event, the EventType
data
field contains the structure shown in the Prototype section, below.
Declared In
Event.h
Prototype
struct _WinExitEventType { WinHandle enterWindow; WinHandle exitWindow; }
Fields
-
enterWindow
- The handle to the window being entered. This may be the window for a form, a menu, or some other type of window.
-
exitWindow
- The handle to the window being exited.
Comments
The winExitEvent
, like all events, is sent to the active form's event handler. Because winExitEvent
is often posted to the event queue as a result of a FrmSetActiveForm()
call, it is sent to the event handler for the form that has just been made active, not to the event handler for the form whose window is being exited.
See Also
winFocusGainedEvent
Purpose
Sent when a new window gains the input focus.
For this event, the EventType
data
field contains the structure shown in the Prototype section, below.
Declared In
Event.h
Prototype
struct _WinFocusGainedEventType { WinHandle window; uint32_t flags; }
Fields
Comments
The input focus determines which thread is sent keyDownEvent
s. This event is sent to the event handler for the window that will now receive keyDownEvent
s. For example, if the user is currently working in a slip window and then taps in your application's form, the form's window receives the input focus. The form's event handler receives the winFocusGainedEvent
.
This event is only sent regarding focusable windows. Menus, pop-up lists, and the input area all use nonfocusable windows. Entering and exiting these windows do not generate winFocusGainedEvent
or winFocusLostEvent
.
FrmHandleEvent()
responds to this event by assigning the focus to a field within that form if necessary. That is, if a text field or table previously had the input focus when the form lost focus, it is assigned the input focus when the form regains focus.
Applications typically do not respond to this event. Games might want to do so to resume activity after receiving the input focus.
winFocusLostEvent
Purpose
Sent when a new window gains input focus.
For this event, the EventType
data
field contains the structure shown in the Prototype section, below.
Declared In
Event.h
Prototype
struct _WinFocusLostEventType { WinHandle window; uint32_t flags; };
Fields
Comments
This event is sent to the event handler for the window that currently has the input focus and is about to lose it. For example, if a form within your application currently has input focus and the user taps the status bar, your form's event handler receives the winFocusLostEvent
.
Note the difference between this event and the winExitEvent
. If your application has the input focus and the user switches to another form in the same application:
- The first form receives
winFocusLostEvent
. - The second form receives a
winExitEvent
about the first form's window. - The second form receives a
winEnterEvent
about its own window. - If the second form is granted input focus, it receives the
winFocusGainedEvent
as well. It is not guaranteed to receive this event because another window in a different thread might request the input focus at the same time.
This event is only sent regarding focusable windows. Menus, pop-up lists, and the input area all use nonfocusable windows. Entering and exiting these windows do not generate winFocusGainedEvent
or winFocusLostEvent
.
FrmHandleEvent()
responds to this event by releasing any focus assigned to a field within the form that's losing focus.
Applications typically do not respond to this event. Games might want to do so to suspend activity upon losing the input focus.
See Also
winResizedEvent
Purpose
Sent when a window's size or position changes.
For this event, the EventType
data
field contains the structure shown in the Prototype section, below.
Declared In
Event.h
Prototype
struct _WinResizedEventType { WinHandle window; RectangleType newBounds; };
Fields
-
window
- The handle to the window that needs to be resized.
-
newBounds
- A rectangle specifying the new bounds for the window. See
RectangleType
.
Comments
Applications should respond to this event by rearranging the controls in the form as necessary. You can set up the form so that this is handled for you. Call FrmInitLayout()
when the form is loaded and specify what should happen for each element in the form when the form is resized (whether that element should move or it should resize). After you make this call, FrmHandleEvent()
calls FrmPerformLayout()
in response to the winResizedEvent
. FrmPerformLayout()
uses the resizing rules you specify to rearrange the elements in the form.
If you need more control over the layout of one or more elements on the form, handle winResizedEvent
. Call FrmPerformLayout()
and then tweak the positions or sizes of the elements you need to control. Optionally, you can handle all elements in the form yourself.
Do not draw the controls until you receive a frmUpdateEvent
.
winResizedEvent
is not sent for legacy windows; legacy windows do not resize.
winUpdateEvent
Purpose
Sent when all or a portion of a window needs to be redrawn. This includes when the window is first created, when it is resized, and as a result of the functions WinInvalidateRect()
or WinInvalidateWindow()
.
For this event, the EventType
data
field contains the structure shown in the Prototype section, below.
Declared In
Event.h
Prototype
struct _WinUpdateEventType { WinHandle window; RectangleType dirtyRect; void *prv; };
Fields
-
window
- The handle to the window that needs to be redrawn.
-
dirtyRect
- The portion of the window that needs to be redrawn. See
RectangleType
. -
prv
- System use only.
Comments
This event is sent for any type of window other than legacy windows. A window may either represent a form, a menu, or a pinlet.
winUpdateEvent
is a signal that the rendering system has created a graphics context for the window and is ready for the application to draw to the window.
When the window represents a form, no action is required for this event. If it is not handled, the system posts a frmUpdateEvent
. FrmHandleEvent()
responds to the frmUpdateEvent
by calling FrmDrawForm()
and then applications can perform any custom drawing.
The system handles updating the windows for menus and other user interface items, so no action is typically required from an application if window
represents a menu.
IMPORTANT: Never post a
winUpdateEvent
or a frmUpdateEvent
explicitly. Instead, use one of the functions WinInvalidateRect()
, WinInvalidateRectFunc()
, or WinInvalidateWindow()
.
winVisibilityChangedEvent
Purpose
Sent to specially marked windows when another window obscures a portion of it.
For this event, the EventType
data
field contains the structure shown in the Prototype section, below.
Declared In
Event.h
Prototype
struct winVisibilityChanged { WinHandle window; uint32_t visibility; } winVisibilityChanged;
Fields
Comments
Only windows that have the winFlagVisibilityEvents flag set in the constraints resource receive this event. You should only set the flag on windows that display time-sensitive information that can become meaningless if obscured. For example, games may want to set the flag for their windows so that they can delay the game if the user launches a slip window or if any other window obscures the game.
Most applications should not care if another window obscures the application's windows. When the window is redrawn, drawing is always clipped to the visible region.
Window Manager Notifications
sysNotifyDisplayChangeEvent
Purpose
Broadcast whenever the display mode changes. That is, either the color table has been set to use a specific palette using the WinPalette()
function or the bit depth has changed using the WinScreenMode()
function.
Declared In
NotifyMgr.h
Parameters
notifyDetailsP
points to a SysNotifyDisplayChangeDetailsType
structure
Comments
The notifyDetailsP
parameter indicates how the bit depth changed. If the two values in the struct are equal, it means that the color palette has changed instead of the bit depth.
See Also
"Notification Manager" in Exploring Palm OS: Programming Basics
Window Management Functions and Macros
This section lists and describes the Window Manager functions that involve the creation, deletion, and manipulation of windows as abstract regions.
ECWinValidateHandle Macro
Purpose
Calls WinValidateHandle()
.
Declared In
Window.h
Prototype
#define ECWinValidateHandle ( winHandle )
Parameters
-
→ winHandle
- The
WinHandle
to validate.
Returns
Comments
On debug ROMs, displays a fatal error message if the window handle is invalid. On release ROMs, this macro has no effect.
Do not use this macro in production code. It is for debugging purposes only.
WinConvertCoord Function
Purpose
Converts a coordinate from one screen density to another.
Declared In
Window.h
Prototype
Coord WinConvertCoord ( uint16_tcurrentDensity
, uint16_tnewDensity
, Coordcoord
, Booleanceiling
)
Parameters
-
→ currentDensity
- The current density for the specified coordinate.
-
→ newDensity
- The density to which to scale the coordinate.
-
→ coord
- Coordinate in the
currentDensity
. -
→ ceiling
-
true
to round up orfalse
to round down.
Returns
Coordinate in newDensity
that provides the same location as coord
.
Comments
This function converts a coordinate by multiplying it by the coordinate scaling factor, which is computed from the current and new densities. 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()
, WinScaleCoordNativeToActive()
, WinScreenGetAttribute()
WinConvertPoint Function
Purpose
Converts a point from one screen density to another.
Declared In
Window.h
Prototype
void WinConvertPoint ( uint16_tcurrentDensity
, uint16_tnewDensity
, PointType*pointP
, Booleanceiling
)
Parameters
-
→ currentDensity
- The current density for the specified point.
-
→ newDensity
- The density to which to scale the point.
-
↔ pointP
- A point in the
currentDensity
. Upon return, a point innewDensity
that represents the same location. -
→ ceiling
-
true
to round up orfalse
to round down.
Returns
Comments
This function converts a point by multiplying its x and y coordinates by the coordinate scaling factor., which is computed from the current and new densities 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()
, WinScreenGetAttribute()
WinConvertRectangle Function
Purpose
Converts a rectangle from one screen density to another.
Declared In
Window.h
Prototype
void WinConvertRectangle ( uint16_tcurrentDensity
, uint16_tnewDensity
, RectangleType*rectP
)
Parameters
-
→ currentDensity
- The current density for the specified rectangle.
-
→ newDensity
- The density to which to scale the rectangle.
-
↔ rectP
- A rectangle in the
currentDensity
. Upon return, the same rectangle with the same location and dimensions but given innewDensity
.
Returns
See Also
WinScaleRectangle()
, WinScreenGetAttribute()
WinCreateBitmapWindow Function
Purpose
Creates a new off-screen window.
Declared In
Window.h
Prototype
WinHandle WinCreateBitmapWindow ( BitmapType *bitmapP
, status_t *error
)
Parameters
-
→ bitmapP
- A pointer to a bitmap to associate with the window. (See
BitmapType
.) -
← error
- A pointer to any error this function encounters.
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, 8, or 16). 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 off-screen and uses the generic format (for device independence). 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 off-screen window. If you call WinCreateOffscreenWindow()
instead of using this function, the bitmap is freed when WinDeleteWindow()
is called.
Compatibility
This function exists for compatibility purposes only. Use GcCreateBitmapContext()
instead.
See Also
WinCreateWindow()
, WinCreateOffscreenWindow()
WinCreateOffscreenWindow Function
Purpose
Creates a new off-screen window.
Declared In
Window.h
Prototype
WinHandle WinCreateOffscreenWindow ( Coordwidth
, Coordheight
, WindowFormatTypeformat
, status_t *error
)
Parameters
-
→ width
- The width of the window in pixels. The coordinate system you use for this parameter depends upon the value of
format
. -
→ height
- The 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
- A pointer to any error this function encounters.
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.
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.
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 off-screen window's bitmap but are just using the APIs, you can always pass nativeFormat
for the screen format and things will work as expected. If you need direct access to the bits of the off-screen 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 Function
Purpose
Creates a new legacy-mode window.
Declared In
Window.h
Prototype
WinHandle WinCreateWindow ( const RectangleType *bounds
, FrameTypeframe
, Booleanmodal
, Booleanfocusable
, status_t *error
)
Parameters
-
→ bounds
- The display-relative bounds of the window. See
RectangleType
. -
→ frame
- The 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
- A pointer to any error encountered by this function.
Returns
The handle of the new window upon success, or NULL
if an error occurs. The error
parameter contains one of the following:
Comments
The window created with this function is a legacy-mode window, meaning that it does not receive events such as winUpdateEvent
or winResizedEvent
.
You can only call this function within the main UI thread.
See Also
WinDeleteWindow()
, WinCreateWindowWithConstraints()
WinCreateWindowWithConstraints Function
Purpose
Creates a new update-based or transitional window with the specified size constraints.
Declared In
Window.h
Prototype
WinHandle WinCreateWindowWithConstraints ( FrameTypeframe
, WinFlagsTypeflags
, const WinConstraintsType *constraints
, status_t *error
)
Parameters
-
→ frame
- The type of frame around the window (see
FrameType
). -
→ flags
- Window creation flags (see
WinFlagsType
). -
→ constraints
- The size constraints (see
WinConstraintsType
). -
← error
- A pointer to any error encountered by this function.
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 size constraints and frame type that you specify. See WinConstraintsType
for an explanation of how to set the size constraints.
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()
.
In Palm OS Cobalt, there are three types of windows that may be created:
- Legacy windows. These windows are created by
WinCreateWindow()
or they are created if you don't specify aWINDOW_CONSTRAINTS_RESOURCE
for a form. You can draw to a legacy window whenever you want, not just in an update event. Legacy windows do not receive the new events (such aswinUpdateEvent
orwinResizedEvent
). - Update-based windows. These windows are created by calling WinCreateWindowWithConstraints
()
or by adding aWINDOW_CONSTRAINTS_RESOURCE
to a form. Drawing to an update-based window is asynchronous and should only be performed when the system requests you to do so (by posting awinUpdateEvent
). - Transitional windows. These windows are created by calling
WinCreateWindowWithConstraints()
and specifyingwinFlagBackBuffer
in theflags
parameter or by adding to a form aWINDOW_CONSTRAINTS_RESOURCE
with thewinFlagBackBuffer
bit set. You must wait for an initialwinResizedEvent
before you draw to a transitional window. After the initial event, you can draw to a transitional window any time you like.
Use this function instead of calling WinCreateWindow()
followed by WinSetConstraints()
because it avoids the intermediate state of the window.
WinDeleteWindow Function
Purpose
Destroys the record for the window. The WinHandle
is no longer valid after calling this function.
Declared In
Window.h
Prototype
void WinDeleteWindow ( WinHandlewinHandle
, BooleaneraseIt
)
Parameters
-
→ winHandle
- The handle of the 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 that was allocated by the system. Windows created using WinCreateOffscreenWindow()
have their bitmaps freed; windows created using WinCreateWindow()
or WinCreateBitmapWindow()
do not.
The eraseIt
parameter affects on-screen transitional or legacy windows only; off-screen windows are never erased. As a performance optimization, you might set eraseIt
to false
for an on-screen window if you know that you are going to immediately redraw the area anyway.
WinDisplayToWindowPt Function
Purpose
Converts a screen-relative coordinate to a window-relative coordinate. The coordinate returned is relative to the display window.
Declared In
Window.h
Prototype
void WinDisplayToWindowPt ( Coord *x
, Coord *y
)
Parameters
Returns
See Also
WinFinishThreadUI Function
Purpose
Delete the user interface context for a thread.
Declared In
Window.h
Prototype
status_t WinFinishThreadUI ( void )
Parameters
Returns
Comments
This function decrements the reference count for the UI context in this thread. If the reference count becomes zero, it then deletes the reference context and all windows that have been created in the thread.
See Also
WinFlush Function
Purpose
Refreshes the screen for transitional windows.
Declared In
Window.h
Prototype
void WinFlush ( void )
Parameters
Returns
WinGetActiveWindow Function
Purpose
Returns the window handle of the active window.
Declared In
Window.h
Prototype
WinHandle WinGetActiveWindow ( void )
Parameters
Returns
The handle of the active window. All user input is directed to the active window.
See Also
WinSetActiveWindow()
, WinGetDisplayWindow()
, WinGetDrawWindow()
WinGetBitmap Function
Purpose
Returns a pointer to a window's bitmap, which holds the window contents.
Declared In
Window.h
Prototype
BitmapType *WinGetBitmap (
WinHandle winHandle
)
Parameters
Returns
A pointer to the bitmap or NULL
if winHandle
is invalid.
Comments
For on-screen 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
For update-based windows, this function works but the returned structure does not contain any bitmap data. If you try to write to or access the bitmap data, your application will crash. It is acceptable to access the other fields of the BitmapType
.
WinGetBitmapDimensions Function
Purpose
Returns a bitmap's dimensions using the draw window's active coordinate system.
Declared In
Window.h
Prototype
void WinGetBitmapDimensions ( const BitmapType *bmP
, Coord *widthP
, Coord *heightP
)
Parameters
-
→ bmP
- A pointer to the bitmap (see
BitmapType
). -
← widthP
- The width of the bitmap.
-
← heightP
- The height of the bitmap.
Returns
See Also
WinGetBounds Function
Purpose
Returns the bounds of the current draw window in display-relative coordinates.
Declared In
Window.h
Prototype
void WinGetBounds ( WinHandlewinH
, RectangleType *rP
)
Parameters
-
→ winH
- The handle to a window.
-
← rP
- A pointer to a
RectangleType
structure.
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
For update-based or transitional windows, this function returns incorrect results until the winResizedEvent
is received. It is acceptable to call this function in response to a frmUpdateEvent
or winUpdateEvent
because winResizedEvent
is sent before winUpdateEvent
.
See Also
WinGetWindowExtent()
, WinGetDrawWindowBounds()
WinGetDisplayExtent Function
Purpose
Returns the width and height of the application area of the screen.
Declared In
Window.h
Prototype
void WinGetDisplayExtent ( Coord *extentX
, Coord *extentY
)
Parameters
-
← extentX
- A pointer to the width of the display in pixels.
-
← extentY
- A pointer to the height of the display in pixels.
Returns
Comments
This function returns the dimensions of the portion of the screen that is not used by the dynamic input area or the status bar. To find out the actual screen size, call WinScreenGetAttribute()
.
WinGetDisplayWindow Function
Purpose
Returns the window handle of the display (screen) window.
Declared In
Window.h
Prototype
WinHandle WinGetDisplayWindow ( void )
Parameters
Returns
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
Returns the window handle of the current draw window.
Declared In
Window.h
Prototype
WinHandle WinGetDrawWindow ( void )
Parameters
Returns
The handle of the draw window.
See Also
WinGetDisplayWindow()
, WinGetActiveWindow()
, WinSetDrawWindow()
WinGetDrawWindowBounds Function
Purpose
Returns the bounds of the draw window.
Declared In
Window.h
Prototype
void WinGetDrawWindowBounds (
RectangleType *rP
)
Parameters
-
← rP
- A pointer to a
RectangleType
structure specifying the window bounds.
Returns
Comments
This function is equivalent to WinGetBounds()
.
Compatibility
For update-based or transitional windows, this function returns incorrect results until the winResizedEvent
is received. It is acceptable to call this function in response to a frmUpdateEvent
or winUpdateEvent
because winResizedEvent
is sent before winUpdateEvent
.
WinGetFrameType Function
Purpose
Gets the frame type for a specified window.
Declared In
Window.h
Prototype
FrameType WinGetFrameType (
const WinHandle winH
)
Parameters
Returns
A FrameType
value indicating the window's frame style.
See Also
WinGetFramesRectangle Function
Purpose
Returns the rectangle that includes a rectangle together with the specified frame around it.
Declared In
Window.h
Prototype
void WinGetFramesRectangle ( FrameTypeframe
, const RectangleType *rP
, RectangleType *obscuredRect
)
Parameters
-
→ frame
- The type of rectangle frame (see
FrameType
). -
→ rP
- A pointer to the rectangle to frame (see
RectangleType
). -
← obscuredRect
- A 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()
WinGetPixel Function
Purpose
Returns the color value of a pixel in the current draw window.
Declared In
Window.h
Prototype
IndexedColorType WinGetPixel ( Coordx
, Coordy
)
Parameters
Returns
The indexed color value of the pixel. See IndexedColorType
. A return value of 0 means that the window is on-screen, 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
This function only works if the active window is off-screen, is a legacy window, or is a transitional window.
See Also
WinGetPixelRGB Function
Purpose
Returns the RGB color values of a pixel in the current draw window.
Declared In
Window.h
Prototype
status_t WinGetPixelRGB ( Coordx
, Coordy
, RGBColorType *rgpP
)
Parameters
-
→ x
- A pointer to the x coordinate of a pixel.
-
→ y
- A pointer to the y coordinate of a pixel.
-
← rgbP
- The RGB color components of the pixel.
Returns
-
errNone
- Success.
-
sysErrParamErr
- When the draw window is on-screen, when the
x
ory
arguments are < 0, or when they are outside the bounds of the draw window.
Comments
This function only works if the draw window is off-screen.
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 within the current draw window.
WinGetSupportedDensity Function
Purpose
Enumerates the various display densities supported by the rendering system.
Declared In
Window.h
Prototype
status_t WinGetSupportedDensity (
uint16_t *densityP
)
Parameters
-
↔ densityP
- A 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
-
errNone
- Success.
-
sysErrParamErr
- The value you supplied in
*
densityP
isn't a supported density and isn't zero.
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 rendering system. These densities are not necessarily supported by the underlying hardware. A device 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 CmnBitmapTypes.h
; see the DensityType
enum. Only those values supported by a given device will be returned by WinGetSupportedDensity()
. For example, on a device 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 rendering system supports pixel-doubling low-density data for a double-density destination, and the rendering system 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
.
WinGetWindowBounds Macro
Purpose
Calls WinGetDrawWindowBounds()
.
Declared In
Window.h
Prototype
#define WinGetWindowBounds ( rP )
Parameters
-
← rP
- A pointer to a
RectangleType
structure specifying the window bounds.
Returns
WinGetWindowExtent Function
Purpose
Returns the width and height of the current draw window.
Declared In
Window.h
Prototype
void WinGetWindowExtent ( Coord *extentX
, Coord *extentY
)
Parameters
-
← extentX
- A pointer to the width in pixels of the draw window.
-
← extentY
- A pointer to the height in pixels of the draw window.
Returns
Compatibility
For update-based or transitional windows, this function returns incorrect results until the winResizedEvent
is received. It is acceptable to call this function in response to a frmUpdateEvent
or winUpdateEvent
because winResizedEvent
is sent before winUpdateEvent
.
See Also
WinGetBounds()
, WinGetWindowFrameRect()
WinGetWindowFlags Function
Purpose
Returns the flags used when the window was created.
Declared In
Window.h
Prototype
WinFlagsType WinGetWindowFlags (
WinHandle winHandle
)
Parameters
Returns
An integer containing the WinFlagsType
flags that were set when this window was created.
See Also
WinCreateWindowWithConstraints()
WinGetWindowFrameRect Function
Purpose
Returns 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 ( WinHandlewinHandle
, RectangleType *r
)
Parameters
-
→ winHandle
- The handle to the window whose coordinates are desired.
-
← r
- A pointer to the coordinates of the window (see
RectangleType
).
Returns
Compatibility
For update-based or transitional windows, this function returns incorrect results until the winResizedEvent
is received. It is acceptable to call this function in response to a frmUpdateEvent
or winUpdateEvent
because winResizedEvent
is sent before winUpdateEvent
.
See Also
WinIndexToRGB Function
Purpose
Converts an index in the currently active color table to an RGB value.
Declared In
Window.h
Prototype
void WinIndexToRGB ( IndexedColorTypei
, RGBColorType *rgbP
)
Parameters
-
→ i
- A color index value. See
IndexedColorType
. -
← rgbP
- A pointer to an RGB color value corresponding to the index value
i
. SeeRGBColorType
.
Returns
See Also
WinInvalidateRect Function
Purpose
Requests an update for a portion of a window.
Declared In
Window.h
Prototype
void WinInvalidateRect ( WinHandlewindow
, const RectangleType*dirtyRect
)
Parameters
-
→ window
- A handle to an on-screen window.
-
→ dirtyRect
- The bounds given in active coordinates of the area that needs to be redrawn (see
RectangleType
).
Returns
Comments
This function generates a winUpdateEvent
. If the window is update-based, the dirtyRect
is added to a pending update queue. All updates in this queue are sent during a single winUpdateEvent
the next time through the event loop.
If the window is a transitional window, the update event for dirtyRect
is enqueued immediately.
If the window is off-screen, this function has no effect.
See Also
WinInvalidateRectFunc()
, WinInvalidateWindow()
WinInvalidateRectFunc Function
Purpose
Requests an update for a portion of the window, specifying a function that can handle the update if it is feasible.
Declared In
Window.h
Prototype
void WinInvalidateRectFunc ( WinHandlewindow
, const RectangleType*dirtyRect
, winInvalidateFuncfunc
, void*state
)
Parameters
-
→ window
- A handle to the window.
-
→ dirtyRect
- The bounds given in active coordinates of the area that needs to be redrawn (see
RectangleType
). -
→ func
- A
winInvalidateFunc()
callback function. The system calls this function to perform the redraw. -
→ state
- Any data that needs to be passed to the
func
.
Returns
Comments
This function is an optimization on invalidating a window that saves the application from having to wait for a frmUpdateEvent
in certain circumstances. The supplied winInvalidateFunc()
is called instead of performing an update under the following conditions:
- The window is a transitional window. In this case,
winInvalidateFunc()
is called directly fromWinInvalidateRectFunc()
. - If this is the only update in the pending update queue the next time through the event loop, the Window Manager calls
winInvalidateFunc()
directly instead of generating awinUpdateEvent
.
If any other portion of the window is dirty for an update-based window, then the winUpdateEvent
is generated as usual.
See Also
WinInvalidateRect()
, WinInvalidateWindow()
WinInvalidateWindow Function
Purpose
Requests that an entire window be redrawn.
Declared In
Window.h
Prototype
void WinInvalidateWindow (
WinHandle window
)
Parameters
Returns
Comments
This function generates a winUpdateEvent
for the window. If the window is update-based, it is added to a pending update queue. All updates in this queue are sent during a single winUpdateEvent
the next time through the event loop.
If the window is a transitional window, the update event is enqueued immediately.
If the window is off-screen, this function has no effect.
See Also
WinInvalidateRect()
, WinInvalidateRectFunc()
WinModal Function
Purpose
Returns true
if the specified window is modal.
Declared In
Window.h
Prototype
Boolean WinModal (
WinHandle winHandle
)
Parameters
Returns
true
if the window is modal, otherwise false
.
See Also
FrmAlert()
, FrmCustomAlert()
, FrmDoDialog()
WinPalette Function
Purpose
Sets or retrieves the palette for the draw window.
Declared In
Window.h
Prototype
status_t WinPalette ( uint8_toperation
, int16_tstartIndex
, uint16_tpaletteEntries
, RGBColorType*tableP
)
Parameters
-
→ operation
- 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. Use only for off-screen windows. -
winPaletteSetToDefault
- Set the palette to the default system palette. Use only for off-screen windows.
-
→ 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
- The 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
-
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.
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.
When the palette is changed, this function broadcasts the sysNotifyDisplayChangeEvent
to notify any interested observer that the color palette has changed.
Palette changes affect only future drawing. The colors of elements already on the screen do not change. It is strongly recommended that you set the palette before you do any drawing.
Compatibility
Earlier releases of Palm OS supported 1, 2, 4, and 8 bit per pixel grayscale and 8 and 16-bit color at the hardware level. Palm OS Cobalt removes hardware support for all but 16-bit color. All previously supported color depths are emulated for compatibility.
TIP: If you previously set your application to run in 8-bit color on a 16-bit device for better performance, you will now experience worse performance because 8-bit color is emulated.
WinRequestFocus Function
Purpose
Asks that the input focus be given to the specified window.
Declared In
Window.h
Prototype
status_t WinRequestFocus ( WinHandlewinHandle
, uint32_tflags
)
Parameters
Returns
Comments
The system satisfies the request asynchronously. At some point in the future, the application receives a winFocusGainedEvent
to inform you that you have been granted focus. The application might not be granted input focus if a window in a higher layer within another thread requests input focus at the same time.
The input focus can only be set for focusable windows. Menus, pop--up lists, and the input area do not use focusable windows.
See Also
WinRGBToIndex Function
Purpose
Converts 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
The index of the closest matching color in the CLUT.
Comments
The number of colors supported is hardware-dependent. The number of possible RGB colors may exceed the number of supported colors. 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.
See Also
WinIndexToRGB()
, WinScreenMode()
WinScaleCoord Function
Purpose
Converts a single coordinate from the standard coordinate system to the active coordinate system.
Declared In
Window.h
Prototype
Coord WinScaleCoord ( Coordcoord
, Booleanceiling
)
Parameters
-
→ coord
- A coordinate in the standard coordinate system.
-
→ ceiling
- Pass
true
to round up,false
to truncate the fractional part when scaling.
Returns
The coordinate scaled to the active coordinate system.
Comments
This function converts a coordinate by multiplying it by the coordinate scaling factor. 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)).
If the active coordinate system is kCoordinatesStandard
, the returned coordinate is equal to the supplied coordinate.
See Also
WinScalePoint()
, WinScaleRectangle()
, WinUnscaleCoord()
, WinScaleCoordNativeToActive()
WinScaleCoordNativeToActive Function
Purpose
Converts a single coordinate from the device's native coordinate system to the active coordinate system.
Declared In
Window.h
Prototype
Coord WinScaleCoordNativeToActive ( Coordcoord
, Booleanceiling
)
Parameters
-
→ coord
- A coordinate in the native coordinate system.
-
→ ceiling
- Pass
true
to round up,false
to truncate the fractional part when scaling.
Returns
The coordinate scaled to the active coordinate system.
Comments
This function converts a coordinate by multiplying it by the coordinate scaling factor. 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)).
If the active coordinate system is kCoordinatesNative
, the returned coordinate is equal to the supplied coordinate.
See Also
WinScalePoint Function
Purpose
Converts a point from the standard coordinate system to the active coordinate system.
Declared In
Window.h
Prototype
void WinScalePoint ( PointType*pointP
, Booleanceiling
)
Parameters
-
↔ pointP
- A 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
Comments
This function converts a point by multiplying its x and y coordinates by the coordinate scaling factor. 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)).
If the active coordinate system is kCoordinatesStandard
, pointP
is not changed by this function.
See Also
WinConvertPoint()
, WinScaleCoord()
, WinScaleRectangle()
, WinUnscalePoint()
WinScaleRectangle Function
Purpose
Converts a rectangle from the standard coordinate system to the active coordinate system.
Declared In
Window.h
Prototype
void WinScaleRectangle (
RectangleType *rectP
)
Parameters
-
↔ rectP
- A 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
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.
See Also
WinScaleCoord()
, WinScalePoint()
, WinUnscaleRectangle()
WinScreenGetAttribute Function
Purpose
Obtains various attributes of the screen.
Declared In
Window.h
Prototype
status_t WinScreenGetAttribute ( WinScreenAttrTypeselector
, uint32_t*attrP
)
Parameters
-
→ selector
- One of the following:
-
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.
-
← attrP
- A pointer to a
uint32_t
into which the specified attribute value is placed by this function.
Returns
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 devices with different screen resolutions.
WinScreenLock Function
Purpose
"Locks" 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_t *WinScreenLock (
WinLockInitType initMode
)
Parameters
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
You can only call this function on a legacy or transitional window. Calling this function when the active window is update-based has no effect.
WinScreenMode Function
Purpose
Sets or returns display parameters, including display geometry, bit depth, and color support.
Declared In
Window.h
Prototype
status_t WinScreenMode ( WinScreenModeOperationoperation
, uint32_t*widthP
, uint32_t*heightP
, uint32_t*depthP
, Boolean*enableColorP
)
Parameters
-
→ 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 bit field 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. -
↔ widthP
- A 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
- A 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
- A 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
-
errNone
- Success.
-
sysErrParamErr
- An invalid argument was specified.
-
memErrNotEnoughSpace
- There is not enough memory to perform the requested operation.
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 36.1 summarizes parameter usage for each operation this function performs.
Table 36.1 Use of parameters to WinScreenMode function
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.
Avoid bit depths of 1, 2, or 4 bits per pixel. They are supported, but they cause rendering to be much slower on Palm OS Cobalt.
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 drawing 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 off-screen window, the color translation tables are out of sync.
To work around this system limitation, developers should change the bit depth first, then create any off-screen windows.
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.

Compatibility
In earlier releases of Palm OS, this function supported two more operations: winScreenModeSet
and winScreenModeSetToDefaults
. In Palm OS Cobalt, WinScreenMode()
does not support these two operations.
See Also
WinScreenUnlock Function
Purpose
Unlocks the screen and updates 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
You can only call this function on a legacy or transitional window. Calling this function when the active window is update-based has no effect.
See Also
WinScrollRectangle Function
Purpose
Scrolls a rectangle in the draw window.
Declared In
Window.h
Prototype
void WinScrollRectangle ( const RectangleType*rP
, WinDirectionTypedirection
, Coorddistance
, RectangleType*vacatedP
)
Parameters
-
→ rP
- A pointer to the rectangle to scroll.
-
→ direction
- The direction to scroll (
winUp
,winDown
,winLeft
, orwinRight
). -
→ distance
- The distance to scroll in pixels.
-
← vacatedP
- A 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.
Compatibility
Use this function only in legacy applications that contain only legacy windows. Palm OS Cobalt native applications should use WinScrollRectangleAsync()
.
WinScrollRectangleAsync Function
Purpose
Scrolls a window by generating an update event.
Declared In
Window.h
Prototype
status_t WinScrollRectangleAsync ( WinHandlewinHandle
, const RectangleType*rP
, Coorddx
, Coorddy
)
Parameters
-
→ winHandle
- The window to scroll.
-
→ rP
- A pointer to the rectangle to scroll.
-
→ dx
- The amount by which to scroll horizontally. A negative value means scroll to the left.
-
→ dy
- The amount by which to scroll vertically. A negative amount means scroll to the top.
Returns
Comments
This function differs from WinScrollRectangle()
not only by how you specify the direction to scroll, but also by how scrolling occurs. This function marks the area as invalid and then triggers a winUpdateEvent
with the region that needs to be redrawn.
For off-screen windows, this merely performs a copy.
WinSetActiveWindow Function
Purpose
Makes 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, which generates the following sequence of events:
- A
winExitEvent
specifying the current window as the exit window andwinHandle
as the new window. - A
winEnterEvent
specifying the current window as the exit window andwinHandle
as the new window. - The window is enabled.
- If
winHandle
should be able to receivekeyDownEvents
, input focus is requested forwinHandle
.At some point later on, if the system grants input focus to
winHandle
, thewinFocusLostEvent
is sent to the event queue of the thread that contains the window that currently has input focus. Then awinFocusGainedEvent
specifyingwinHandle
are is sent to the current thread's event queue.
All user input is directed to the active window.
See Also
WinGetActiveWindow()
, EvtGetEvent()
, WinSetDrawWindow()
, WinRequestFocus()
WinSetBounds Function
Purpose
Sets the bounds of the window to display-relative coordinates.
Declared In
Window.h
Prototype
void WinSetBounds ( WinHandlewinHandle
, const RectangleType*rP
)
Parameters
-
→ winHandle
- A handle for the window for which to set the bounds.
-
→ rP
- A pointer to a rectangle to use for bounds.
Returns
Compatibility
Visible windows and transitional or update-based windows cannot have their bounds modified. You can only modify the bounds of a legacy or an off-screen window. For update-based or transitional windows, you specify the size requirements (or constraints) when you create the window. The system determines what size to make it, and then sends the winResizedEvent
.
See Also
WinSetConstraints Function
Purpose
Declared In
Window.h
Prototype
status_t WinSetConstraints ( WinHandlewinHandle
, const WinConstraintsType*constraints
)
Parameters
-
→ winHandle
- A handle to the window.
-
→ constraints
- A
WinConstraintsType
structure specifying the position and minimum, preferred, and maximum sizes for the window.
Returns
Comments
You can use this to change a window's size constraints. Calling this function causes the Window Manager to re-evaluate the window's size. Eventually, a winResizedEvent
and a winUpdateEvent
are generated.
See Also
WinCreateWindowWithConstraints()
WinSetDrawWindow Function
Purpose
Sets the draw window. (All drawing operations are relative to the draw window.)
Declared In
Window.h
Prototype
WinHandle WinSetDrawWindow (
WinHandle winHandle
)
Parameters
Returns
Comments
Do not call this function in response to a winUpdateEvent
. You cannot change the draw window during an update.
See Also
WinGetDrawWindow()
, WinSetActiveWindow()
WinSetWindowBounds Macro
Purpose
Calls WinSetBounds()
.
Declared In
Window.h
Prototype
#define WinSetWindowBounds (winH
,rP
)
Parameters
-
→ winHandle
- A
WinHandle
for the window for which to set the bounds. -
→ rP
- A pointer to a
RectangleType
to use for bounds.
Returns
WinStartThreadUI Function
Purpose
Starts the user interface context for a thread.
Declared In
Window.h
Prototype
status_t WinStartThreadUI ( void )
Parameters
Returns
errNone
upon success, or sysErrNoFreeRAM
if an error occurs.
Comments
Call this function from a thread spawned in your program if you want that thread to display a user interface. All of the windows that you create to display inside of this thread must be updated-based windows.
Nested calls to WinStartThreadUI()
are allowed.
See Also
WinUnscaleCoord Function
Purpose
Converts a single coordinate from the active coordinate system to the standard coordinate system.
Declared In
Window.h
Prototype
Coord WinUnscaleCoord ( Coordcoord
, Booleanceiling
)
Parameters
-
→ coord
- A coordinate in the active coordinate system.
-
→ ceiling
- Pass
true
to round up,false
to truncate the fractional part when scaling.
Returns
The coordinate scaled to the standard coordinate system.
Comments
This function converts a coordinate by dividing it by the coordinate scaling factor. 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)).
If the active coordinate system is kCoordinatesStandard
, the returned coordinate is equal to the supplied coordinate.
See Also
WinScaleCoord()
, WinUnscalePoint()
, WinUnscaleRectangle()
WinUnscalePoint Function
Purpose
Converts a point from the active coordinate system to the standard coordinate system.
Declared In
Window.h
Prototype
void WinUnscalePoint ( PointType*pointP
, Booleanceiling
)
Parameters
-
↔ pointP
- A 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
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. 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)).
If the active coordinate system is kCoordinatesStandard
, pointP
is not changed by this function.
See Also
WinScalePoint()
, WinUnscaleCoord()
, WinUnscaleRectangle()
WinUnscaleRectangle Function
Purpose
Converts a rectangle from the active coordinate system to the standard coordinate system.
Declared In
Window.h
Prototype
void WinUnscaleRectangle (
RectangleType *rectP
)
Parameters
-
↔ rectP
- A 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
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.
See Also
WinScaleRectangle()
, WinUnscaleCoord()
, WinUnscalePoint()
WinValidateHandle Function
Purpose
Declared In
Window.h
Prototype
Boolean WinValidateHandle (
WinHandle winHandle
)
Parameters
Returns
true
if the specified handle references a window that exists, false
otherwise.
Comments
For debugging purposes only. Do not include this function in commercial applications.
See Also
FrmValidatePtr()
, FrmRemoveObject()
WinWindowToDisplayPt Function
Purpose
Converts a window-relative coordinate to a display-relative coordinate.
Declared In
Window.h
Prototype
void WinWindowToDisplayPt ( Coord*x
, Coord*y
)
Parameters
Returns
Comments
The coordinate passed is assumed to be relative to the draw window.
See Also
Window Drawing Functions and Macros
This section lists and describes drawing-related functions implemented in the Window Manager. All of these functions work as expected in Palm OS Cobalt, but they are considered obsolete and replaced by the "Graphics Context Reference" drawing functions. The two types of drawing functions maintain separate draw states and should not be mixed. Use either the Win.
.. drawing functions or the Gc.
.. drawing functions.
WinClipRectangle Function
Purpose
Truncates 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
- A pointer to a
RectangleType
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()
.
Compatibility
Do not use this function if you are using the graphics context APIs.
See Also
WinCopyRectangle()
, WinDrawRectangle()
, WinEraseRectangle()
, WinGetClip()
WinCopyRectangle Function
Purpose
Copies a rectangular region from one place to another (either between windows or within a single window).
Declared In
Window.h
Prototype
void WinCopyRectangle ( WinHandlesrcWin
, WinHandledstWin
, const RectangleType *srcRect
, CoorddestX
, CoorddestY
, WinDrawOperationmode
)
Parameters
-
→ srcWin
- The window from which the rectangle is copied. If
NULL
, use the draw window. -
→ dstWin
- The window to which the rectangle is copied. If
NULL
, use the draw window. -
→ srcRect
- The bounds of the region to copy (see
RectangleType
). -
→ destX
- The left bound of the rectangle in destination window.
-
→ destY
- The top bound of the rectangle in destination window.
-
→ mode
- Must be set to the
winPaint
transfer mode.
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.
This function does not work if the source window is an update-based window. It is best not to use this function to copy between two on-screen rectangles. It is better to copy your data to an off-screen window to capture data and then copy that onto the screen as needed.
Compatibility
In earlier releases of Palm OS, this function used the transfer mode passed as a parameter. In Palm OS Cobalt, you must pass winPaint
as the transfer mode.
See Also
WinDrawBitmap Function
Purpose
Draws a bitmap at the given coordinates in winPaint
mode (see WinDrawOperation
for mode details).
Declared In
Window.h
Prototype
void WinDrawBitmap ( BitmapPtrbitmapP
, Coordx
, Coordy
)
Parameters
-
→ bitmapP
- A 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. This color conversion is slow and not recommended.
Compatibility
Do not use this function in conjunction with the graphics context. Use WinDrawBitmapHandle()
, GcDrawBitmapAt()
, GcDrawRawBitmapAt()
, or GcPaintBitmap()
instead.
See Also
WinDrawBitmapHandle Function
Purpose
Draws a bitmap at the coordinates specified, using a GcBitmapHandle
.
Declared In
GcRender.h
Prototype
void WinDrawBitmapHandle ( GcBitmapHandlebitmapHandle
, Coordx
, Coordy
)
Parameters
-
→ bitmapHandle
- The bitmap Use
FrmGetBitmapHandle()
orGcLoadBitmap()
to obtain aGcBitmapHandle
to a bitmap. -
→ x
- The x coordinate of the top-left corner.
-
→ y
- The y coordinate of the top-left corner.
Returns
Comments
A GcBitmapHandle
stores a bitmap that has been converted to draw to the screen more efficiently than a BitmapType
. Use this function if you want the efficiency of the GcBitmapHandle
type but do not want to convert all of your drawing code to use the new drawing model.
This function behaves exactly like WinDrawBitmap()
except that it ignores the current scaling mode. Scaling for GcBitmapHandle
bitmaps is controlled when the GcBitmapHandle
is created.
WinDrawChar Function
Purpose
Draws the specified character in the draw window.
Declared In
Window.h
Prototype
void WinDrawChar ( wchar32_ttheChar
, Coordx
, Coordy
)
Parameters
-
→ theChar
- The character to draw. This may be either a single-byte character or a multi-byte character.
-
→ x
- The x coordinate of the location where the character is to be drawn (left bound).
-
→ y
- The 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
The winInvert
drawing mode does not work when you draw text. If you try to use it, nothing is drawn to the screen.
Do not use this function in conjunction with the graphics context APIs. Use GcDrawTextAt()
instead. Note that GcDrawTextAt()
uses the y value as the font baseline whereas WinDrawChar()
uses the y value as the top of the character.
See Also
WinDrawChars()
, WinDrawInvertedChars()
, WinDrawTruncChars()
, WinEraseChars()
, WinInvertChars()
, WinPaintChars()
WinDrawChars Function
Purpose
Draws the specified characters in the draw window.
Declared In
Window.h
Prototype
void WinDrawChars ( const char *chars
, int16_tlen
, Coordx
, Coordy
)
Parameters
-
→ chars
- A pointer to the characters to draw.
-
→ len
- The length in bytes of the characters to draw.
-
→ x
- The x coordinate of the first character to draw (left bound).
-
→ y
- The 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
.
Compatibility
The winInvert
drawing mode does not work when you draw text. If you try to use it, nothing is drawn to the screen.
Do not use this function in conjunction with the graphics context APIs. Use GcDrawTextAt()
instead. Note that GcDrawTextAt()
uses the y value as the font baseline whereas WinDrawChars()
uses the y value as the top of the character.
See Also
WinDrawChar()
, WinDrawInvertedChars()
, WinDrawTruncChars()
, WinEraseChars()
, WinInvertChars()
, WinPaintChar()
WinDrawGrayLine Function
Purpose
Draws a dashed line in the draw window.
Declared In
Window.h
Prototype
void WinDrawGrayLine ( Coordx1
, Coordy1
, Coordx2
, Coordy2
)
Parameters
-
→ x1
- The x coordinate of line start point.
-
→ y1
- The y coordinate of line start point.
-
→ x2
- The x coordinate of line endpoint.
-
→ y2
- The 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.
Compatibility
Do not use this function in conjunction with the graphics context APIs. Use GcLineTo()
instead.
See Also
WinDrawLine()
, WinEraseLine()
, WinFillLine()
, WinInvertLine()
, WinPaintLine()
, WinPaintLines()
WinDrawGrayRectangleFrame Function
Purpose
Draws a gray rectangular frame in the draw window.
Declared In
Window.h
Prototype
void WinDrawGrayRectangleFrame ( FrameTypeframe
, const RectangleType *rP
)
Parameters
-
→ frame
- The type of frame to draw (see
FrameType
). -
→ rP
- A pointer to the rectangle to frame (see
RectangleType
).
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.
Compatibility
The winInvert
and winSwap
drawing modes do not work when you draw a rectangle frame or unfilled rectangle. Nothing is drawn to the screen.
Do not use this function in conjunction with the graphics context APIs. Use GcRect()
instead. Note that GcRect()
specifies a rectangle's bounds differently than a RectangleType
structure does.
See Also
WinDrawRectangleFrame()
, WinEraseRectangleFrame()
, WinGetFramesRectangle()
, WinInvertRectangleFrame()
, WinPaintRectangleFrame()
WinDrawInvertedChars Function
Purpose
Draws the specified characters inverted (background color) in the draw window.
Declared In
Window.h
Prototype
void WinDrawInvertedChars ( const char *chars
, int16_tlen
, Coordx
, Coordy
)
Parameters
-
→ chars
- A pointer to the characters to draw.
-
→ len
- The length in bytes of the characters to draw.
-
→ x
- The x coordinate of the first character to draw (left bound).
-
→ y
- The y coordinate of the first character to draw (top bound).
Returns
Compatibility
This function is deprecated in Palm OS Cobalt.
See Also
WinDrawChar()
, WinDrawChars()
, WinDrawTruncChars()
, WinEraseChars()
, WinInvertChars()
, WinPaintChar()
, WinPaintChars()
WinDrawLine Function
Purpose
Draws a line in the draw window using the current foreground color.
Declared In
Window.h
Prototype
void WinDrawLine ( Coordx1
, Coordy1
, Coordx2
, Coordy2
)
Parameters
-
→ x1
- The x coordinate of line start point.
-
→ y1
- The y coordinate of line start point.
-
→ x2
- The x coordinate of line endpoint.
-
→ y2
- The 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
.
Compatibility
Do not use this function in conjunction with the graphics context APIs. Use GcLineTo()
instead.
See Also
WinDrawGrayLine()
, WinEraseLine()
, WinFillLine()
, WinInvertLine()
, WinPaintLine()
, WinPaintLines()
WinDrawPixel Function
Purpose
Draws a pixel in the draw window using the current foreground color.
Declared In
Window.h
Prototype
void WinDrawPixel ( Coordx
, Coordy
)
Parameters
Returns
Compatibility
Do not use this function in conjunction with the graphics context APIs. Use GcLineTo()
instead.
See Also
WinErasePixel()
, WinInvertPixel()
, WinPaintPixel()
, WinPaintPixels()
WinDrawRectangle Function
Purpose
Draws a rectangle in the draw window using the current foreground color.
Declared In
Window.h
Prototype
void WinDrawRectangle ( const RectangleType *rP
, uint16_tcornerDiam
)
Parameters
-
→ rP
- A pointer to the rectangle to draw (see
RectangleType
). -
→ cornerDiam
- The 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
.
Compatibility
Do not use this function in conjunction with the graphics context APIs. Use GcRect()
instead. Note that GcRect()
specifies a rectangle's bounds differently than a RectangleType
structure does.
See Also
WinEraseRectangle()
, WinFillRectangle()
, WinInvertRectangle()
WinDrawRectangleFrame Function
Purpose
Draws a rectangular frame in the draw window using the current foreground color.
Declared In
Window.h
Prototype
void WinDrawRectangleFrame ( FrameTypeframe
, const RectangleType *rP
)
Parameters
-
→ frame
- The type of frame to draw (see
FrameType
). -
→ rP
- A pointer to the rectangle to frame (see
RectangleType
).
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
.
Compatibility
The winInvert
and winSwap
drawing modes do not work when you draw a rectangle frame or unfilled rectangle. Nothing is drawn to the screen.
Do not use this function in conjunction with the graphics context APIs. Use GcRect()
instead. Note that GcRect()
specifies a rectangle's bounds differently than a RectangleType
structure does.
See Also
WinDrawGrayRectangleFrame()
, WinEraseRectangleFrame()
, WinGetFramesRectangle()
, WinInvertRectangleFrame()
WinDrawTruncChars Function
Purpose
Draws 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_tlen
, Coordx
, Coordy
, CoordmaxWidth
)
Parameters
-
→ chars
- A pointer to the characters to draw.
-
→ len
- The length in bytes of the characters to draw.
-
→ x
- The x coordinate of the first character to draw (left bound).
-
→ y
- The y coordinate of the first character to draw (top bound).
-
→ maxWidth
- The 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.
This function differs from WinPaintTruncChars()
in that it always uses winPaint
. WinPaintTruncChars()
uses the current draw state transfer mode.
Compatibility
The winInvert
drawing mode does not work when you draw text. Nothing is drawn to the screen.
Do not use this function in conjunction with the graphics context APIs. Use GcDrawTextAt()
instead. Note that GcDrawTextAt()
uses the y value as the font baseline whereas WinDrawTruncChars()
uses the y value as the top of the character.
See Also
WinDrawChar()
, WinDrawChars()
, WinDrawInvertedChars()
, WinEraseChars()
, WinInvertChars()
, WinPaintChar()
, WinPaintChars()
, WinPaintTruncChars()
WinEraseChars Function
Purpose
Erases the specified characters in the draw window.
Declared In
Window.h
Prototype
void WinEraseChars ( const char *chars
, int16_tlen
, Coordx
, Coordy
)
Parameters
-
→ chars
- A pointer to the characters to erase.
-
→ len
- The length in bytes of the characters to erase.
-
→ x
- The x coordinate of the first character to erase (left bound).
-
→ y
- The 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.
Compatibility
Do not use this function in conjunction with the graphics context APIs. Use GcDrawTextAt()
instead. Note that GcDrawTextAt()
uses the y value as the font baseline whereas WinEraseChars()
uses the y value as the top of the character.
See Also
WinDrawChar()
, WinDrawChars()
, WinDrawInvertedChars()
, WinDrawTruncChars()
, WinInvertChars()
, WinPaintChar()
, WinPaintChars()
WinEraseLine Function
Purpose
Draws a line in the draw window using the current background color.
Declared In
Window.h
Prototype
void WinEraseLine ( Coordx1
, Coordy1
, Coordx2
, Coordy2
)
Parameters
-
→ x1
- The x coordinate of line start point.
-
→ y1
- The y coordinate of line start point.
-
→ x2
- The x coordinate of line endpoint.
-
→ y2
- The y coordinate of line endpoint.
Returns
Compatibility
Do not use this function in conjunction with the graphics context APIs. Use GcLineTo()
instead.
See Also
WinDrawGrayLine()
, WinDrawLine()
, WinFillLine()
, WinInvertLine()
, WinPaintLine()
, WinPaintLines()
WinErasePixel Function
Purpose
Draws a pixel in the draw window using the current background color.
Declared In
Window.h
Prototype
void WinErasePixel ( Coordx
, Coordy
)
Parameters
Returns
Compatibility
Do not use this function in conjunction with the graphics context APIs. Use GcLineTo()
instead.
See Also
WinDrawPixel()
, WinInvertPixel()
, WinPaintPixel()
, WinPaintPixels()
WinEraseRectangle Function
Purpose
Draws a rectangle in the draw window using the current background color.
Declared In
Window.h
Prototype
void WinEraseRectangle ( const RectangleType *rP
, uint16_tcornerDiam
)
Parameters
-
→ rP
- A pointer to the rectangle to erase (see
RectangleType
). -
→ cornerDiam
- The 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.
Compatibility
Do not use this function in conjunction with the graphics context APIs. Use GcRect()
instead. Note that GcRect()
specifies a rectangle's bounds differently than a RectangleType
structure does.
See Also
WinDrawRectangle()
, WinFillRectangle()
, WinInvertRectangle()
, WinPaintRectangle()
WinEraseRectangleFrame Function
Purpose
Draws a rectangular frame in the draw window using the current background color.
Declared In
Window.h
Prototype
void WinEraseRectangleFrame ( FrameTypeframe
, const RectangleType *rP
)
Parameters
-
→ frame
- The type of frame to draw (see
FrameType
). -
→ rP
- A pointer to the rectangle to frame (see
RectangleType
).
Returns
Compatibility
Do not use this function in conjunction with the graphics context APIs. Use GcRect()
instead.
See Also
WinDrawGrayRectangleFrame()
, WinDrawRectangleFrame()
, WinGetFramesRectangle()
, WinInvertRectangleFrame()
, WinPaintRectangleFrame()
WinEraseWindow Function
Purpose
Erases 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()
.
Compatibility
Do not use this function in conjunction with the graphics context APIs. Use GcPaint()
instead.
WinFillLine Function
Purpose
Fills a line in the draw window with the current pattern.
Declared In
Window.h
Prototype
void WinFillLine ( Coordx1
, Coordy1
, Coordx2
, Coordy2
)
Parameters
-
→ x1
- The x coordinate of line start point.
-
→ y1
- The y coordinate of line start point.
-
→ x2
- The x coordinate of line endpoint.
-
→ y2
- The y coordinate of line endpoint.
Returns
Comments
You can set the current pattern with WinSetPattern()
.
Compatibility
Do not use this function in conjunction with the graphics context APIs. Use GcLineTo()
instead.
See Also
WinDrawGrayLine()
, WinDrawLine()
, WinEraseLine()
, WinInvertLine()
, WinPaintLine()
, WinPaintLines()
WinFillRectangle Function
Purpose
Draws a rectangle in the draw window with current pattern.
Declared In
Window.h
Prototype
void WinFillRectangle ( const RectangleType *rP
, uint16_tcornerDiam
)
Parameters
-
→ rP
- A pointer to the rectangle to draw (see
RectangleType
). -
→ cornerDiam
- The 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.
Compatibility
Do not use this function in conjunction with the graphics context APIs. Use GcRect()
instead. Note that GcRect()
specifies a rectangle's bounds differently than a RectangleType
structure does.
See Also
WinDrawRectangle()
, WinEraseRectangle()
, WinInvertRectangle()
, WinPaintRectangle()
WinGetClip Function
Purpose
Returns the clipping rectangle of the draw window.
Declared In
Window.h
Prototype
void WinGetClip (
RectangleType *rP
)
Parameters
-
← rP
- A pointer to a structure to hold the clipping bounds (see
RectangleType
).
Returns
See Also
WinGetCoordinateSystem Function
Purpose
Declared In
Window.h
Prototype
uint16_t WinGetCoordinateSystem ( void )
Parameters
Returns
A value representing the current coordinate system. See "Coordinate System Constants" for the values that this function can return.
Comments
Use this function to determine the active window 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
Do not use this function in conjunction with the graphics context APIs. It returns the coordinate system of the window rather than the coordinate system of the graphics context.
WinGetPattern Function
Purpose
Returns the current fill pattern.
Declared In
Window.h
Prototype
void WinGetPattern (
CustomPatternType *patternP
)
Parameters
-
← patternP
- The buffer where the current pattern is returned (see
CustomPatternType
).
Returns
Comments
The fill pattern is used by WinFillLine()
and WinFillRectangle()
.
This function returns the pattern data stored in the drawing state. The drawing state only has pattern data if the pattern field itself is set to customPattern
. Therefore, it's a good idea to use WinGetPatternType()
instead of this function on systems that support WinGetPatternType()
.
See Also
WinGetPatternType Function
Purpose
Returns the current pattern type.
Declared In
Window.h
Prototype
PatternType WinGetPatternType ( void )
Parameters
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()
.
See Also
WinGetScalingMode Function
Purpose
Gets the current scaling mode.
Declared In
Window.h
Prototype
uint32_t WinGetScalingMode ( void )
Parameters
Returns
One of the Scaling Mode Constants.
See Also
WinInvertChars Function
Purpose
Inverts the specified characters in the draw window.
Declared In
Window.h
Prototype
void WinInvertChars ( const char*chars
, int16_tlen
, Coordx
, Coordy
)
Parameters
-
→ chars
- A pointer to the characters to invert.
-
→ len
- The length in bytes of the characters to invert.
-
→ x
- The x coordinate of the first character to invert (left bound).
-
→ y
- The y coordinate of the first character to invert (top bound).
Returns
Compatibility
This function is deprecated in Palm OS Cobalt.
See Also
WinDrawChar()
, WinDrawChars()
, WinDrawInvertedChars()
, WinDrawTruncChars()
, WinEraseChars()
, WinPaintChar()
, WinPaintChars()
WinInvertLine Function
Purpose
Inverts a line in the draw window (using the WinDrawOperation
winInvert
).
Declared In
Window.h
Prototype
void WinInvertLine ( Coordx1
, Coordy1
, Coordx2
, Coordy2
)
Parameters
-
→ x1
- The x coordinate of line start point.
-
→ y1
- The y coordinate of line start point.
-
→ x2
- The x coordinate of line endpoint.
-
→ y2
- The y coordinate of line endpoint.
Returns
Compatibility
This function is deprecated in Palm OS Cobalt.
See Also
WinDrawGrayLine()
, WinDrawLine()
, WinEraseLine()
, WinFillLine()
, WinPaintLine()
, WinPaintLines()
WinInvertPixel Function
Purpose
Inverts a pixel in the draw window (using the WinDrawOperation
winInvert
).
Declared In
Window.h
Prototype
void WinInvertPixel ( Coordx
, Coordy
)
Parameters
Returns
Compatibility
This function is deprecated in Palm OS Cobalt.
See Also
WinDrawPixel()
, WinErasePixel()
, WinPaintPixel()
, WinPaintPixels()
WinInvertRectangle Function
Purpose
Inverts a rectangle in the draw window (using the WinDrawOperation
winInvert
).
Declared In
Window.h
Prototype
void WinInvertRectangle ( const RectangleType*rP
, uint16_tcornerDiam
)
Parameters
-
→ rP
- A pointer to the rectangle to invert (see
RectangleType
). -
→ cornerDiam
- The radius of rounded corners. Specify zero for square corners.
Returns
Compatibility
This function is deprecated in Palm OS Cobalt.
See Also
WinDrawRectangle()
, WinEraseRectangle()
, WinFillRectangle()
, WinPaintRectangle()
WinInvertRectangleFrame Function
Purpose
Inverts a rectangular frame in the draw window (using the WinDrawOperation
winInvert
).
Declared In
Window.h
Prototype
void WinInvertRectangleFrame ( FrameTypeframe
, const RectangleType*rP
)
Parameters
-
→ frame
- The type of frame to draw (see
FrameType
). -
→ rP
- A pointer to the rectangle to frame (see
RectangleType
).
Returns
Compatibility
This function is deprecated in Palm OS Cobalt.
See Also
WinDrawGrayRectangleFrame()
, WinDrawRectangleFrame()
, WinEraseRectangleFrame()
, WinGetFramesRectangle()
, WinPaintRectangleFrame()
WinPaintBitmap Function
Purpose
Draws a bitmap in the current draw window at the specified coordinates using the winPaint
transfer mode.
Declared In
Window.h
Prototype
void WinPaintBitmap ( BitmapType*bitmapP
, Coordx
, Coordy
)
Parameters
-
→ bitmapP
- A 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 recommended instead of the rendering bitmaps into an off-screen window and then using WinCopyRectangle()
to draw them on screen.
If the bitmap has its own color table, color conversion to the draw window color table will be applied. This color conversion is slow and not recommended.
Compatibility
Do not use this function with the graphics context. Use GcPaintBitmap()
instead.
In earlier releases, this function used the transfer mode set in the draw state to paint the bitmap to the screen. Palm OS Cobalt ignores the current transfer mode and uses winPaint
instead.
See Also
WinDrawBitmap()
, WinEraseRectangle()
, WinPaintTiledBitmap()
WinPaintChar Function
Purpose
Draws a character in the draw window using the current drawing state.
Declared In
Window.h
Prototype
void WinPaintChar ( wchar32_ttheChar
, Coordx
, Coordy
)
Parameters
-
→ theChar
- The character to draw. This may be either a single-byte character or a multi-byte character.
-
→ x
- The x coordinate of the location where the character is to be drawn (left bound).
-
→ y
- The y coordinate of the location where the character is to be drawn (top bound).
Returns
Comments
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.
Compatibility
The winInvert
drawing mode does not work when you draw text. Nothing is drawn to the screen.
Do not use this function with the graphics context. Use GcDrawTextAt()
instead. Note that GcDrawTextAt()
uses the y value as the baseline for the font whereas WinPaintChar()
uses the y value as the top of the character.
See Also
WinDrawChar()
, WinDrawChars()
, WinDrawInvertedChars()
, WinDrawTruncChars()
, WinEraseChars()
, WinInvertChars()
, WinPaintChars()
WinPaintChars Function
Purpose
Draws the specified characters in the draw window with the current draw state.
Declared In
Window.h
Prototype
void WinPaintChars ( const char*chars
, int16_tlen
, Coordx
, Coordy
)
Parameters
-
→ chars
- A pointer to the characters to draw.
-
→ len
- The length in bytes of the characters to draw.
-
→ x
- The x coordinate of the first character to draw (left bound).
-
→ y
- The 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.
Before calling this function, consider calling WinSetUnderlineMode()
and FntSetFont()
.
Compatibility
The winInvert
drawing mode does not work when you draw text. Nothing is drawn to the screen.
Do not use this function with the graphics context. Use GcDrawTextAt()
instead. Note that GcDrawTextAt()
uses the y value as the baseline for the font whereas WinPaintChars()
uses the y value as the top of the character.
See Also
WinDrawChar()
, WinDrawChars()
, WinDrawInvertedChars()
, WinDrawTruncChars()
, WinEraseChars()
, WinInvertChars()
, WinPaintChar()
WinPaintLine Function
Purpose
Draws a line in the draw window using the current drawing state.
Declared In
Window.h
Prototype
void WinPaintLine ( Coordx1
, Coordy1
, Coordx2
, Coordy2
)
Parameters
-
→ x1
- The x coordinate of line beginning point.
-
→ y1
- The y coordinate of line beginning point.
-
→ x2
- The x coordinate of line endpoint.
-
→ y2
- The y coordinate of line endpoint.
Returns
Comments
This function uses the current drawing state.
Compatibility
Do not use this function with the graphics context. Use GcLineTo()
instead.
See Also
WinDrawLine()
, WinDrawGrayLine()
, WinEraseLine()
, WinFillLine()
, WinInvertLine()
, WinPaintLines()
WinPaintLines Function
Purpose
Draws several lines in the draw window using the current drawing state.
Declared In
Window.h
Prototype
void WinPaintLines ( uint16_tnumLines
, WinLineTypelines
[] )
Parameters
-
→ numLines
- The number of lines to paint.
-
→ lines
- An array of lines. See
WinLineType
.
Returns
Comments
This function uses the current drawing state.
Compatibility
Do not use this function with the graphics context. Use GcLineTo()
instead.
See Also
WinDrawLine()
, WinDrawGrayLine()
, WinEraseLine()
, WinFillLine()
, WinInvertLine()
, WinPaintLine()
WinPaintPixel Function
Purpose
Renders a pixel in the draw window using the current drawing state.
Declared In
Window.h
Prototype
void WinPaintPixel ( Coordx
, Coordy
)
Parameters
Returns
Comments
This function uses the current drawing state.
Compatibility
Do not use this function with the graphics context. Use GcLineTo()
instead.
See Also
WinDrawPixel()
, WinErasePixel()
, WinInvertPixel()
, WinPaintPixels()
WinPaintPixels Function
Purpose
Renders several pixels in the draw window using the current drawing state.
Declared In
Window.h
Prototype
void WinPaintPixels ( uint16_tnumPoints
, PointTypepts[]
)
Parameters
Returns
Comments
This function uses the current drawing state.
Compatibility
Do not use this function with the graphics context. Use GcLineTo()
instead.
See Also
WinDrawPixel()
, WinErasePixel()
, WinInvertPixel()
, WinPaintPixel()
WinPaintRectangle Function
Purpose
Draws a rectangle in the draw window using the current drawing state.
Declared In
Window.h
Prototype
void WinPaintRectangle ( const RectangleType*rP
, uint16_tcornerDiam
)
Parameters
-
→ rP
- The pointer to the rectangle to draw (see
RectangleType
). -
→ cornerDiam
- The 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.
Compatibility
The winInvert
and winSwap
drawing mode do not work when you draw a rectangle frame or unfilled rectangle. Nothing is drawn to the screen.
Do not use this function with the graphics context. Use GcRect()
instead. Note that GcRect()
specifies a rectangle's bounds differently than a RectangleType
structure does.
See Also
WinDrawRectangle()
, WinEraseRectangle()
, WinFillRectangle()
, WinInvertRectangle()
WinPaintRectangleFrame Function
Purpose
Draws a rectangular frame in the draw window using the current drawing state.
Declared In
Window.h
Prototype
void WinPaintRectangleFrame ( FrameTypeframe
, const RectangleType*rP
)
Parameters
-
→ frame
- The type of frame to draw (see
FrameType
). -
→ rP
- A pointer to the rectangle to frame (see
RectangleType
).
Returns
Comments
The frame is drawn outside the specified rectangle.
This function uses the current drawing state.
Compatibility
The winInvert
and winSwap
drawing mode do not work when you draw a rectangle frame or unfilled rectangle. Nothing is drawn to the screen.
Do not use this function with the graphics context. Use GcRect()
instead. Note that GcRect()
specifies a rectangle's bounds differently than a RectangleType
structure does.
See Also
WinDrawGrayRectangleFrame()
, WinDrawRectangleFrame()
, WinEraseRectangleFrame()
, WinGetFramesRectangle()
, WinInvertRectangleFrame()
, WinPaintRoundedRectangleFrame()
WinPaintRoundedRectangleFrame Function
Purpose
Draws 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
, Coordwidth
, CoordcornerRadius
, CoordshadowWidth
)
Parameters
-
→ rP
- A pointer to the rectangle to frame (see
RectangleType
). -
→ 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
The winInvert
and winSwap
drawing mode do not work when you draw a rectangle frame or unfilled rectangle. Nothing is drawn to the screen.
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
Do not use this function with the graphics context. Use GcRoundRect()
instead. Note that GcRoundRect()
specifies a rectangle's bounds differently than a RectangleType
structure does.
WinPaintTiledBitmap Function
Purpose
Fills a rectangle with a pattern defined by a bitmap.
Declared In
Window.h
Prototype
void WinPaintTiledBitmap ( const BitmapType*bitmapP
, RectangleType*rectP
)
Parameters
-
→ bitmapP
- A pointer to the bitmap that contains the desired pattern.
-
→ rectP
- A pointer to the rectangle that is to be filled (see
RectangleType
).
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 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.
Compatibility
Do not use this function with the graphics context. Use GcPaintBitmap()
instead.
WinPaintThinLine Function
Purpose
Draws a line that is one pixel thick.
Declared In
Window.h
Prototype
void WinPaintThinLine ( Coordx1
, Coordy1
, Coordx2
, Coordy2
)
Parameters
-
→ x1
- The x coordinate of line start point.
-
→ y1
- The y coordinate of line start point.
-
→ x2
- The x coordinate of line endpoint.
-
→ y2
- The y coordinate of line endpoint.
Returns
Comments
The text field uses this function when it needs to extend the text underline past the end of the text.
Compatibility
Do not use this function with the graphics context. Use GcLineTo()
instead.
See Also
WinPaintTruncChars Function
Purpose
Draws the specified characters in the draw window using the current transfer mode, truncating the characters to the specified width.
Declared In
Window.h
Prototype
void WinPaintTruncChars ( const char*chars
, int16_tlen
, Coordx
, Coordy
, CoordmaxWidth
)
Parameters
-
→ chars
- A pointer to the characters to draw.
-
→ len
- The length in bytes of the characters to draw.
-
→ x
- The x coordinate of the first character to draw (left bound).
-
→ y
- The y coordinate of the first character to draw (top bound).
-
→ maxWidth
- The maximum width in pixels of the characters that are to be drawn.
Returns
Comments
Before calling this function, consider calling WinSetTextColor()
, WinSetUnderlineMode()
and FntSetFont()
.
If drawing all of the specified characters requires more space than maxWidth
allows, WinPainTruncChars()
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.
This function differs from WinDrawTruncChars()
in that it uses the current drawing state's transfer mode. WinDrawTruncChars()
always uses winPaint
.
Compatibility
Do not use this function with the graphics context. Use GcDrawTextAt()
instead. Note that GcDrawTextAt()
uses the y value as the baseline for the font whereas WinPaintTruncChars()
uses the y value as the top of the character.
See Also
WinDrawChar()
, WinDrawChars()
, WinDrawInvertedChars()
, WinEraseChars()
, WinInvertChars()
, WinPaintChar()
, WinPaintChars()
, WinDrawTruncChars()
WinPopDrawState Function
Purpose
Restores 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()
.
Compatibility
Do not use this function with the graphics context. Use GcPopState()
instead.
WinPushDrawState Function
Purpose
Saves 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. Call WinPopDrawState()
to restore the saved settings.
Compatibility
Do not use this function with the graphics context. Use GcPushState()
instead.
WinResetClip Function
Purpose
Resets 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
WinSetBackColor Function
Purpose
Sets the background color to use in subsequent draw operations.
Declared In
Window.h
Prototype
IndexedColorType WinSetBackColor (
IndexedColorType backColor
)
Parameters
-
→ backColor
- The color to set; specify a value of type
IndexedColorType
.
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
));
Using WinSetBackColorRGB()
is preferred over this function. It is faster.
See Also
WinSetForeColor()
, WinSetTextColor()
WinSetBackColorRGB Function
Purpose
Sets the background color to use in subsequent draw operations.
Declared In
Window.h
Prototype
void WinSetBackColorRGB ( const RGBColorType*newRgbP
, RGBColorType*prevRgbP
)
Parameters
-
→ newRgbP
- The color to set; specify a value of type
RGBColorType
. -
← prevRgbP
- The 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 background color 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 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
Do not use this function with the graphics context. Use GcSetColor()
instead.
See Also
WinSetForeColorRGB()
, WinSetTextColorRGB()
WinSetClip Function
Purpose
Sets the clipping rectangle of the draw window.
Declared In
Window.h
Prototype
void WinSetClip (
const RectangleType *rP
)
Parameters
-
→ rP
- A pointer to a structure holding the clipping bounds (see
RectangleType
).
Returns
Compatibility
This function sets a rectangular region of the window into which the application may draw. It differs from GcBeginClip()
in that GcBeginClip()
works only with a graphics context and is able to define non-rectangular clipping regions.
See Also
WinClipRectangle()
, WinSetClip()
, WinGetClip()
WinSetColors Function
Purpose
Declared In
Window.h
Prototype
void WinSetColors ( const RGBColorType*newForeColorP
, RGBColorType*oldForeColorP
, const RGBColorType*newBackColorP
, RGBColorType*oldBackColorP
)
Parameters
-
→ newForeColorP
- The color to use for the foreground and the text; specify a value of type
RGBColorType
. -
← oldForeColorP
- Previous foreground color.
-
→ newBackColorP
- The color to use for the background; specify a value of type
RGBColorType
. -
← oldBackColorP
- Previous background color.
Returns
See Also
WinSetBackColorRGB()
, WinSetTextColorRGB()
, WinSetForeColorRGB()
WinSetCoordinateSystem Function
Purpose
Establishes the coordinate system to be used for subsequent drawing operations.
Declared In
Window.h
Prototype
uint16_t WinSetCoordinateSystem (
uint16_t coordSys
)
Parameters
-
→ coordSys
- The desired coordinate system. Supply one of the values defined in "Coordinate System Constants."
Returns
The previous coordinate system value.
Comments
This function modifies the draw state. 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 amount by which it will scale all coordinates, 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
If you are making graphics context calls, use GcSetCoordinateSystem()
to set the coordinate system that the graphics context uses within the window. It is a good idea to always make both calls so that you are certain that the window's coordinate system is the same as the graphics context's coordinate system.
See Also
WinSetDrawMode Function
Purpose
Sets the transfer mode to use in subsequent draw operations.
Declared In
Window.h
Prototype
WinDrawOperation WinSetDrawMode (
WinDrawOperation newMode
)
Parameters
-
→ newMode
- The transfer mode to set; specify one of the
WinDrawOperation
values.
Returns
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
Do not use this function with the graphics context.
WinSetForeColor Function
Purpose
Sets the foreground color to use in subsequent draw operations.
Declared In
Window.h
Prototype
IndexedColorType WinSetForeColor (
IndexedColorType foreColor
)
Parameters
-
→ foreColor
- The color to set; specify a value of type
IndexedColorType
.
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));
Using WinSetForeColorRGB()
is preferred over this function. It is faster.
Compatibility
Do not use this function with the graphics context. Use GcSetColor()
instead.
See Also
WinSetBackColor()
, WinSetTextColor()
WinSetForeColorRGB Function
Purpose
Sets the foreground color to use in subsequent draw operations.
Declared In
Window.h
Prototype
void WinSetForeColorRGB ( const RGBColorType*newRgbP
, RGBColorType*prevRgbP
)
Parameters
-
→ newRgbP
- The color to set; specify a value of type
RGBColorType
. -
← prevRgbP
- Previous color
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 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 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
Do not use this function with the graphics context. Use GcSetColor()
instead.
See Also
WinSetBackColorRGB()
, WinSetTextColorRGB()
WinSetFrameType Function
Purpose
Sets the type of frame to be used for a specified window.
Declared In
Window.h
Prototype
void WinSetFrameType ( const WinHandlewinH
, FrameTypeframe
)
Parameters
-
→ winH
- The window's handle.
-
→ frame
- The style of frame to be used. See
FrameType
.
Returns
See Also
WinSetPattern Function
Purpose
Sets the current fill pattern.
Declared In
Window.h
Prototype
void WinSetPattern (
const CustomPatternType *patternP
)
Parameters
-
→ patternP
- The 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.
Compatibility
Do not use this function with the graphics context.
See Also
WinSetPatternType Function
Purpose
Sets the current pattern type.
Declared In
Window.h
Prototype
void WinSetPatternType (
PatternType newPattern
)
Parameters
-
→ newPattern
- The pattern type to set for the draw window (see
PatternType
).
Returns
Comments
This function sets the drawing state's pattern newPattern
and sets the custom pattern data to NULL
. To set 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
Do not use this function with the graphics context.
See Also
WinSetScalingMode Function
Purpose
Controls the scaling of bitmaps and bitmapped fonts and the spacing between text glyphs.
Declared In
Window.h
Prototype
uint32_t WinSetScalingMode (
uint32_t mode
)
Parameters
-
→
mode
- One or more of the Scaling Mode Constants OR'd together.
Returns
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 device that has a high-density display, you can use WinSetScalingMode()
to draw text unscaled.
On a device 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.
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 text padding turned off, or to use native coordinates with text padding turned on, call WinSetScalingMode()
after calling WinSetCoordinateSystem()
. Note that using standard coordinates with padding off is not recommended since the Font Manager functions 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.
See Also
WinSetTextColor Function
Purpose
Sets the color to use for drawing characters in subsequent draw operations.
Declared In
Window.h
Prototype
IndexedColorType WinSetTextColor (
IndexedColorType textColor
)
Parameters
-
→ textColor
- The color to set; specify a value of type
IndexedColorType
.
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));
Using WinSetTextColorRGB()
is preferred over this function. It is faster.
Compatibility
Do not use this function with the graphics context. Use GcSetColor()
instead.
See Also
WinSetBackColor()
, WinSetForeColor()
WinSetTextColorRGB Function
Purpose
Sets 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
- The color to set; specify a value of type
RGBColorType
. -
← prevRgbP
- The previous color; specify a value of type
RGBColorType
.
Returns
Comments
This function takes new and previous RGBColorType
arguments. It is acceptable 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 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 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
Do not use this function with the graphics context. Use GcSetColor()
instead.
See Also
WinSetBackColorRGB()
, WinSetForeColorRGB()
WinSetUnderlineMode Function
Purpose
Sets the graphic state to enable or disable the underlining of characters.
Declared In
Window.h
Prototype
UnderlineModeType WinSetUnderlineMode (
UnderlineModeType mode
)
Parameters
-
↔ mode
- The new underline mode type; see
UnderlineModeType
.
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.
Compatibility
Do not use this function with the graphics context.
See Also
Application-Defined Functions
winInvalidateFunc Function
Purpose
Redraws the specified portion of a window.
Declared In
Window.h
Prototype
Boolean ( *winInvalidateFunc ) ( int32_tcmd
, WinHandlewindow
, const RectangleType*dirtyRect
, void*state
)
Parameters
-
→ cmd
- One of the following:
-
winInvalidateExecute
- Redraw the region
dirtyRect
in thewindow
. -
winInvalidateDestroy
- Free the
state
if necessary. -
→ window
- The window into which to draw.
-
→ dirtyRect
- The region of the window that needs to be redrawn (see
RectangleType
). -
→ state
- Application-specific data necessary for the redraw.
Returns
true
if the function handled the cmd, or false
if an error occurred.
Comments
This function is used as a drawing optimization. You specify this function in a call to WinInvalidateRectFunc()
. If certain conditions are met, the Window Manager calls this function instead of enqueueing a winUpdateEvent
.
Even if this function is not used to redraw the specified area, it is always called with the winInvalidateDestroy
parameter to free the state.
After you receive the call with winInvalidateDestroy
, the association between the rectangle and this function is destroyed. If you want to keep using your callback function for this region, you should use WinInvalidateRectFunc()
each time you need to invalidate it.