Estructura PRINTDLGEXA (commdlg.h)

Contiene información que la función PrintDlgEx usa para inicializar la hoja de propiedades Print. Una vez que el usuario cierra la hoja de propiedades, el sistema usa esta estructura para devolver información sobre las selecciones del usuario.

Sintaxis

typedef struct tagPDEXA {
  DWORD            lStructSize;
  HWND             hwndOwner;
  HGLOBAL          hDevMode;
  HGLOBAL          hDevNames;
  HDC              hDC;
  DWORD            Flags;
  DWORD            Flags2;
  DWORD            ExclusionFlags;
  DWORD            nPageRanges;
  DWORD            nMaxPageRanges;
  LPPRINTPAGERANGE lpPageRanges;
  DWORD            nMinPage;
  DWORD            nMaxPage;
  DWORD            nCopies;
  HINSTANCE        hInstance;
  LPCSTR           lpPrintTemplateName;
  LPUNKNOWN        lpCallback;
  DWORD            nPropertyPages;
  HPROPSHEETPAGE   *lphPropertyPages;
  DWORD            nStartPage;
  DWORD            dwResultAction;
} PRINTDLGEXA, *LPPRINTDLGEXA;

Members

lStructSize

Tipo: DWORD

Tamaño de la estructura, en bytes.

hwndOwner

Tipo: HWND

Identificador de la ventana que posee la hoja de propiedades. Este miembro debe ser un identificador de ventana válido; no puede ser NULL.

hDevMode

Tipo: HGLOBAL

Identificador de un objeto de memoria global móvil que contiene una estructura DEVMODE . Si hDevMode no es NULL en la entrada, debe asignar un bloque de memoria extraíble para la estructura DEVMODE e inicializar sus miembros. La función PrintDlgEx usa los datos de entrada para inicializar los controles de la hoja de propiedades. Cuando se devuelve PrintDlgEx , los miembros de DEVMODE indican la entrada del usuario.

Si hDevMode es NULL en la entrada, PrintDlgEx asigna memoria para la estructura DEVMODE , inicializa sus miembros para indicar la entrada del usuario y devuelve un identificador que lo identifica.

Para obtener más información sobre los miembros hDevMode y hDevNames , vea la sección Comentarios al final de este tema.

hDevNames

Tipo: HGLOBAL

Identificador de un objeto de memoria global móvil que contiene una estructura DEVNAMES . Si hDevNames no es NULL en la entrada, debe asignar un bloque de memoria extraíble para la estructura DEVNAMES e inicializar sus miembros. La función PrintDlgEx usa los datos de entrada para inicializar los controles de la hoja de propiedades. Cuando se devuelve PrintDlgEx , los miembros DEVNAMES contienen información para la impresora elegida por el usuario. Puede usar esta información para crear un contexto de dispositivo o un contexto de información.

El miembro hDevNames puede ser NULL, en cuyo caso PrintDlgEx asigna memoria para la estructura DEVNAMES , inicializa sus miembros para indicar la entrada del usuario y devuelve un identificador que lo identifica.

Para obtener más información sobre los miembros hDevMode y hDevNames , vea la sección Comentarios al final de este tema.

hDC

Tipo: HDC

Identificador de un contexto de dispositivo o un contexto de información, dependiendo de si el miembro Flags especifica la marca PD_RETURNDC o PC_RETURNIC . Si no se especifica ninguna marca, el valor de este miembro no está definido. Si se especifican ambas marcas, PD_RETURNDC tiene prioridad. Si hDC no es NULL, debe llamar a DeleteDC para liberar el objeto GDI después de que ya no lo necesite; de lo contrario, perderá objetos GDI cada vez que llame a las API printDlgw .

Flags

Tipo: DWORD

Un conjunto de marcas de bits que puede usar para inicializar la hoja de propiedades Print . Cuando la función PrintDlgEx devuelve, establece estas marcas para indicar la entrada del usuario. Este miembro puede ser uno o varios de los valores siguientes.

Para asegurarse de que PrintDlg o PrintDlgEx devuelven los valores correctos en los miembros dmCopies y dmCollate de la estructura DEVMODE , establezca PD_RETURNDC = TRUE y PD_USEDEVMODECOPIESANDCOLLATE = TRUE. Al hacerlo, el miembro nCopies de la estructura PRINTDLG siempre es 1 y PD_COLLATE siempre es FALSE.

Para asegurarse de que PrintDlg o PrintDlgEx devuelven los valores correctos en nCopies y PD_COLLATE, establezca PD_RETURNDC = TRUE y PD_USEDEVMODECOPIESANDCOLLATE = FALSE. Al hacerlo, dmCopies siempre es 1 y dmCollate siempre es FALSE.

A partir de Windows Vista, cuando se llama a PrintDlg o PrintDlgEx con PD_RETURNDC establecido en TRUE y PD_USEDEVMODECOPIESANDCOLLATE establecido en FALSE, la función PrintDlg o PrintDlgEx establece el número de copias en el miembro nCopies de la estructura PRINTDLG y establece el número de copias en la estructura representada por el miembro hDC de la estructura PRINTDLG .

Al realizar llamadas a GDI, debe omitir el valor de nCopies, considerar el valor como 1 y usar el hDC devuelto para evitar imprimir copias duplicadas.

Flags2

Tipo: DWORD

ExclusionFlags

Tipo: DWORD

Conjunto de marcas de bits que pueden excluir elementos de las páginas de propiedades del controlador de impresora en la hoja de propiedades Imprimir . Este valor solo se usa si la marca PD_EXCLUSIONFLAGS está establecida en el miembro Flags . Las marcas de exclusión solo se deben usar si el elemento que se va a excluir se incluirá en la página General o en una página definida por la aplicación en la hoja de propiedades Print . Este miembro puede especificar la marca siguiente.

PD_EXCL_COPIESANDCOLLATE

Excluye los controles Copies y Collate de las páginas de propiedades del controlador de impresora en una hoja de propiedades Print . Esta marca siempre debe establecerse cuando la aplicación usa los controles Copia y Intercalación predeterminados proporcionados por la parte inferior de la página General de la hoja de propiedades Imprimir .

nPageRanges

Tipo: DWORD

En la entrada, establezca este miembro en el número inicial de intervalos de página especificados en la matriz lpPageRanges . Cuando la función PrintDlgEx devuelve, nPageRanges indica el número de intervalos de páginas especificados por el usuario almacenados en la matriz lpPageRanges . Si se especifica la marca PD_NOPAGENUMS , este valor no es válido.

nMaxPageRanges

Tipo: DWORD

Tamaño, en elementos de matriz, del búfer lpPageRanges . Este valor indica el número máximo de intervalos de páginas que se pueden almacenar en la matriz. Si se especifica la marca PD_NOPAGENUMS , este valor no es válido. Si no se especifica la marca PD_NOPAGENUMS , este valor debe ser mayor que cero.

lpPageRanges

Tipo: LPPRINTPAGERANGE

Puntero a un búfer que contiene una matriz de estructuras PRINTPAGERANGE . En la entrada, la matriz contiene los intervalos de página iniciales que se van a mostrar en el control Edición de páginas . Cuando la función PrintDlgEx devuelve, la matriz contiene los intervalos de página especificados por el usuario. Si se especifica la marca PD_NOPAGENUMS , este valor no es válido. Si no se especifica la marca PD_NOPAGENUMS , lpPageRanges debe ser distinto de NULL.

nMinPage

Tipo: DWORD

Valor mínimo para los intervalos de página especificados en el control De edición de páginas . Si se especifica la marca PD_NOPAGENUMS , este valor no es válido.

nMaxPage

Tipo: DWORD

Valor máximo de los intervalos de página especificados en el control De edición de páginas . Si se especifica la marca PD_NOPAGENUMS , este valor no es válido.

nCopies

Tipo: DWORD

Contiene el número inicial de copias para el control de edición Copias si hDevMode es NULL; de lo contrario, el miembro dmCopies de la estructura DEVMODE contiene el valor inicial. Cuando se devuelve PrintDlgEx , nCopies contiene el número real de copias que debe imprimir la aplicación. Este valor depende de si la aplicación o el controlador de impresora son responsables de imprimir varias copias. Si la marca de PD_USEDEVMODECOPIESANDCOLLATE se establece en el miembro Flags , nCopies siempre es 1 en devolución y el controlador de impresora es responsable de imprimir varias copias. Si no se establece la marca, la aplicación es responsable de imprimir el número de copias especificadas por nCopies. Para obtener más información, consulte la descripción de la marca PD_USEDEVMODECOPIESANDCOLLATE .

hInstance

Tipo: HINSTANCE

Si la marca de PD_ENABLEPRINTTEMPLATE se establece en el miembro Flags , hInstance es un identificador para la aplicación o la instancia de módulo que contiene la plantilla de cuadro de diálogo denominada por el miembro lpPrintTemplateName . Si la marca PD_ENABLEPRINTTEMPLATEHANDLE se establece en el miembro Flags , hInstance es un identificador de un objeto de memoria que contiene una plantilla de cuadro de diálogo. Si ninguna de las marcas de plantilla está establecida en el miembro Flags , hInstance debe ser NULL.

lpPrintTemplateName

Tipo: LPCTSTR

Nombre del recurso de plantilla del cuadro de diálogo en el módulo identificado por el miembro hInstance . Esta plantilla reemplaza la plantilla de cuadro de diálogo predeterminada en la parte inferior de la página General . La plantilla predeterminada contiene controles similares a los del cuadro de diálogo Imprimir . Este miembro se omite a menos que la marca de PD_ENABLEPRINTTEMPLATE esté establecida en el miembro Flags .

lpCallback

Tipo: LPUNKNOWN

Puntero a un objeto de devolución de llamada definido por la aplicación.

El objeto debe contener la clase IPrintDialogCallback para recibir mensajes para el cuadro de diálogo secundario en la parte inferior de la página General .

El objeto de devolución de llamada también debe contener la clase IObjectWithSite para recibir un puntero a la interfaz IPrintDialogServices . La función PrintDlgEx llama a IUnknown::QueryInterface en el objeto de devolución de llamada para IID_IPrintDialogCallback y IID_IObjectWithSite para determinar qué interfaces se admiten.

Si no desea recuperar ninguna de las informaciones de devolución de llamada, establezca lpCallback en NULL.

nPropertyPages

Tipo: DWORD

Número de identificadores de página de propiedades en la matriz lphPropertyPages .

lphPropertyPages

Tipo: HPROPSHEETPAGE*

Contiene una matriz de identificadores de página de propiedades que se van a agregar a la hoja de propiedades Print . Las páginas de propiedades adicionales siguen la página General . Use la función CreatePropertySheetPage para crear estas páginas adicionales. Cuando se devuelve la función PrintDlgEx , se han destruido todos los identificadores HPROPSHEETPAGE de la matriz lphPropertyPages . Si nPropertyPages es cero, lphPropertyPages debe ser NULL.

nStartPage

Tipo: DWORD

Página de propiedades que se muestra inicialmente. Para mostrar la página General , especifique START_PAGE_GENERAL. De lo contrario, especifique el índice de base cero de una página de propiedades de la matriz especificada en el miembro lphPropertyPages . Para mantener la coherencia, se recomienda que la hoja de propiedades siempre se inicie en la página General .

dwResultAction

Tipo: DWORD

En la entrada, establezca este miembro en cero. Si la función PrintDlgEx devuelve S_OK, dwResultAction contiene el resultado del cuadro de diálogo. Si PrintDlgEx devuelve un error, se debe omitir este miembro. El miembro dwResultAction puede ser uno de los valores siguientes.

PD_RESULT_APPLY

El usuario ha clic en el botón Aplicar y, después, ha clic en el botón Cancelar . Esto indica que el usuario quiere aplicar los cambios realizados en la hoja de propiedades, pero aún no desea imprimir. La estructura PRINTDLGEX contiene la información especificada por el usuario en el momento en que se hizo clic en el botón Aplicar .

PD_RESULT_CANCEL

El usuario ha clic en el botón Cancelar . La información de la estructura PRINTDLGEX no cambia.

PD_RESULT_PRINT

El usuario ha clic en el botón Imprimir . La estructura PRINTDLGEX contiene la información especificada por el usuario.

Observaciones

Si hDevMode y hDevNames son NULL, PrintDlgEx inicializa la hoja de propiedades con la impresora predeterminada actual. Para inicializar la hoja de propiedades de una impresora diferente, utilice el miembro wDeviceOffset de la estructura DEVNAMES para especificar el nombre de la impresora.

Tenga en cuenta que el miembro dmDeviceName de la estructura DEVMODE también especifica un nombre de impresora. Sin embargo, dmDeviceName está limitado a 32 caracteres y el nombre wDeviceOffset no lo es. Si los nombres wDeviceOffset y dmDeviceName no son los mismos, PrintDlgEx inicializa la hoja de propiedades con la impresora especificada por wDeviceOffset.

Si se establece la marca PD_RETURNDEFAULT y hDevMode y hDevNames son NULL, PrintDlgEx usa los miembros hDevNames y hDevMode para devolver información sobre la impresora predeterminada actual sin mostrar el cuadro de diálogo.

Durante la ejecución de PrintDlgEx, es posible que las estructuras DEVMODE y DEVNAMES especificadas en la estructura PRINTDLGEX no siempre contengan datos actuales. Por este motivo, las páginas de propiedades específicas de la aplicación, así como las rutinas IPrintDialogCallback de la página inicial deben usar la interfaz IPrintDialogServices para recuperar información sobre el estado de la impresora actual.

Requisitos

Consulte también

Biblioteca de cuadros de diálogo comunes

Conceptual

DEVMODE

DEVNAMES

IPrintDialogCallback

IPrintDialogServices

PrintDlgEx

Referencia