User Tools

Site Tools




23.7 Component gb.scanner

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.

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. Methods

The methods of the Scanners class:

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 : Methods of the Scanners class Events

The Scanners class only has this event:

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

Table : 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
'' End of search and enumeration of scanners
Public Sub Scanners_Found()
  Dim s As String
  For Each s In Scanners
  If ComboBoxScanners.count > 0 Then
     ComboBoxScanners.Index = 0
    Message.Error("No scanner found.")

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

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

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. 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 : 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 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 : 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


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

The Scanner class has these events:

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 : 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")
  PictureBoxScan.Picture = hImage.Picture  

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 `':
  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.
    -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.
    --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) 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 : Properties of the ScannerOption class


  • 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!

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:

  • 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 Main window of the gb.Scan application


  • 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.


Chapter & Projects


The website uses a temporary session cookie. This technically necessary cookie is deleted when the browser is closed. You can find information on cookies in our privacy policy.
k23/k23.7/start.txt · Last modified: 07.03.2024 by emma

Page Tools