DTWAIN_SelectSource2Ex
|
The DTWAIN_SelectSource2Ex function allows the user to select the TWAIN Source and position the TWAIN Select Source dialog, with the option to include / exclude TWAIN Sources from the TWAIN Select Source dialog, and change the name that is displayed in the TWAIN dialog for a particular source.
DTWAIN_SOURCE DTWAIN_SelectSource2 (
Parameters hWndParent Points to the window that will be the parent of the Twain Select Source dialog, or NULL if no parent window.
szTitle Optional title, or NULL.
xpos, ypos Position of the Select Source dialog with respect to the parent window.
lpszIncludeNames Pipe separated string of TWAIN Product Names to include in the Select Source Dialog or NULL. lpszExcludeNames Pipe separated string of TWAIN Product Names to exclude in the Select Source Dialog or NULL lpszNameMapping Pipe separated string of names to be used for particular Sources. flags Optional window placement flags.
Return Values If successful, the return value is a non-zero DTWAIN_SOURCE handle to the selected Source. Otherwise NULL is returned.
Character specific version
Comments The DTWAIN_SelectSource2Ex function displays the TWAIN 'Select Source' dialog box and returns a handle to the Source that is selected by the user. If the user chooses 'Cancel' from the dialog, DTWAIN_SelectSource2 returns NULL. The DTWAIN_SOURCE return value is used for any other DTWAIN function that requires a Source handle.
The difference between DTWAIN_SelectSource2Ex and DTWAIN_SelectSource2 is that DTWAIN_SelectSource2Ex allows the application to rename and/or include/remove Source names from the TWAIN Select Source dialog. Including and Excluding names from the TWAIN Select Source dialog The lpszIncludeNames is a pipe-delimited string that determines what names will be included in the TWAIN Select Source dialog, or NULL if there will not be any name filtering done to include names. For example, assume that there are 3 installed TWAIN devices with product names "HP Scanner", "Fujitsu Scanner" and "Canon Scanner". If you want to only show "HP Scanner" and "Canon Scanner" in the TWAIN Select Source dialog, the lpszIncludeNames string would be: The lpszExcludeNames is a pipe-delemited string that determines what names will be excluded in the TWAIN Select Source dialog, or NULL if there will not be any name filtering done to exclude names. For example, assume that there are 3 installed TWAIN devices with product names "HP Scanner", "Fujitsu Scanner" and "Canon Scanner". If you want to remove the "Canon Scanner" and "Fujitsu Scanner" from the TWAIN Select Source dialog, lpszExcludeNames string would be: Canon Scanner|Fujitsu Scanner Given that there is a choice between including and excluding names, it is recommended to use either lpszIncludeNames or lpszExcludeNames, depending on which argument is easier to express. For example, if you have 6 TWAIN devices and only want to exclude one of them, the simplest choice would be to use lpszExcludeNames and specify the excluded name, and set lpszIncludeNames to NULL. On the other hand, if you have 6 TWAIN devices and want to include only one, then use lpszIncludeNames, specifying only the single device. Changing Source names in the TWAIN Select Source dialog The lpszNameMapping denotes a mapping between the TWAIN Source's Produce Name and the name being displayed in the TWAIN Select Source dialog. The syntax of the mapping is as follows: ProductName1=AliasName1|ProductName2=AliasName2|...ProductNamen=AliasNamen where ProductNamex is the Product Name of the device, and AliasNamex is the name you want to show in the TWAIN Select Source dialog instead of ProductNamex. Note that you can have more than one set of ProductName/AliasName's, to be separated by the pipe character. So for example: "HP Scanner=My HP Scanner|Canon Scanner=My Canon Scanner" will display "My HP Scanner" instead of "HP Scanner" and "My Canon Scanner" instead of "Canon Scanner". Please note that even though the names are changed in the Select Source dialog, the original Product names are still used internally. Thus only use the mapping feature for purely user-interface purposes -- do not rely on DTWAIN to use the aliased name when actually communicating with the TWAIN device.
TWAIN State Transitions Remains in State 3.
Prerequisite Calls
Optional Prerequisite Calls None.
See Also |