DTWAIN_SelectOCREngine2

DTWAIN_SelectOCREngine2A

DTWAIN_SelectOCREngine2W

The DTWAIN_SelectOCREngine2 function allows the user to select an OCR engine from a list of supported OCR Engines.

DTWAIN_OCRENGINE DTWAIN_SelectOCREngine2 (

HWND	hWndParent,
LPCTSTR	szTitle,
LONG	xpos,
LONG	ypos,
LONG	flags );

Parameters

hWndParent

Points to the window that will be the parent of the OCR Select 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.

flags

Optional window placement flags.

Return Values

If successful, the return value is a non-zero DTWAIN_OCRENGINE handle. Otherwise NULL is returned.

Character specific version

ANSI version:	DTWAIN_SelectOCREngine2A
Unicode version:	DTWAIN_SelectOCREngine2W

Comments

The DTWAIN_SelectOCREngine function displays the DTWAIN Select OCR Engine dialog box and returns a handle to the selected OCR Engine. If the user chooses 'Cancel' from the dialog, DTWAIN_SelectOCREngine returns NULL.

To determine if a NULL return value from DTWAIN_SelectOCREngine is due to the user cancelling the dialog or if there is another error, call DTWAIN_GetLastError and check if the value is non-zero (which means an error occurred). If DTWAIN_GetLastError returned 0, this means that the user canceled the dialog, which is perfectly valid for the user to do.

The DTWAIN_OCRENGINE return value is used for any other DTWAIN function that requires an OCR Engine handle.

The difference between DTWAIN_SelectOCREngine2 and DTWAIN_SelectOCREngine is that DTWAIN_SelectOCREngine2 allows the application to position the Select OCR dialog on the screen and place a title on the window. The hWndParent sets the dialog's parent window to hWndParent. If no parent window is desired, hWndParent must be NULL or 0. If hWndParent is NULL, the parent window is the entire screen.

Another difference is that DTWAIN_SelectOCREngine2 will allow the various controls within the dialog to use a custom language setting. Depending on the resources loaded (see DTWAIN_LoadLanguageResource and DTWAIN_LoadCustomStringResource), the various controls and buttons will display the text in the language selected.

The xpos and ypos arguments place the window at position (xpos, pos) with respect to the parent window (if no parent window, xpos and ypos are relative to the entire screen).

The szTitle argument is a null-terminated string that represents the title to display on the window. If szTitle is NULL, the title will be the localized string representing the English text "Select OCR Engine".

The flags parameter determine whether the dialog will be centered and whether the list of names displayed will be sorted. A list of available flag options are as follows (multiple options can be selected by adding the values together).

DTWAIN_DLG_CENTER	Centers the Select dialog on the parent window hWndParent. The xpos and ypos arguments are ignored.
DTWAIN_DLG_SORTNAMES	Sorts and displays the names in the dialog. Normally, the names are displayed in order of their time of installation.
DTWAIN_DLG_HORIZONTALSCROLL	Add horizontal scroll bar to list box that displays the names. Use this option if the Names will not fit horizontally within the list box.
DTWAIN_DLG_CENTER_SCREEN	Centers the dialog on the current Windows desktop. The xpos and ypos arguments are ignored.
DTWAIN_DLG_TOPMOSTWINDOW	Places the Select dialog on top of all other windows on the screen.
DTWAIN_DLG_HIGHLIGHTFIRST	Always highlight the first Source listed in the dialog.
DTWAIN_DLG_SAVELASTSCREENPOS	Use this flag to allow the user to move the Select dialog to an appropriate position on the screen, and have the dialog always appear in subsequent calls to DTWAIN_SelectOCREngine2() at the saved position. This flag will ignore the DTWAIN_DLG_CENTER, DTWAIN_DLG_CENTER_SCREEN, and xpos, ypos values when the dialog is displayed after the first call to DTWAIN_SelectOCREngine2()

To change the language used for the various buttons and text, a call to DTWAIN_LoadCustomStringResources can be used. If DTWAIN_LoadCustomStringResources is used, the following DTWAIN constants define the various components of the dialog:

Resource Name	Description
IDS_SELECT_OCRENGINE_TEXT	Dialog Title
IDS_SELECT_TEXT	"Select" button text
IDS_CANCEL_TEXT	"Cancel" button text
IDS_SOURCES_TEXT	Text above the Sources list box.

TWAIN State Transitions

Remains in State 3.

Prerequisite Calls

DTWAIN_SysInitialize

DTWAIN_InitOCRInterface

Optional Prerequisite Calls

None.