GAMBAS BOOK 3.19.1

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

• Scanners,
• Scanner and
• ScannerOption.

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.

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.

The methods of the Scanners class:

Table 23.7.1.1.1 : Methods of the Scanners class

The Scanners class only has this event:

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 

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

The Scanner class has these properties:

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

The Scanner class has the following methods:

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

The Scanner class has these events:

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

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:

• Left = distance to the left edge (in mm)
• Top = distance to the top edge (in mm)
• Width = Width of the scan (in mm)
• Height = Height of the scan (in mm)

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

Table 23.7.3.1.1 : Properties of the ScannerOption class

Notes:

• The name of the option always begins with a capital letter such as “Resolution”.
• This also applies if the option supplied by the scanner begins with a lowercase letter!

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:

• Scanning of entire pages or selected sections.
• Scanning in A4, A5, A6, US Letter and user-defined formats.
• Saves single-page or multi-page scans in JPG, PNG, BMP or PDF format.
• Sending single-page or multi-page scans in PDF format as email attachments.
• Print single-page or multi-page scans.
• Optional OCR function for creating searchable PDFs (experimental).
• Selection of scanner if more than one scanner is available.
• Saving and restoring the set parameters for each connected or selected scanner.
• Restore the size and position of the application windows.

Display of the scans in a multi-select list with

• Rotate the scans in 90° steps,
• Changing the order of the scans. Example: Before creating a multi-page PDF file,
• Delete scans. Example: Before creating a multi-page PDF file.

Figure 23.7.4.1: Main window of the gb.Scan application

Notes:

• The application requires QT5.
• The application currently uses the source code of the classes described because errors occurred within the Scanner class in two scanners from the manufacturer Canon that were available during development. These could each be rectified by a small modification and are labelled “Modified” in the source code of the class. In addition, the scope of the error messages issued in the Error event turned out to be a problem that could be solved by a further addition. Corresponding improvements have already been suggested to the developers.
• To rotate, delete or move scanned documents, individual or multiple entries can be selected with the mouse. The list uses the multi-select option for this. For all other operations such as emailing, printing or saving, all entries are always processed.
• When emailing, the generated PDF file is provided with a timestamp accurate to the second.
• When saving multiple scans in JPG, PNG or BMP format, the individual scans are given an additional three-digit index according to their order - such as Scan_001.jpg, Scan_002.jpg etc. .
• The optional and experimental OCR function is limited to the creation of searchable PDFs and can be installed later within the app.
• Double-click on a scan in the list to display it in the large scan display.
• Multi-page scanning with devices that have a feeder tray was not implemented because this type of scanner was not available during development.
• If one or other of the device options does not work as expected, the cause is more likely to be found in the SANE backend. Unfortunately, SANE compatibility lists proved to be an unreliable reference in two individual cases.