DevOpenDC: Difference between revisions

Revision as of 05:24, 8 April 2025

This function creates a device context.

Syntax

DevOpenDC(hab, lType, pszToken, lCount, pdopData, hdcComp)

Parameters

hab (HAB) - input: Anchor-block handle.

lType (LONG) - input: Type of device context:

OD_QUEUED: A device, such as a printer or plotter, for which output is to be queued.

Certain restrictions apply for this device type;

OD_DIRECT: A device, such as a printer or plotter, for which output is not to be queued.

OD_INFO: A device, such as a printer or plotter, but the device context is used only to retrieve information (for example, font metrics). Drawing can be performed to a presentation space associated with such a device context, but no output medium is updated.

OD_METAFILE: The device context is used to write a metafile. The presentation page defines the area of interest within the picture in the metafile. See

OD_METAFILE_NOQUERY.: Certain restrictions apply for this device type;

OD_METAFILE_NOQUERY: The device context is used to write a metafile.

Functionally, this device type is the same as OD_METAFILE, except that querying of attributes is not allowed with a presentation space while it is associated with an OD_METAFILE_NOQUERY device context. If querying of attributes is not required, OD_METAFILE_NOQUERY should be used in preference to OD_METAFILE, since it gives improved performance.

Certain restrictions apply for this device type;

OD_MEMORY: A device context that is used to contain a bit map. The hdcComp parameter identifies a device with which the memory device context is to be compatible.

pszToken (PSZ) - input: Device-information token.

This identifies the device information, held in the initialization file. This information is the same as that which may be pointed to by pdopData; any information that is obtained from pdopData overrides the information obtained by using this parameter.

If pszToken is specified as "*", no device information is taken from the initialization file.

OS/2 behaves as if "*" is specified, but it allows any string.

lCount (LONG) - input: Number of items.

This is the number of items present in the pdopData parameter. This can be less than the full list if omitted items are irrelevant, or are supplied from pszToken or elsewhere.

pdopData (PDEVOPENDATA) - input: Open-device-context data area.

hdcComp (HDC) - input: Compatible-device-context handle.

When lType is OD_MEMORY, this parameter is a handle to a device context compatible with bit maps that are to be used with this device context.

If hdcComp is NULLHANDLE, compatibility with the screen is assumed.

Return Code

hdc (HDC) - returns: Device-context handle:

DEV_ERROR

Error

<>0

Device-context handle.

Errors

Possible returns from WinGetLastError

PMERR_INV_DC_TYPE (0x2060): An invalid type parameter was specified with DevOpenDC, or a function was issued that is invalid for a OD_METAFILE_NOQUERY device context.

PMERR_INV_LENGTH_OR_COUNT (0x2092): An invalid length or count parameter was specified.

PMERR_INV_DC_DATA (0x205F): An invalid data parameter was specified with DevOpenDC.

PMERR_INV_HDC (0x207C): An invalid device-context handle or (micro presentation space) presentation-space handle was specified.

PMERR_INV_DRIVER_NAME (0x2067): A driver name was specified which has not been installed.

PMERR_INV_LOGICAL_ADDRESS (0x2097): An invalid device logical address was specified.

Remarks

A device context is a means of writing to a particular device. Before using GPI functions to cause output to be directed to the device context, the GpiAssociate function call must be issued (or the GPIA_ASSOC option specified on GpiCreatePS).

DevOpenDC cannot be used to open a device context for a screen window; use WinOpenWindowDC instead.

The device context is owned by the process from which DevOpenDC is issued. It cannot be accessed directly from any other process. If it still exists when the process terminates, it is automatically deleted by the system. When using a device context type of OD_METAFILE_NOQUERY the querying of attributes is not allowed. To improve performance of this type of metafile no error checking is performed to ensure that such API calls are not attempted. Query calls are accepted but the results returned are undefined.

This function requires the existence of a message queue.

Example Code

#define INCL_DEV /* Or use INCL_PM, Also in COMMON section */
#include <os2.h>

HAB             hab;       /*  Anchor-block handle. */
LONG            lType;     /*  Type of device context: */
PSZ             pszToken;  /*  Device-information token. */
LONG            lCount;    /*  Number of items. */
PDEVOPENDATA    pdopData;  /*  Open-device-context data area. */
HDC             hdcComp;   /*  Compatible-device-context handle. */
HDC             hdc;       /*  Device-context handle: */

hdc = DevOpenDC(hab, lType, pszToken, lCount,
        pdopData, hdcComp);

This example calls DevOpenDC to create a memory device context with screen compatibility and then associates that context with a newly created presentation space.

#define INCL_DEV                /* Device Function definitions  */
#define INCL_GPICONTROL         /* GPI control Functions        */
#include <os2.h>

HDC   hdc;              /* Device-context handle                */
HAB   hab;              /* Anchor-block handle                  */
 /* context data structure */
DEVOPENSTRUC dop = {NULL, "DISPLAY", NULL, NULL, NULL, NULL,
                    NULL, NULL, NULL};
HPS    hps;             /* presentation-space handle            */
SIZEL  sizl={0, 0};     /* use same page size as device        */

/* create memory device context */
hdc = DevOpenDC(hab, OD_MEMORY, "*", 5L, (PDEVOPENDATA)&dop, NULLHANDLE);

/* create a presentation space associated with the context */
hps = GpiCreatePS(hab, hdc, &sizl, GPIA_ASSOC | PU_PELS);

Prerequisite Functions

WinInitialize

Related Functions