### PMCX Definition Headers - PMCX.H

The PMCX definitions header include file -- PMCX.H for OS/2 or PMCXW.H for Windows -- is used to define constants, structures, and macros for the purpose of allowing information to be passed between the IRE and the custom control.

A set of constant definitions is provided within the header that you can use within your implementation of the PMCX control. The definitions are a mixture of limits, options, flags, and service requests. They are:

CTYPES | Defines the maximum number of user types.
CCHCLASS | Defines the maximum length of the class-name definition, including the null-terminating byte.
CCHNAME | Defines the maximum length of the control's name, including the null-terminating byte.
CCHAUTHOR | Defines the maximum length of the author's name for the control, including the null-terminating byte.
CCHDESC | Defines the maximum length of the control's description, including the null-terminating byte.
CCHID | Defines the maximum length of the ID symbol, including the null-terminating byte.
CCHTEXTMAX | Defines the maximum length of text that can be defined for the control, including the null-terminating byte.
UTYPE_PRIVATE | Defines the type of control as a private class where it must be registered specifically by the application before it is used. This registration of the control is provided the XxxxRegister function within the DLL.
UTYPE_PUBLIC | Defines the type of control as a public class that has been registered and does not need to be registered by the application.
USER_CWINDOWWORDS | Defines the minimum amount of reserved memory that must be allocated for the control when it is registered. Additional reserved memory for the control can be allocated by simply adding the value to the constant in the XxxxRegister function.
QWW_USER | It is a pointer into the control's reserved memory where the pointer to the user data resides.
QWW_CDATA | Is used as an index into the control's reserved memory where the pointer to the private-control data memory allocated for the control is located.
CUACHK_MNEMONIC | Is used as an option with the pfnCUACheck function to check that the text of the control complies with CUA requirements for mnemonic inclusion.
CUACHK_CAPS | Is used as an option with the pfnCUACheck function to check that the text of the control complies with CUA requirements for capitalization.
CUACHK_ELLIPSIS | Is used as an option with the pfnCUACheck function to check that the text of the control complies with CUA requirements for the text and ellipsis.
STYLETYPE_BITFLAGS | Indicates that the style masks are bit flags, and that the style generated in the resource script can be multiple values when the bits are compared to the style masks.
STYLETYPE_SEQUENCE | Indicates that the style masks are sequential in nature, and that the styles generated in the resource script should be based on a single value that must match the style mask.
PMCXOPT_NONE | Indicates that no special options are required.
PMCXOPT_REFRESH | Indicates that the control should be refreshed through the Integrated Resource Editor, where the IRE will delete the previous instance of the control and create a new one to show the revised styles selected.
PMCXOPT_VARICDATA | Indicates that the control supports variable-length control data.
PMCXOPT_STYLECHG | Indicates that the control supports the changing of the style flags using the SetWindowLong function and the index of GWL_STYLE.
PMCXOPT_TABABLE | Indicates that the control supports tabbing and cursor-movement selections.
PMCXOPT_HELP | Indicates that the control allows the help to be selected when it receives focus.
PMCXWS_VISIBLE | Indicates window style.
PMCXWS_DISABLED | Indicates window style.
PMCXWS_GROUP | Indicates window style.
PMCXWS_TABSTOP | Indicates window style.

Four structures are defined within the header. Three of these structures are used to describe the PMCX control to the IRE, with the last structure being used by the IRE to communicate with the styles dialog. These structures are:

STYLE | Defines a control style mask and the corresponding resource-file string-table ID. The structure is used by the USERTYPE structure.
USERTYPE | Defines the user control type. The information within the structure is for the default characteristics of the control, the ID of the dialog template within the control's DLL for the styles dialog, the room necessary for additional control data (for example, picture masks, ranges, and limits), control type, styles count, and style masks. It is used by the USERINFO structure.
USERINFO | Defines information for the control that the IRE initially queries to determine the capabilities of the control. The control's version number, author, class, library name, and types are defined. Used only by XxxxQuery function.
USERSTYLE | Allow a method of communication regarding data information entered or edited through the dialog procedure. The structure provides helper function addresses that can be used to reference the control's style, ID symbol and value, text, and control specific data.

The STYLE structure is defined as:

flStyleMask | Contains a style flag mask for a possible style of the control. It should be in the form of 0x0000UL. The style mask must correspond with a resource string indicated in the idStyle field.
idStyle | Contains the ID of the resource string for the corresponding style mask in the flStyleMask field.

The USERTYPE structure is defined as:

cx | Contains suggested width of the control in dialog units. This value will be used by the IRE as the initial width of the control when it is added to a window or dialog.
cy | Contains suggested height of the control in dialog units. This value will be used by the IRE as the initial height of the control when it is added to a window or dialog.
flStyle | Contains initial style flags of the control when it is created by the IRE.
flOptions | Contains the options flags, which can be one of the PMCXOPT_* flags.
cMaxText | Contains the maximum number of characters that the control is capable of handling. This value is used by the IRE to allocate space for the control's text that is addressed in the pszText field of the USERSTYLE structure.
idDlg | Contains the resource ID of the styles dialog that is displayed by the IRE when the control is first added to a window or dialog, or when the user requests to edit the styles of the control.
idReserved | Reserved.
flStyleType | Contains the style type flag, which indicates to the IRE how the style masks should be interpreted when the resource script statement for the control is generated. The current style types defined are STYLETYPE_BITFLAGS for bit-flag styles, and STYLETYPE_SEQUENCE for sequential styles.
cCtlData | Contains the number of bytes that should be allocated for private data used by the control. This data is allocated by the IRE and is addressed in the abCtlData field of the USER_STYLE structure.
ulType | Contains the control type, which can be either UTYPE_PRIVATE or UTYPE_PUBLIC.
cMasks | Contains the total count of style masks defined in the stMasks field.
szDescription[CCHDESC] | Contains a control name that can be displayed by the IRE.
stMasks[32] | Contains the control style-flag masks and ID string values.
aulReserved[4] | Reserved.

The USERINFO structure is defined as:

ulMajor | Contains the control's major version number.
ulMinor | Contains the control's minor version number.
szAuthor[CCHAUTHOR] | Contains the control's author name.
szClassname[CCHCLASS] | Contains the class name of the control.
szName[CCHNAME] | Contains the library name for the control. This name should correspond to the Xxxx component of the required functions, as well as the dynamic-link library name.
aulReserved[6] | Reserved.
cTypes | Contains the number of types supported by the control. In Version 1.0 of PMCX, only one type is allowed, and this field must be 1.
utDefined[CTYPES] | Contains the type information of each of the controls supported by the control. In Version 1.0 of PMCX, only the first array element is used.

The USERSTYLE structure is defined as:

pfnSetSymbol | Contains the function address for the function within the IRE that will set the ID field symbol and value.
pfnGetSymbol | Contains the function address for the function within the IRE that will cause the ID field symbol and value to be validated and placed within the USERSTYLE structure.
pfnGetFontClr | Contains the function address for the Font & Color dialog box. The IRE will record the font and colors selected by the user internally on behalf of the control.
pfnCUACheck | Contains the function address for the CUA-compliance checking function. Compliance for mnemonics, capitalization, and ellipsis can be checked through this function if the control supports any of these features. A value of TRUE will be returned when noncompliance is determined. A value of FALSE will be returned when the control is compliant.
pfnRealloc | Contains the function address for the control data reallocation function. This function allows the control to reallocate the necessary control data memory when the control supports variable control data.
flStyle | Contains the current style flags set for the control.
id | Contains the current ID value for the control.
szid[CCHID] | Contains the current ID symbol for the control.
pszText | Contains the address of the text for the control.
cText | Contains the count of characters for the control, including null terminator.
pfnGetBidi | Contains the function address for the Bidirectional Support dialog. The IRE will record the bidirectional options selected by the user internally on behalf of the control.
aulReserved[8] | Reserved.
pbCtlData | Contains the variable control-data buffer pointer. This is used only when the control supports variable control data and is used in place of the abCtlData field.
cbCtlData | Contains the size of the control-data buffer, pbCtlData, when the control supports variable control data.
abCtlData[1] | First element of the private control data. When control data is used, the control should cast the appropriate structure as the address of the array to be able to easily address areas of the data.

Two helper macros are defined within the header:

PDATATODLG | Places the passed address of the USERSTYLE pointer within the dialog's reserved memory. The passed address is contained within the second message parameters (MPARAMmp2 on OS/2 or LONG lParam on Windows) and must be placed within the dialog's reserved memory when it receives the WM_INITDLG (on OS/2) or WM_INITDIALOG (on Windows) message.
PDATAFROMDLG | Refers to the memory location within the dialog procedure where the USERSTYLE pointer passed to the dialog is placed. A pointer is returned by the macro that allows reference to the elements of the USERSTYLE structure.

Control Extensions

PMCX Construction

PMCX Architecture
How PMCX Works