DTwainSource::Select

Syntax

static DTwainSource DTwainSource::Select( const std::string & SourceName, bool bOpenSource=true );

static DTwainSource DTwainSource::Select( bool bOpenSource=true );

static DTwainSource DTwainSource::Select( HWND hWndParent, const std::string& sTitle, int xPos, int yPos,

                                                                      LONG flags=0, bool bOpenSource=true);

Parameters

SourceName

Source product name.

bOpenSource

Indicates if Source is to be opened when selected.

hWndParent

Handle to parent window of the "Select Source" dialog or NULL if no parent window.

sTitle

Title of the Select Source window

xPos, yPos

The x and y position of the "Select Source" dialog, relative to hWndParent.

flags

Centering window and sorting options when "Select Source" dialog is used.

Returns

On successful return, a new DTwainSource object will be returned representing the selected TWAIN Source.

Comments

The CDTwainSource::Select functions are static functions that allow the application to select the TWAIN Source.  The DTwainSource::Select function is overloaded so as to allow different forms of selecting the Source.  If you want to select the default Source (the last Source that was opened, or if only one TWAIN Source exists), then call DTwainSource::SelectDefault( ).

For all of these functions, the bOpenSource argument determines whether the TWAIN Source will be opened when it is selected.  All Sources must be opened before doing any operation on the Source, so by default, bOpenSource is true.

If the user cancels selecting the Source, then the returned DTwainSource will be invalid.  To test this, the DTwainSource::IsValid( ) function can be used to test if the user actually selected a TWAIN Source, or just cancelled the selection.

Example:

DTwainSource Source = DTwainSource::Select( );

if ( !Source.IsValid( ) )

{

   // User didn't select a Source

}

A description of each of the overloads of DTwainSource::Select are as follows:

This usage of Select will allow you to select a TWAIN Source by using the product name of the Source.  The SourceName is the product name of the Source.  The TWAIN Source dialog will not be displayed.

This usage of Select will display the TWAIN "Select Source" dialog.

                                                                         LONG nOptions=0, bool bOpenSource=true);

This usage of Select will display the TWAIN "Select Source" dialog, but with various options such as the position of the Select Source dialog, and the title used in the dialog.  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.

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 a 0-length string, the title is "Select Source".  You must not pass a NULL for szTitle.  The reason is that assigning NULL to a std::string (which the compiler will attempt to do when you pass a NULL) is undefined behavior, and may crash your program.

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

As an example, to place the Twain dialog on the center of the screen, the following would be used:

DTwainSource::Select( NULL, "", 0, 0, DTWAIN_DLG_CENTER );

To place the dialog at (20,20) of a particular window, the following would be used:

DTwainSource::Select( hWnd, "", 20, 20 );

To center the dialog on the screen, have the title "My Twain Dialog", and have sorted Source names:

DTwainSource::Select( NULL, "My Twain Dialog", 0, 0,  DTWAIN_DLG_SORTNAMES + DTWAIN_DLG_CENTER );

If more customization is desired in selecting a Source (for example, you may want to create your own interface that displays the Sources to select), call DTwainSource::EnumSources, get all of the product names, and then present all of the product names found in your own custom interface to the user.  When the user chooses one of the Sources from your interface, your application would call

DTwainSource::Select( "product_name");

  where "product_name" would be the name of the Source you want to select.