GetPenMiscInfo 

1.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 BOXEDITINFO232HBFC 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 RGB959Q0EE 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 PENTIP1AOCX_ 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 RGB959Q0EE 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 ABSTIME1AOCV. 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)

01  dark blue   RGB(  0,   0, 127)

02  dark green  RGB(  0, 127,   0)

03  dark cyan   RGB(  0, 127, 127)

04  dark red    RGB(127,   0,   0)

05  purple      RGB(127,   0, 127)

06  brown       RGB(127, 127,   0)

07  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!

 

See Also

SetPenMiscInfo