GnomeScanContext

GnomeScanContext — The marshaller object that holds all other objects

Synopsis




            GnomeScanContext;
enum        GnomeScanContextError;
GnomeScanContext* gnome_scan_context_new    (void);
void        gnome_scan_context_destroy      (GnomeScanContext *context);
void        gnome_scan_context_probe_scanners
                                            (GnomeScanContext *context);
GSList*     gnome_scan_context_get_scanners (GnomeScanContext *context);
GnomeScanner* gnome_scan_context_get_scanner
                                            (GnomeScanContext *context);
void        gnome_scan_context_select_scanner
                                            (GnomeScanContext *context,
                                             GnomeScanner *scanner);
GnomeScanArea* gnome_scan_context_get_area  (GnomeScanContext *context);
void        gnome_scan_context_set_area     (GnomeScanContext *context,
                                             GnomeScanArea *area);
GdkPixbufRotation gnome_scan_context_get_rotation
                                            (GnomeScanContext *context);
void        gnome_scan_context_set_rotation (GnomeScanContext *context,
                                             GdkPixbufRotation rotation);
GnomeScannerSource gnome_scan_context_get_source
                                            (GnomeScanContext *context);
void        gnome_scan_context_set_source   (GnomeScanContext *context,
                                             GnomeScannerSource source);
GnomeScanForecast* gnome_scan_context_forecast
                                            (GnomeScanContext *context);
void        gnome_scan_context_acquire_preview
                                            (GnomeScanContext *context);
void        gnome_scan_context_start_acquisition
                                            (GnomeScanContext *context);

Object Hierarchy


  GObject
   +----GnomeScanContext

Properties


  "area"                 gpointer              : Read / Write
  "backend"              GnomeScanBackend      : Read / Write / Construct Only
  "rotation"             gint                  : Read / Write
  "scanner"              GnomeScanner          : Read / Write
  "scanners"             gpointer              : Read
  "x-resolution"         gint                  : Read / Write
  "y-resolution"         gint                  : Read / Write

Signals


"acquisition-paused"
            void        user_function      (GnomeScanContext *context,
                                            gpointer          user_data)      : Run first
"acquisition-resumed"
            void        user_function      (GnomeScanContext *context,
                                            gpointer          user_data)      : Run first
"acquisition-started"
            void        user_function      (GnomeScanContext  *context,
                                            GnomeScanForecast *forecast,
                                            gpointer           user_data)      : Run first
"acquisition-terminated"
            void        user_function      (GnomeScanContext *context,
                                            gpointer          user_data)      : Run first
"changed"   void        user_function      (GnomeScanContext *context,
                                            gchar            *property,
                                            gpointer          user_data)      : Run first
"data-received"
            void        user_function      (GnomeScanContext *context,
                                            gint              data_size,
                                            gpointer          user_data)      : Run first
"error"     void        user_function      (GnomeScanContext *context,
                                            gpointer          error,
                                            gpointer          user_data)      : Run first
"image-received"
            void        user_function      (GnomeScanContext *context,
                                            GnomeScanResult  *pixbuf,
                                            gpointer          user_data)      : Run first
"preview-received"
            void        user_function      (GnomeScanContext *context,
                                            GnomeScanResult  *pixbuf,
                                            gpointer          user_data)      : Run first
"preview-started"
            void        user_function      (GnomeScanContext  *context,
                                            GnomeScanForecast *forecast,
                                            gpointer           user_data)      : Run first
"preview-terminated"
            void        user_function      (GnomeScanContext *context,
                                            gpointer          user_data)      : Run first
"probe-done"
            void        user_function      (GnomeScanContext *context,
                                            gpointer          user_data)      : Run first
"scanner-selected"
            void        user_function      (GnomeScanContext *context,
                                            GnomeScanner     *scanner,
                                            gpointer          user_data)      : Run first

Description

The GnomeScanContext is the main object that applications will use. GnomeScanContext holds the list of scanners, scan options such as resolution, area, rotation, etc. Only one GnomeScanContext should be used in one application. The object must be shared between all object and widget of the application. Also, if the application do not show widgets for handling such or such option, the application must set those options to the desired value itself.

Details

GnomeScanContext

typedef struct _GnomeScanContext GnomeScanContext;


enum GnomeScanContextError

typedef enum {
  GNOME_SCAN_CONTEXT_ERROR_FAILED,
  GNOME_SCAN_CONTEXT_ERROR_NO_DEVICES
} GnomeScanContextError;


gnome_scan_context_new ()

GnomeScanContext* gnome_scan_context_new    (void);

Create a new GnomeScanContext

Returns : the new GnomeScanContext

gnome_scan_context_destroy ()

void        gnome_scan_context_destroy      (GnomeScanContext *context);

Unref a GnomeScanContext

context : a GnomeScanContext

gnome_scan_context_probe_scanners ()

void        gnome_scan_context_probe_scanners
                                            (GnomeScanContext *context);

Since probe can be very long, a newly created GnomeScanContext contains an empty list of scanners. The application must call gnome_scan_context_probe_scanners and wait for the signal GnomeScancontext::probe-done before query the scanners list. This allow the application to show a waiting dialog.

This function will be drop as soon as a dbus service will be implemented.

context : a GnomeScanContext

gnome_scan_context_get_scanners ()

GSList*     gnome_scan_context_get_scanners (GnomeScanContext *context);

Return the list of probed scanners. Don't forget to do a gnome_scan_context_probe_scanners() before calling gnome_scan_context_get_scanners().

context : a GnomeScanContext
Returns : a GSList of GnomeScanner.

gnome_scan_context_get_scanner ()

GnomeScanner* gnome_scan_context_get_scanner
                                            (GnomeScanContext *context);

Return the current selected scanner as a GnomeScanner.

context : a GnomeScanContext
Returns : the current selected scanner

gnome_scan_context_select_scanner ()

void        gnome_scan_context_select_scanner
                                            (GnomeScanContext *context,
                                             GnomeScanner *scanner);

Select a scanner for scan. Use a scanner pointed in the scanners list. Beware, no check the scanner were in the scanners list is done.

see_also: gnome_scan_context_get_scanners()

context : a GnomeScanContext
scanner : a GnomeScanner

gnome_scan_context_get_area ()

GnomeScanArea* gnome_scan_context_get_area  (GnomeScanContext *context);

Get the current area required. See gnome_scan_context_set_area() for further informations. The returned GnomeScanArea is a copy of the area and should be freed using g_free().

context : a GnomeScanContext
Returns : the current GnomeScanArea

gnome_scan_context_set_area ()

void        gnome_scan_context_set_area     (GnomeScanContext *context,
                                             GnomeScanArea *area);

Set the scan area of the picture. Using a scan area avoid people to use Gimp or such tools to crop picture and save some time during acquisition. This function is usually called by Preview widgets. Beware, the value aren't checked against the image geometrys.

context : a GnomeScanContext
area : a GnomeScanArea

gnome_scan_context_get_rotation ()

GdkPixbufRotation gnome_scan_context_get_rotation
                                            (GnomeScanContext *context);

Retreive the current final image rotation.

context : a GnomeScanContext
Returns : the image rotation

gnome_scan_context_set_rotation ()

void        gnome_scan_context_set_rotation (GnomeScanContext *context,
                                             GdkPixbufRotation rotation);

Set the final image rotation using a value in GdkPixbufRotation.

context : a GnomeScanContext
rotation : the rotation.

gnome_scan_context_get_source ()

GnomeScannerSource gnome_scan_context_get_source
                                            (GnomeScanContext *context);

Get the selected scanner source.

context : a GnomeScanContext
Returns : the source

gnome_scan_context_set_source ()

void        gnome_scan_context_set_source   (GnomeScanContext *context,
                                             GnomeScannerSource source);

Change current selected source.

context : a GonmeScanContext
source : the source to select

gnome_scan_context_forecast ()

GnomeScanForecast* gnome_scan_context_forecast
                                            (GnomeScanContext *context);

Forecast image size and geometry with current resolution and area.

context : a GnomeScanContext
Returns : a GnomeScanForecast

gnome_scan_context_acquire_preview ()

void        gnome_scan_context_acquire_preview
                                            (GnomeScanContext *context);

This function trigger a acquisition using full area and given resolution, without changing the selection area and resolution.

context : a GnomeScanContext

gnome_scan_context_start_acquisition ()

void        gnome_scan_context_start_acquisition
                                            (GnomeScanContext *context);

Acquire a picture. Cancel an acquisition is possible using gnome_scan_context_stop_acquisition(). The resulted pixbuf is sent using the GnomeScanContext::"image-received" signal.

context : a GnomeScanContext

Property Details

The "area" property

  "area"                 gpointer              : Read / Write

The final image area to be scanned.


The "backend" property

  "backend"              GnomeScanBackend      : Read / Write / Construct Only

a GnomeScanBackend.


The "rotation" property

  "rotation"             gint                  : Read / Write

The rotation in degree to be applied to the final image.

Allowed values: [0,90]

Default value: 0


The "scanner" property

  "scanner"              GnomeScanner          : Read / Write

The current selected scanner.


The "scanners" property

  "scanners"             gpointer              : Read

Contain scanners list.


The "x-resolution" property

  "x-resolution"         gint                  : Read / Write

The final image X resolution.

Allowed values: >= 0

Default value: 100


The "y-resolution" property

  "y-resolution"         gint                  : Read / Write

The final image y resolution.

Allowed values: >= 0

Default value: 100

Signal Details

The "acquisition-paused" signal

void        user_function                  (GnomeScanContext *context,
                                            gpointer          user_data)      : Run first

Emitted when the acquisition process has been paused.

context : The emitting GnomeScanContext
user_data : user data set when the signal handler was connected.

The "acquisition-resumed" signal

void        user_function                  (GnomeScanContext *context,
                                            gpointer          user_data)      : Run first

Emitted when the acquisition process has been paused.

context : The emitting GnomeScanContext
user_data : user data set when the signal handler was connected.

The "acquisition-started" signal

void        user_function                  (GnomeScanContext  *context,
                                            GnomeScanForecast *forecast,
                                            gpointer           user_data)      : Run first

Emitted when the acquisition is started. Use that signal to show a popup before actualy receiving data.

context : The emitting GnomeScanContext
forecast : The image size forecast.
user_data : user data set when the signal handler was connected.

The "acquisition-terminated" signal

void        user_function                  (GnomeScanContext *context,
                                            gpointer          user_data)      : Run first

Emitted when the backend has no more data to send. This signal is emitted even if the acquisition has been canceled.

context : The emitting GnomeScanContext
user_data : user data set when the signal handler was connected.

The "changed" signal

void        user_function                  (GnomeScanContext *context,
                                            gchar            *property,
                                            gpointer          user_data)      : Run first

Emitted when a scan option has been changed.

context : The emitting GnomeScanContext
property : The changed property name
user_data : user data set when the signal handler was connected.

The "data-received" signal

void        user_function                  (GnomeScanContext *context,
                                            gint              data_size,
                                            gpointer          user_data)      : Run first

Emitted when the backend send data. Either for a final picture acquisition or for a preview refresh.

context : The emitting GnomeScanContext
data_size : The current number of bytes received.
user_data : user data set when the signal handler was connected.

The "error" signal

void        user_function                  (GnomeScanContext *context,
                                            gpointer          error,
                                            gpointer          user_data)      : Run first

This signal allow the application to avert he user that a backend error occured.

context : The emitting GnomeScanContext
error : a GError containing the backend error.
user_data : user data set when the signal handler was connected.

The "image-received" signal

void        user_function                  (GnomeScanContext *context,
                                            GnomeScanResult  *pixbuf,
                                            gpointer          user_data)      : Run first

Emitted when a final image has been acquired. The pixbuf is then sent with that signal.

context : The emitting GnomeScanContext
pixbuf : The final image in a GdkPixbuf
user_data : user data set when the signal handler was connected.

The "preview-received" signal

void        user_function                  (GnomeScanContext *context,
                                            GnomeScanResult  *pixbuf,
                                            gpointer          user_data)      : Run first

Emitted when a preview image is received.

context : The emitting GnomeScanContext
pixbuf : The preview image in a GdkPixbuf
user_data : user data set when the signal handler was connected.

The "preview-started" signal

void        user_function                  (GnomeScanContext  *context,
                                            GnomeScanForecast *forecast,
                                            gpointer           user_data)      : Run first

Emitted when a preview acquisition is started.

context : The emitting GnomeScanContext
forecast : The image size forecast.
user_data : user data set when the signal handler was connected.

The "preview-terminated" signal

void        user_function                  (GnomeScanContext *context,
                                            gpointer          user_data)      : Run first

Emitted when a preview acquisition is terminated.

context : The emitting GnomeScanContext
user_data : user data set when the signal handler was connected.

The "probe-done" signal

void        user_function                  (GnomeScanContext *context,
                                            gpointer          user_data)      : Run first

Emitted when the backend terminate the scanner probe.

context : The emitting GnomeScanContext
user_data : user data set when the signal handler was connected.

The "scanner-selected" signal

void        user_function                  (GnomeScanContext *context,
                                            GnomeScanner     *scanner,
                                            gpointer          user_data)      : Run first

Emitted when the current a scanner is selected (wheter or not a previous scanner were selected).

context : The emitting GnomeScanContext
scanner : The newly selected scanner
user_data : user data set when the signal handler was connected.