ExtDeviceMode

The ExtDeviceMode function retrieves or modifies device-initialization information for a given graphics driver, or displays a driver-supplied dialog box for configuring the graphics driver. Applications call the ExtDeviceMode function when the user requests setting up the printer as part of preparing for a print job.

All printer drivers must export the ExtDeviceMode function. Display drivers that permit the user to change operating modes must export the ExtDeviceMode function.

Parameters

hWnd

Identifies the parent window for the dialog box.

hDriver

Identifies the module instance of the device driver.

lpDevModeOutput

Points to a DEVMODE structure. The driver writes the initialization information supplied in the lpDevModeInput parameter to this structure. The structure has the following form:

typedef struct _devicemode { /* dm */

char dmDeviceName[CCHDEVICENAME];

WORD dmSpecVersion;

WORD dmDriverVersion;

WORD dmSize;

WORD dmDriverExtra;

DWORD dmFields;

short dmOrientation;

short dmPaperSize;

short dmPaperLength;

short dmPaperWidth;

short dmScale;

short dmCopies;

short dmDefaultSource;

short dmPrintQuality;

short dmColor;

short dmDuplex;

short dmYResolution;

short dmTTOption;

} DEVMODE;

lpDeviceName

Points to a null-terminated string that contains the name of the device, such as PCL/HP LaserJet.

lpPort

Points to a null-terminated string that contains the name of the port to which the device is connected, such as LPT1.

lpDevModeInput

Points to a DEVMODE structure containing initialization information set by the application.

lpProfile

Points to a null-terminated string that contains the name of the initialization file in which initialization information is recorded and read from. If this parameter is NULL, the [Model Name, Port] section of the WIN.INI file is the default.

wMode

Specifies which operations the function will perform. If the wMode parameter is zero, ExtDeviceMode returns the number of bytes required by the device driver's DEVMODE structure. Otherwise, wMode can be a combination of the following values.

Return Value

If the wMode parameter is zero, the return value is the size of the DEVMODE structure required to contain the printer-driver initialization data. If the function displays the initialization-dialog box, the return value is either IDOK or IDCANCEL, depending on which button the user chose. If the function does not display the dialog box and was successful, the return value is IDOK. The return value is less than zero if the function failed.

Comments

The export ordinal for this function is 90.

If wMode includes DM_PROMPT, the ExtDeviceMode function creates an application-modal dialog box using the DialogBox function (USER.240). The dialog box must provide options for the user to set the various settings of the device. ExtDeviceMode does the following:

1.Initializes the dialog box settings by using the environment specified by lpDevModeInput, by retrieving the current environment using the GetEnvironment function (GDI.133), or by reading the environment from the corresponding, device-specific section in the WIN.INI file.

2.Calls the DialogBox box to display the dialog box, then waits for the user to complete their changes. When the value returns from DialogBox, check the return value. Make subsequent updates only if the return value is IDOK.

3.Updates the current device environment by using the SetEnvironment function (GDI.132). Also, it updates the corresponding device-specific section in the WIN.INI file (or specified initialization file) if wMode includes DM_UPDATE.

4.Sends a WM_DEVMODE message to all applications informing them of a change to the device's operating modes.

The dialog box must provide at least a title bar and OK and Cancel buttons in addition to controls for the various operating modes. The title bar should contain the name of the current printer model (if the driver supports several models), but no other printer model information should be presented in the dialog box. (The ExtDeviceMode dialog box cannot permit the user to change device models.)

If a device has too many options to fit in a single dialog box, ExtDeviceMode can provide nested dialog boxes, using buttons in the first dialog box to access the others. In all cases, a dialog function for a ExtDeviceMode dialog box must close the dialog box if it receives a WM_COMMAND message with the wParam parameter set to IDCANCEL. This message occurs when the user presses the ESC key, chooses the Cancel button in the dialog box, or when Windows Help needs to close the dialog box in order to respond to a request for help from another application.

See Also

AdvancedSetUpDialog, DeviceMode