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);
gdouble     gnome_scan_context_get_resolution
                                            (GnomeScanContext *context);
void        gnome_scan_context_set_resolution
                                            (GnomeScanContext *context,
                                             gdouble resolution);
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);
void        gnome_scan_context_cancel_acquisition
                                            (GnomeScanContext *context);

Object Hierarchy


  GObject
   +----GnomeScanContext

Properties


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

Signals


"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
"data-received"
            void        user_function      (GnomeScanContext *scancontext,
                                            gint              arg1,
                                            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,
                                            gpointer          pixbuf,
                                            gpointer          user_data)      : Run first
"preview-received"
            void        user_function      (GnomeScanContext *context,
                                            gpointer          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
} 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_resolution ()

gdouble     gnome_scan_context_get_resolution
                                            (GnomeScanContext *context);

Retreive the current resolution the image will be scan on.

context : a GnomeScanContext
Returns : The current resolution.

gnome_scan_context_set_resolution ()

void        gnome_scan_context_set_resolution
                                            (GnomeScanContext *context,
                                             gdouble resolution);

Set the resolution of the scan. Beware of fiting the range of allowed value.

context : a GnomeScanContext
resolution : the new resolution

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);

Retreive the current selected source.

context :
source :

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_cancel_acquisition(). The resulted pixbuf is sent using the GnomeScanContext::"image-received" signal. If the acquisition has been cancel or something else went wrong, only the GnomeScancontext::"acquisition-terminated" is sent.

context : a GnomeScanContext

gnome_scan_context_cancel_acquisition ()

void        gnome_scan_context_cancel_acquisition
                                            (GnomeScanContext *context);

Cancel either preview or final acquisition.

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 "resolution" property

  "resolution"           gint                  : Read / Write

The final image resolution.

Allowed values: >= 0

Default value: 100


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.

Signal Details

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 "data-received" signal

void        user_function                  (GnomeScanContext *scancontext,
                                            gint              arg1,
                                            gpointer          user_data)        : Run first

scancontext : the object which received the signal.
arg1 :
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,
                                            gpointer          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,
                                            gpointer          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.