Table of Contents

23.7 Component gb.scanner

The Gambas scanner component gb.scanner consists of the three classes

It enables the simple management and control of scanner devices in Gambas code. The classes use the ScanImage programme, which is provided in the SANE project as a line command-oriented front-end tool.

23.7.1 Class Scanners

To be able to create scanner objects and work with them, you must first find out how the scanner used has registered as a device in the system. The Scanners class is available for this purpose. You can create the class and it acts as a read-only array that contains a list of the Scanner object type and can be enumerated using FOR-EACH. It does not provide any properties, but has two methods and an event.

23.7.1.1 Methods

The methods of the Scanners class:

MethodDescription
Close ()This static method closes a possibly running process of ScanImage.
Search ([ bWait as Boolean ])Initiates the search for scanners. If the option is used with bWait = True, the application blocks until the scanner list is complete. If the option is not used or bWait = False, the search is performed in the background.

Table 23.7.1.1.1 : Methods of the Scanners class

23.7.1.2 Events

The Scanners class only has this event:

EventDescription
Found ( )The event is triggered when the search for scanners has been completed.

Table 23.7.1.2.1 : Event of the Scanners class

The search process initiated by the Search method takes place in the background and ends in the Scanners_Found() event, in which the evaluation can take place. So that the class can trigger this event in the parent class, it must be registered accordingly with the Object.Attach instruction:

'-- Attach Scanner static class to the form class to catch events
Object.Attach(Scanners, Me, "Scanners")
 
'-- Start searching for scanners
Scanners.Search
... 
 
'' End of search and enumeration of scanners
Public Sub Scanners_Found()
  Dim s As String
 
  For Each s In Scanners
    ComboBoxScanners.Add(Scanners[s].name)
  Next
  If ComboBoxScanners.count > 0 Then
     ComboBoxScanners.Index = 0
  Else
    Message.Error("No scanner found.")
    Quit  
  Endif
 
End 

Alternatively, this can also be implemented in the usual way:

Dim MyScanners As Scanners
 
MyScanners = New Scanners As "MyScanners"
MyScanners.Search()
...
 
'' End of search and enumeration of scanners
Public Sub MyScanners_Found()
 
Dim s As String
 
  For Each s In Scanners
    ComboBoxScanners.Add(Scanners[s].Name)
  Next
  If ComboBoxScanners.count > 0 Then
     ComboBoxScanners.Index = 0
  Else
     Message.Error("No scanner found.")
     Quit  
  Endif
 
End 

23.7.2 Scanner class

The Scanner class represents a scanner as a device and provides the basis for working with the device with the Scanner object.

23.7.2.1 Properties

The Scanner class has these properties:

PropertyData typeDescription
AsyncBooleanReturns or sets the process mode to be used. If True, all processes are executed in the background, while the default value False stops the programme run for the duration of the process.
DebugBooleanReturns or sets the debug mode. If True, the internally used ScanImage CLI commands are output in the IDE console for control purposes. The default value is False.
ModelStringReturns the model of the scanner.
NameStringReturns the device name of the scanner.
ProgressFloatReturns the progress of the scan process. The value is between 0 and 1; corresponding to 0% to 100%.
TypeStringThis value is supplied by the scanner and returns the type of scanner, for example “flatbed scanner”.
VendorStringThis value is supplied by the scanner and returns the manufacturer of the scanner.

Table 23.7.2.1.1 : Properties of the Scanner class

To create a new Scanner object:

Dim hScanner As Scanner
hScanner = New Scanner ( sDevice As String )  As "EventName" 

Based on the recognition of existing scanners described above, this could look as follows:

Dim hScanner As Scanner
hScanner = New Scanner(ComboBoxScanners.Text) As "hScanner"
hScanner.Async = True

The class is enumerable with FOR-EACH and provides the names of all available scanner options:

Dim sOption As String

For Each sOption In hScanner
  Print sOption
Next

23.7.2.2 Methods

The Scanner class has the following methods:

MethodReturn typeDescription
Exist ( Key As String )BooleanReturns whether the scanner has a property/function that is defined by a key, for example “Contrast” or “Brightness”.
Find ( Key As String )ScannerOption Performs a search for a scanner option defined by the key. If successful, a scanner option is returned. If unsuccessful, the scanner option is empty.
IsAvailable ( )BooleanReturns true if the scanner is available.
Peek ( )ImageReturns the scanned image. The method can only be used in Async = True mode in the PageEnd event or in Async = False mode after the scan process has been completed.
Scan ( )ImageStarts the scan process.

Table 23.7.2.2.1 : Methods of the Scanner class

You can use the Scanner class to determine, among other things, whether the scanner used offers the brightness setting:

If hScanner.Exist("Brightness") Then
   Print hScanner["Brightness"].MinValue	' Minimum value of this option
   Print hScanner["Brightness"].MaxValue    	' Maximum value of this option
   Print hScanner["Brightness"].Value	   	' Default value of this option
Endif

Alternative:

Print hScanner.Find("Brightness").MinValue
Print hScanner.Find("Brightness").MaxValue
Print hScanner.Find("Brightness").Value

23.7.2.3 Events

The Scanner class has these events:

EventDescription
Begin ( )This event is triggered immediately after the scan method is applied.
End ( )This event is the last of a scan process and is triggered after the Finished() event.
Error ( ErrorText As String )This event is triggered when an error occurs. The ErrorText variable returns the corresponding error message.
Finished ( )This event is triggered at the end of the page scan and may include the return of the scanner mechanism.
PageBegin ( )This event is triggered immediately before a page is scanned.
PageEnd ( )This event is triggered immediately after a page has been scanned. The event routine is typically used to read the scanned image.
Progress ( )This event is triggered periodically during the scan for the purpose of progress control. Within the event routine, a value between 0 and 1 (corresponding to 0% to 100%) is available for progress control with Last.Progress.

Table 23.7.2.3.1 : Events of the Scanner class

Here is an example of how to read and display the scanned image in the PageEnd event routine:

Public Sub hScanner_PageEnd()
 
  Dim hImage As Image
 
  Try hImage = Last.Peek()
 
  If Not hImage Then
     Message.Error("Can't load image")
     Return
  Endif
 
  PictureBoxScan.Picture = hImage.Picture  
 
End

23.7.3 ScannerOption class

Experience has shown that the options available for a scanner vary greatly between models and manufacturers. It is up to the programmer to determine these and use them accordingly. The ScannerOptions class is available for this purpose, which attempts to provide all available options as corresponding properties with the help of a parser.

For this purpose, the parser receives a scanner-specific data record from the ScanImage programme. This looks like this for a (fictitious) scanner, for example

All options specific to device `quickscan:QS2000_192.xxx.xxx.xxx':
  Scan mode:
    --resolution 75|150|300|600|1200|2400|4800dpi [75]
        Sets the resolution of the scanned image.
    --mode auto|Color|Gray|Lineart [Color]
        Selects the scan mode (e.g., lineart, monochrome, or color).
    --source Flatbed [Flatbed]
        Selects the scan source (such as a document-feeder). Set source before
        mode and resolution. Resets mode and resolution to auto values.
  Geometry:
    -l auto|0..216.069mm [0]
        Top-left x position of scan area.
    -t auto|0..297.011mm [0]
        Top-left y position of scan area.
    -x auto|0..216.069mm [216.069]
        Width of scan-area.
    -y auto|0..297.011mm [297.011]
        Height of scan-area.
  Extras:
    --threshold auto|0..100% (in steps of 1) [inactive]
...

and provides the parser with values for adjustable resolutions (marked in red), which are made available as properties, in addition to many other parameters.

In contrast to the discrete values in the example above, values for the available resolutions can also be specified as a range, as the following example shows:

...
  --resolution 50..1200dpi [50]
...

To use the resolution values, it is therefore necessary to differentiate between these cases. The class provides the IsRange property for this purpose.

The options of the “Geometry” data group are intended for defining the section to be scanned. The class provides fixed names for this:

23.7.3.1 Properties

The ScannerOption class has the following properties, whereby its values can only be read with the exception of the Value property:

PropertyData typeDescription
GroupStringReturns the name of the data group in which the option is located, such as “Scan Mode” for the “Resolution” option.
InfoStringReturns information about an option - if available.
IsActiveBooleanReturns whether an option is active.
IsRangeBooleanReturns whether the option is specified as a range between 2 values - as opposed to discrete individual values.
ListString[]Returns a string array containing a list of discrete values of an option.
MaxValueFloatReturns the determined maximum value of the option, such as 4800∙dpi as the largest resolution.
MinValueFloatReturns the determined minimum value of the option, such as 75∙dpi as the lowest resolution.
ModifiedBooleanReturns whether the value of the “Value” property has been changed.
NameStringReturns the name of the option.
StepsIntegerReturns the step size with which the option is resolved between MinValue and MaxValue.
UnitStringReturns the unit of measurement for the option if this is defined using numerical values, such as “mm” for the “Width” option.
ValueVariantReturns or sets the current value of the option.

Table 23.7.3.1.1 : Properties of the ScannerOption class

Notes:

23.7.4 The gb.Scan project

In the gb.Scan project, whose source code archive is available for download, only native Gambas resources are used in order to present a scanning application that is as versatile as possible for everyday use.

The gb.Scan application has the following functions:

Display of the scans in a multi-select list with

Figure 23.7.4.1: Main window of the gb.Scan application

Notes:

Download

Chapter & Projects

Download