winspool.h

PRINTDLG

Definición

typedef struct tagPD {  // pd  
    DWORD     lStructSize; 
    HWND      hwndOwner; 
    HANDLE    hDevMode; 
    HANDLE    hDevNames; 
    HDC       hDC; 
    DWORD     Flags; 
    WORD      nFromPage; 
    WORD      nToPage; 
    WORD      nMinPage; 
    WORD      nMaxPage; 
    WORD      nCopies; 
    HINSTANCE hInstance; 
    DWORD     lCustData; 
    LPPRINTHOOKPROC lpfnPrintHook; 
    LPSETUPHOOKPROC lpfnSetupHook; 
    LPCTSTR    lpPrintTemplateName; 
    LPCTSTR    lpSetupTemplateName; 
    HANDLE    hPrintTemplate; 
    HANDLE    hSetupTemplate; 
} PRINTDLG;

La estructura PRINTDLG contiene información que la función PrintDlg usa para inicializar un cuadro de diálogo común de impresión. Después de que el usuaior cierre el diálogo, el sistema devuelve en esta misma estructura información sobre las selecciones de impresión de usuario.

Descripción

lStructSize: Especifica el tamaño de la estructura en bytes.

hwndOwner: Identifica la ventana a la que pertenece el cuadro de diálogo. Este miembro puede tener cualquier manipulador de ventana válido, o puede ser NULL si el cuadro de diálogo no tiene propietario.

hDevMode: Identifica un objeto de memoria global movible que contiene una estructura DEVMODE. Antes de una llamada a la función PrintDlg, los miembros de la estructura deben contener datos usados para inicializar los controles del diálogo. Cuando PrintDlg regresa, los miembros de la estructura especifican el estado de los controles del cuadro de diálogo.

Si se usa la estructura para inicializar los controles del cuadro de diálogo, se debe reservar espacio para ello y crea la estructura DEVMODE. (Se debe reservar un bloque de memoria movible.)

Si no se usa la estructura para inicializar los controles del cuadro de diálogo, hDevMode debe ser NULL. En este caso, PrintDlg reserva memoria para la estructura, inicializa sus miembros, y devuelve un manipulador que lo identifica.

Si el controlador de dispositivo para la impresora especificada no soporta modos de dispositivo extendidos, hDevMode será NULL cuado PrintDlg regrese.

Si el nombre de dispositivo (especificado mediante el miembro dmDeviceName de la estructura DEVMODE) no aparece en la sección [devices] de WIN.INI, PrintDlg retornará un error.

Debido a que se trata de un objeto de memoria global y movible, el valor de hDevMode puede cambiar durante la ejecución de PrintDlg.

Para ver una explicación de cómo el sistema resuelve una posible colisión de datos entre los valores especificados por los miembros hDevMode y hDevNames, ver la siguiente sección de observaciones.

hDevNames: Identifica un objeto de memoria global movible que contiene una estructura DEVNAMES. Esta estructura contiene tres cadenas que especifican el nombre del controlador, el de la impresora y el del puerto de salida. Antes de la llamada a PrintDlg, los miembros de la estructura contienen cadenas usadas para para inicializar los controles del cuadro de diálogo. Cuando PrintDlg regresa, los miembros de la estructura contienen las cadenas introducidas por el usuario. La aplicación usa estas cadenas para crear un contexto de dispositivo o un contexto de información.

Si se usa la estructura para inicializar los controles del cuadro de diálogo, se debe reservar espacio y crear la estructura DEVNAMES. (Se debe reservar un bloque de memoria global movible.)

Si no se usa la estructura para inicializar los controles del cuadro de diálogo, hDevNames debe ser NULL. En ese caso, PrintDlg reserva memoria para la estructura, inicializa sus miembros (usando el nombre de impresora especificado en la estructura DEVMODE), y retorna un manipulador que lo identifica. PrintDlg usa el primer nombre de puerto que aparezca en la sección [devices] de WIN.INI cuando inicializa los miembros en la estructura DEVNAMES. Por ejemplo, la función usa "LPT1:" como nombre de puerto si la siguiente cadena aparece en la sección [devices]:

PCL / HP LaserJet=HPPCL,LPT1:,LPT2:

Si tanto hDevMode como hDevNames son NULL, PrintDlg inicializará hDevNames usando la impresora por defecto actual.

Como esta estructura es un obejeto global móvil, el valor de hDevNames puede cambiar durante la ejecución de PrintDlg.

Para una explicación de como el sistema resuelve una posible colisión de datos entre valores especificados por hDevNames y hDevMode, ver la sección de observaciones más adelante.

hDC: Identifica un contexto de dispositivo o un contexto de información, dependiendo de si el miembro Flags especifica la bandera PD_RETURNDC o PC_RETURNIC. Si no se especifica ninguna de las dos banderas, el valor de este miembro queda indefinido. Si se especifican ambos, PD_RETURNDC tiene prioridad.

Flags: Un conjunto de banderas de bit que se pueden usar para inicializar el cuadro de diálogo común de impresión. Cuando el cuadro de diálogo regresa, activa esas banderas para indicar las entradas del usuario. Este miembro puede ser una combinación de las siguientes banderas:

PD_ALLPAGES	La bandera por defecto que indica que todos los radio buttons están seleccionados inicialmente. Esta bandera se usa como plantilla para indicar que no se han especificado las banderas PD_PAGENUMS y PD_SELECTION.
PD_COLLATE	Coloca una marcha de chequeo en el check box "Intercalar" cuando se establece en la entrada. Cuando la función PrintDlg regresa, esta bandera indica que el usuario ha seleccionado la opción de "Intercalar" y el controlador de la impresora no soporta el intercalado. En ese caso, la aplicación debe proporcionar el intercalado. Si PrintDlg activa la bandera PD_COLLATE a su regreso, el miembro dmCollate de la estructura DEVMODE queda indefinido.
PD_DISABLEPRINTTOFILE	Inhabilita el check box de "Imprimir a fichero".
PD_ENABLEPRINTHOOK	Habilita el procedimiento gancho especificado en el miembro lpfnPrintHook. Esto permite un procedimiento "gancho" para el cuadro de diálogo de impresión.
PD_ENABLEPRINTTEMPLATE	Indica que los miembros hInstance y lpPrintTemplateName especifican una la plantilla de cuadro de diálogo que se usará en lugar de la plantilla por defecto para el cuadro de diálogo de impresión.
PD_ENABLEPRINTTEMPLATEHANDLE	Indica que el miembro hPrintTemplate identifica un bloque de datos que contiene una plantilla de cuadro de diálogo precargada. El sistema usa esta plantilla en lugar de la plantilla por defecto para el cuadro de diálogo de impresión. El sistema ignora el miembro lpPrintTemplateName si se especifica esta bandera.
PD_ENABLESETUPHOOK	Habilita el procedimiento "gancho" espeficado en el miembro lpfnSetupHook. Esto activa un procedimiento "gancho" para el cuadro de diálogo de preparación de impresión.
PD_ENABLESETUPTEMPLATE	Indica que los miembros hInstance y lpSetupTemplateName especifican una plantilla de cuadro de diálogo que se usará en lugar de la plantilla por defecto para el cuadro de diálogo de preparación de impresión.
PD_ENABLESETUPTEMPLATEHANDLE	Indica que el miembro hSetupTemplate identifica un bloque de datos que contiene una plantilla de cuadro de diálogo percargada. El sistema usa esta plantilla en lugar de la plantilla por defecto del cuadro de diálogo de preparación de impresión. El sistema ignora el miembro lpSetupTemplateName si se especifica esta bandera.
PD_HIDEPRINTTOFILE	Oculta el check box de "Imprimir a fichero".
PD_NOPAGENUMS	Inhibe el radio button "Páginas" y el control de edición asociado.
PD_NOSELECTION	Inhibe el radio button de "Selección".
PD_NOWARNING	Evita que se muestre el mensaje de advertencia cuando no existe impresora predeterminada.
PD_PAGENUMS	Hace que el radio button "Páginas" esté en el estado seleccionado cuando se crea el cuadro de diálogo. Cuando PrintDlg regresa, esta bandera estará activa si el radio button "Páginas" está seleccionado.
PD_PRINTSETUP	Hace que el sistema muestre el cuadro de diálogo de preparación de impresión en lugar del cuadro de diálogo de impresión.
PD_PRINTTOFILE	Hace que el check box de "Imprimir a fichero" esté marcado cuando el cuadro de diálogo es creado. Cuando PrintDlg regresa, esta bandera estará activa si el check box está marcado. En ese caso, el desplazamiento indicado por el miembro wOutputOffset de la estructura DEVNAMES contiene la cadena "FILE:". Cuando se llame a la función StartDoc para comenzar el proceso de impresión, especificar esta cadena "FILE:" en el miembro lpszOutput de la estructura DOCINFO. Especificar esta cadena hace que el subsistema de impresión pregunte al usuario el nombre el fichero de salida.
PD_RETURNDC	Hace que PrintDlg retorne un contexto de dispositivo que coincida con las selecciones que el usuario haya hecho en el cuadro de diálogo. El contexto de dispositivo se devuelve en hDC.
PD_RETURNDEFAULT	La función no muestra el cuadro de diálogo. En su lugar, asigna los miembros hDevNames y hDevMode para manipular las estructuras DEVMODE y DEVNAMES que son inicializados para la impresora por defecto del sistema. Tanto hDevNames como hDevMode deben ser NULL, en caso contrario PrintDlg retorna un error. Si la impresora por defecto está soportado por un controlador de impresora antiguo (anterior a Windows versión 3.0), sólo se devuelveo hDevNames; hDevMode es NULL.
PD_RETURNIC	Similar a la bandera PD_RETURNDC, excepto que esta bandera retorna un contexto de información en lugar de un contexto de dispositivo. Si no se especifica PD_RETURNDC ni PD_RETURNIC, hDC queda indefinida en la salida.
PD_SELECTION	Hace que el radio button "Selección" quede en el estado seleccionado cuando se crea el cuadro de diálogo. Cuando PrintDlg regresa, esta bandera se especifica si el radio button está seleccionado. Si no están activos PD_PAGENUMS ni PD_SELECTION, se selecciona el radio button "Todo".
PD_SHOWHELP	Hace que el cuadro de diálogo muestre el botón de "Ayuda". El miembro hwndOwner debe especificar la ventana que recibirá los mensajes HELPMSGSTRING registrados que el cuadro de diálogo envía cuando el usuario pulsa el botón de ayuda.
PD_USEDEVMODECOPIES	Lo mismo que PD_USEDEVMODECOPIESANDCOLLATE.
PD_USEDEVMODECOPIESANDCOLLATE	Inhibe el control de edición "Copias" si el controlador de impresora no soporta copias múltiples, e inhibe el check box "Intercalar" si el controlador de la impresora no soporta intercalado. Si no se especifica esta bandera, PrintDlg almacena las selecciones del usuario para las opciones de copias e intercalar en los miembros dmCopies y dmCollate de la estructura DEVMODE. Si esta bandera no está activa, la información de copias e intercalado se devuelve en la estructura DEVMODE si el controlador soporta múltiples copias e intercalado. Si el controlador no soporta estas características, la información se devuelve en la estructura PRINTDLG. Esto significa que la aplicación sólo debe consultar los valores de nCopies y PD_COLLATE para determinar cuantas copias necesita hacer y si es necesario imprimirlas intercaladas.

nFromPage: Especifica el valor inicial de la página de comienzo en el control de edición. Cuando PrintDlg regresa, nFromPage especifica la página de inicio indicada por el usuario. Este valor sólo es válido si se especifica la bandera PD_PAGENUMS.

nToPage: Especifica el valor inicial para la última página en el control de edición. Cuando la función PrintDlg regresa, nToPage especifica la última página indicada por el usuario. Este valor sólo es válido si se especifica la bandera PD_PAGENUMS.

nMinPage: Especifica el valor mínimo para el rángo de páginas indicados en los controles de edición "Desde" y "Hasta".

nMaxPage: Especifica el valor máximo para el rángo de páginas indicados en los controles de edición "Desde" y "Hasta"

nCopies: Contiene en número inicial de copias para el cuadro de edición "Copias" si hDevMode es NULL; en caso contrario, el miembro dmCopies de la estructura DEVMODE contiene el valor inicial. Cuando PrintDlg regresa, este miembro contiene el número de copias actual a imprimir. Si el controlador de impresora no soporta múltiples copias, este valor puede ser mayor que uno, y la aplicación debe imprimir todas la copias requeridas. Si se especifica el valor PD_USEDEVMODECOPIESANDCOLLATE en el miembro Flags, nCopies siempre es 1 al retornar y el miembro dmCopies de DEVMODE recibe el número actual de copias a imprimir.

hInstance: Si la bandera PD_ENABLEPRINTTEMPLATE o PD_ENABLESETUPTEMPLATE están activas en el miembro Flags, hInstance es el manipulador de la aplicación de la instancia del módulo que contiene la plantilla de cuadro de diálogo cuyo nombre está indicado por el miembro lpPrintTemplateName o lpSetupTemplateName.

lCustData: Especifica los datos definidos por la aplicación que el sistema le pasa al procedimiento "gancho" identificado por el miembro lpfnPrintHook o lpfnSetupHook. Cuando el sistema envía el mensaje WM_INITDIALOG al procedimiento "gancho", el parámetro lParam del mensaje es un puntero a la estructura PRINTDLG especificada cuando se creó el diálogo. EL procedimiento "gancho" puede usar ese puntero para obtener el valor lCustData.

lpfnPrintHook: Puntero a un procedimiento "gancho" PrintHookProc que puede procesar mensajes destinados al cuadro de diálogo de impresión. Este miembro es ignorado a no ser que se especifique la bandera PD_ENABLEPRINTHOOK en el miembro Flags.

lpfnSetupHook: Puntero a un procedimiento "gancho" SetupHookProc que puede procesar mensajes destinados al cuadro de diálogo de preparación de impresión. Este miembro es ignorado a no ser que se especifique la bandera PD_ENABLESETUPHOOK en el miembro Flags.

lpPrintTemplateName: Puntero a una cadena terminada en cero que nombra un recurso de plantilla de cuadro de diálogo en el módulo identificado por el miembro hInstance. Esta plantilla sustituye a la plantilla estándar de cuadro de diálogo de impresión. Este miembro es ignorado salvo que se active la bandera PD_ENABLEPRINTTEMPLATE en el miembro Flags.

lpSetupTemplateName: Puntero a una cadena terminada en cero que nombra un recurso de plantilla de cuadro de diálogo en el módulo identificado por el miembro hInstance. Esta plantilla sustituye a la plantilla estándar de cuadro de diálogo de preparación de impresión. Este miembro es ignorado salvo que se active la bandera PD_ENABLEPRINTTEMPLATE en el miembro Flags.

hPrintTemplate: Si se activa la bandera PD_ENABLEPRINTTEMPLATEHANDLE en el miembro Flags, hPrintTemplate es el manipulador de un objeto de memoria que contiene la plantilla del cuadro de diálogo. Esta plantilla sustituye a la plantilla estándar de cuadro de diálogo de impresión.

hSetupTemplate: Si se activa la bandera PD_ENABLEPRINTTEMPLATEHANDLE en el miembro Flags, hSetupTemplate es el manipulador de un objeto de memoria que contiene la plantilla del cuadro de diálogo. Esta plantilla sustituye a la plantilla estándar de cuadro de diálogo de preparación de impresión.

Observaciones

Es posible que se produzca una colisión de datos entre los valores especificados por hDevNames y hDevMode ya que se supone que el miembro wDeviceOffset de la estructura DEVNAMES debe ser idéntico al miembro dmDeviceName de la estructura DEVMODE. Si no lo son, el sistema resuelve la colisión usando el valor de wDeviceOffset.

Si el usuario marca el checkbox del intercalado en el cuadro de diálogo común de impresión, pero en controlador de la impresora no soporta intercalado, el miembro Flags de la estructura PRINTDLG retornada por PrintDlg incluye la bandera PD_COLLATE. Además, el miembro dmCollate de la estructura DEVMODE identificado por el miembro hDevMode tendrá el valor COLLATE_TRUE. Si la bandera PD_COLLATE está activa, la aplicación debe simular el intercalado.

Si la bandera PD_USEDEVMODECOPIESANDCOLLATE está activa, el checkbox "Intercalado" aparecerá en gris si el controlador de la impresora no soporta intercalado. Esto asegura que el usuario sólo puede selecciona una copia, y que nCopies será uno. Si el controlador soporta múltiples copias, dmCopies podrá contener el número de copias y nCopies será uno.

A la entrada de PrintDlg, el miembro nCopies de la estructura PRINTDLG especifica el número de copias si PD_USEDEVMODECOPIESANDCOLLATE no está activo. A la salida de PrintDlg, nCopies contiene el número de copias si el controlador de impresora no soporta múltiples copias. En caso contrario contendrá el valor uno. Si nCopies es mayor que uno a la salida de PrintDlg, la aplicación debe imprimir múltiples copias del documento.