GetPenMiscInfo - Microsoft Windows Pen API Programmer's Reference (penapi.hlp)

Microsoft Windows Pen API
Programmer's Reference

Index Commented Search About

GetPenMiscInfo

0 2.0

Retrieves values pertaining to the pen system.

LONG GetPenMiscInfo( WPARAM wParam, LPARAM lParam )

Parameters
wParam

Specifies the identifier of the pen system value to retrieve. The pen system identifier must be a PMI_ value. See the table below for the possible PMI_ values in wParam.

lParam

Address of storage for data. This must not be NULL. The calling application must ensure that there is sufficient room to store the requested information. The type of storage object that lParam points to depends on wParam, as described in the following table. For each value of wParam in the first column, the second column describes the corresponding requirement for lParam:

wParam constant	LParam description
PMI_BEDIT	lParam is the address of a BOXEDITINFO structure. Boxed edit information.
PMI_CXTABLET	lParam is a far pointer to a UINT value specifying the width of tablet (in units of 0.001 inch) if present; otherwise, the width of the screen.
PMI_CYTABLET	lParam is a far pointer to a UINT value specifying the height of tablet (in units of 0.001 inch) if present; otherwise, the height of the screen.
PMI_INDEXFROMRGB	lParam is a far pointer to a DWORD value. On entry, lParam is the address of an RGB ink color value. On return, the low-order word of lParam is replaced with an index in the range 0 to 15 for the closest standard ink color and the high-order word is 0.
PMI_ENABLEFLAGS	lParam is a far pointer to a WORD value containing a flag describing whether certain Pen API features are enabled. The flags can be a combination of the following values: PWE_AUTOWRITE Enable pen functionality where the I-Beam cursor is present. PWE_ACTIONHANDLES Enable action handles in controls. PWE_INPUTCURSOR Show cursor while writing. PWE_LENS Enable pop-up letter guides (that is, the lens).
PMI_PENTIP	lParam is the address of a PENTIP structure.
PMI_RGBFROMINDEX	lParam is the address of a DWORD value. On entry, lParam is the address of an index in the range 0 to 15; on return, this value at this address is replaced with the standard RGB ink color value.
wParam constant	LParam description
PMI_SYSFLAGS	lParam is a far pointer to a WORD value containing a flag describing which pen system components are loaded. The flags can be a combination of the following values: PWF_RC1 Support available for Pen API version 1.0 Recognition Context (RC) and associated functions. PWF_PEN Pen/tablet hardware is present. PWF_INKDISPLAY Ink-compatible display driver is present. PWF_RECOGNIZER System recognizer is present. PWF_BEDIT Boxed edit (bedit) control is available. PWF_HEDIT Handwriting edit (hedit) control is available. PWF_IEDIT Ink edit (iedit) control is available. PWF_ENHANCED Enhanced features, including gesture support and 1 millisecond timing, are available. PWF_FULL All components listed above are present..
PMI_SYSREC	lParam is a far pointer to an HREC value which is the handle of the system recognizer, if present.
PMI_TICKREF	lParam is the address of an ABSTIME structure indicating the absolute reference time that the system uses to calculate time-stamps for strokes in pen data objects and inkset
PMI_TIMEOUT	lParam is a far pointer to a UINT value indicating time-out value to end hand-writing input, in milliseconds.
PMI_TIMEOUTGEST	lParam is a far pointer to a UINT value indicating time-out value to end a gesture, in milliseconds.
PMI_TIMEOUTSEL	lParam is a far pointer to a UINT value indicating the time-out value in milli-seconds for press-and-hold gesture. The range of permissible values is 0 to 5000. If press-and-hold has been disabled, this value is 65,535.

Return Value
The return value is PMIR_OK if successful; otherwise it is one of the following negative error values:

Constant	Description
PMIR_INDEX	wParam is out of range.
PMIR_NA	Support for this value of wParam is not available.
PMIR_VALUE	lParam is NULL or a invalid pointer.

Comments
The information type returned varies depending on the index. Note that if a UINT is expected, for example, it is an error to provide the address of a DWORD variable without explicitly setting the HIWORD to 0. This function only sets the LOWORD in this case, and since the variable is usually declared on the stack, there would be an unknown value in the HIWORD. See the examples below.

If wParam is PMI_INDEXFROMRGB or PMI_RGBFROMINDEX, the standard pen-tip color table is as follows:

00 black RGB( 0, 0, 0)

dark blue RGB( 0, 0, 127)
dark green RGB( 0, 127, 0)
dark cyan RGB( 0, 127, 127)
dark red RGB(127, 0, 0)
purple RGB(127, 0, 127)
brown RGB(127, 127, 0)
gray RGB(127, 127, 127)

08 light gray RGB(192, 192, 192)

09 blue RGB( 0, 0, 255)

10 green RGB( 0, 255, 0)

11 cyan RGB( 0, 255, 255)

12 red RGB(255, 0, 0)

13 magenta RGB(255, 0, 255)

14 yellow RGB(255, 255, 0)

15 white RGB(255, 255, 255)

Example
The following code sample retrieves the timeout and pen tip:

UINT uTimeout;

PENTIP tip;

GetPenMiscInfo( PMI_TIMEOUT, (LPARAM)(UINT FAR *)&utimeout );

GetPenMiscInfo( PMI_PENTIP, (LPARAM)(LPPENTIP)&tip );

Note that the following is an error, since the HIWORD is undefined:

DWORD dwTimeout;

GetPenMiscInfo( PMI_TIMEOUT, (LPARAM)&dwtimeout ); // Wrong!