1
/* Copyright 2011 Yorba Foundation
3
* This software is licensed under the GNU Lesser General Public License
4
* (version 2.1 or later). See the COPYING file in this distribution.
8
* Shotwell Pluggable Data Imports API
10
* The Shotwell Pluggable Data Imports API allows you to write plugins that import
11
* information from other media library databases to help migration to Shotwell.
12
* The Shotwell distribution includes import support for F-Spot.
13
* To enable Shotwell to import from additional libaries, developers like you write
14
* data import plugins, dynamically-loadable shared objects that are linked into the
15
* Shotwell process at runtime. Data import plugins are just one of several kinds of
16
* plugins supported by {@link Spit}, the Shotwell Pluggable Interfaces Technology.
18
namespace Spit.DataImports {
21
* The current version of the Pluggable Data Import API
23
public const int CURRENT_INTERFACE = 0;
26
* The error domain for alien databases
28
public errordomain DataImportError {
30
* Indicates that the version of the external database being imported is
31
* not supported by this version of the plugin.
33
* This occurs for example when trying to import an F-Spot database that
34
* has a version that is more recent than what the current plugin supports.
40
* Represents a module that is able to import data from a specific database format.
42
* Developers of data import plugins provide a class that implements this interface. At
43
* any given time, only one DataImporter can be running. When a data importer is running, it
44
* has exclusive use of the shared user-interface and
45
* configuration services provided by the {@link PluginHost}. Data importers are created in
46
* a non-running state and do not begin running until start( ) is invoked. Data importers
47
* run until stop( ) is invoked.
49
public interface DataImporter : GLib.Object {
51
* Returns a {@link Service} object describing the service to which this connects.
53
public abstract Service get_service();
56
* Makes this data importer enter the running state and endows it with exclusive access
57
* to the shared services provided by the {@link PluginHost}. Through the host’s interface,
58
* this data importer can install user interface panes and query configuration information.
60
public abstract void start();
63
* Returns true if this data importer is in the running state; false otherwise.
65
public abstract bool is_running();
68
* Causes this data importer to enter a non-running state. This data importer should stop all
69
* data access operations and cease use of the shared services provided by the {@link PluginHost}.
71
public abstract void stop();
74
* Causes this data importer to enter start the import of a library.
76
public abstract void on_library_selected(ImportableLibrary library);
79
* Causes this data importer to enter start the import of a library file.
81
public abstract void on_file_selected(File file);
84
// For future expansion.
86
protected virtual void reserved0() {}
87
protected virtual void reserved1() {}
88
protected virtual void reserved2() {}
89
protected virtual void reserved3() {}
90
protected virtual void reserved4() {}
91
protected virtual void reserved5() {}
92
protected virtual void reserved6() {}
93
protected virtual void reserved7() {}
97
* Represents a libary of importable media items.
99
* Developers of data import plugins provide a class that implements this interface.
101
public interface ImportableLibrary : GLib.Object {
102
public abstract string get_display_name();
106
* Represents an importable media item such as a photo or a video file.
108
* Developers of data import plugins provide a class that implements this interface.
110
public interface ImportableMediaItem : GLib.Object {
111
public abstract ImportableTag[] get_tags();
113
public abstract ImportableEvent? get_event();
115
public abstract ImportableRating get_rating();
117
public abstract string? get_title();
119
public abstract string get_folder_path();
121
public abstract string get_filename();
125
* Represents an importable tag.
127
* Developers of data import plugins provide a class that implements this interface.
129
public interface ImportableTag : GLib.Object {
130
public abstract string get_name();
132
public abstract ImportableTag? get_parent();
136
* Represents an importable event.
138
* Developers of data import plugins provide a class that implements this interface.
140
public interface ImportableEvent : GLib.Object {
141
public abstract string get_name();
145
* Represents an importable rating value.
147
* Developers of data import plugins provide a class that implements this interface.
148
* Note that the value returned by the get_value method should be a value between
149
* 1 and 5, unless the rating object is unrated or rejected, in which case the
150
* value is unspecified.
152
public interface ImportableRating : GLib.Object {
153
public abstract bool is_unrated();
155
public abstract bool is_rejected();
157
public abstract int get_value();
161
* Encapsulates a pane that can be installed in the on-screen import dialog box to
162
* communicate status to and to get information from the user.
165
public interface DialogPane : GLib.Object {
168
* Describes how the on-screen publishing dialog box should look and behave when an associated
169
* pane is installed in the on-screen publishing dialog box.
171
public enum GeometryOptions {
174
* When the associated pane is installed, the on-screen publishing dialog box will be
175
* sized normally and will not allow the user to change its size.
180
* If this bit is set, when the associated pane is installed, the on-screen publishing
181
* dialog box will grow to a larger size.
183
EXTENDED_SIZE = 1 << 0,
186
* If this bit is set, when the associated pane is installed, the on-screen publishing
187
* dialog box will allow the user to change its size.
192
* If this bit is set, when the associated pane is installed, the on-screen publishing
193
* dialog box will grow to accomodate a full-width 1024 pixel web page. If both
194
* EXTENDED_SIZE and COLOSSAL_SIZE are set, EXTENDED_SIZE takes precedence.
196
COLOSSAL_SIZE = 1 << 2;
200
* Returns the Gtk.Widget that is this pane's on-screen representation.
202
public abstract Gtk.Widget get_widget();
205
* Returns a {@link GeometryOptions} bitfield describing how the on-screen publishing dialog
206
* box should look and behave when this pane is installed.
208
public abstract GeometryOptions get_preferred_geometry();
211
* Invoked automatically by Shotwell when this pane has been installed into the on-screen
212
* publishing dialog box and become visible to the user.
214
public abstract void on_pane_installed();
217
* Invoked automatically by Shotwell when this pane has been removed from the on-screen
218
* publishing dialog box and is no longer visible to the user.
220
public abstract void on_pane_uninstalled();
223
// For future expansion.
225
protected virtual void reserved0() {}
226
protected virtual void reserved1() {}
227
protected virtual void reserved2() {}
228
protected virtual void reserved3() {}
229
protected virtual void reserved4() {}
230
protected virtual void reserved5() {}
231
protected virtual void reserved6() {}
232
protected virtual void reserved7() {}
236
* Called by the data imports system at the end of an import batch to report
237
* to the plugin the number of items that were really imported. This enables
238
* the plugin to display a final message to the user. However, the plugin
239
* should not rely on this callback being called in order to clean up.
241
public delegate void ImportedItemsCountCallback(int imported_items_count);
244
* Manages and provides services for data import plugins.
246
* Implemented inside Shotwell, the PluginHost provides an interface through which the
247
* developers of data import plugins can query and make changes to the import
248
* environment. Plugins can use the services of the PluginHost only when their
249
* {@link DataImporter} is in the running state. This ensures that non-running data importers
250
* don’t destructively interfere with the actively running importer.
252
public interface PluginHost : GLib.Object, Spit.HostInterface {
255
* Specifies the label text on the push button control that appears in the
256
* lower-right-hand corner of the on-screen publishing dialog box.
258
public enum ButtonMode {
264
* Notifies the user that an unrecoverable import error has occurred and halts
265
* the import process.
267
* @param err An error object that describes the kind of error that occurred.
269
public abstract void post_error(Error err);
272
* Notifies the user that an unrecoverable import error has occurred and halts
273
* the import process.
275
* @param msg A message that describes the kind of error that occurred.
277
public abstract void post_error_message(string msg);
280
* Starts the import process.
282
* Calling this method starts the import activity for this host.
284
public abstract void start_importing();
287
* Halts the import process.
289
* Calling this method stops all import activity and hides the on-screen import
292
public abstract void stop_importing();
295
* Returns a reference to the {@link DataImporter} object that this is currently hosting.
297
public abstract DataImporter get_data_importer();
300
* Attempts to install a pane in the on-screen data import dialog box, making the pane visible
301
* and allowing it to interact with the user.
303
* If an error has posted, the {@link PluginHost} will not honor this request.
305
* @param pane the pane to install
307
* @param mode allows you to set the text displayed on the close/cancel button in the
308
* lower-right-hand corner of the on-screen data import dialog box when pane is installed.
309
* If mode is ButtonMode.CLOSE, the button will have the title "Close." If mode is
310
* ButtonMode.CANCEL, the button will be titled "Cancel." You should set mode depending on
311
* whether a cancellable action is in progress. For example, if your importer is in the
312
* middle of processing 3 of 8 videos, then mode should be ButtonMode.CANCEL. However, if
313
* the processing operation has completed and the success pane is displayed, then mode
314
* should be ButtonMode.CLOSE, because all cancellable actions have already
317
public abstract void install_dialog_pane(Spit.DataImports.DialogPane pane,
318
ButtonMode mode = ButtonMode.CANCEL);
321
* Attempts to install a pane in the on-screen data import dialog box that contains
324
* The text appears centered in the data import dialog box and is drawn in
325
* the system font. This is a convenience method only; similar results could be
326
* achieved by manually constructing a Gtk.Label widget, wrapping it inside a
327
* {@link DialogPane}, and installing it manually with a call to
328
* install_dialog_pane( ). To provide visual consistency across data import services,
329
* however, always use this convenience method instead of constructing label panes when
330
* you need to display static text to the user.
332
* If an error has posted, the {@link PluginHost} will not honor this request.
334
* @param message the text to show in the pane
336
* @param mode allows you to set the text displayed on the close/cancel button in the
337
* lower-right-hand corner of the on-screen data import dialog box when pane is installed.
338
* If mode is ButtonMode.CLOSE, the button will have the title "Close." If mode is
339
* ButtonMode.CANCEL, the button will be titled "Cancel." You should set mode depending on
340
* whether a cancellable action is in progress. For example, if your importer is in the
341
* middle of processing 3 of 8 videos, then mode should be ButtonMode.CANCEL. However, if
342
* the processing operation has completed and the success pane is displayed, then mode
343
* should be ButtonMode.CLOSE, because all cancellable actions have already
346
public abstract void install_static_message_pane(string message,
347
ButtonMode mode = ButtonMode.CANCEL);
350
* Attempts to install a library selection pane that presents a list of
351
* discovered libraries to the user.
353
* When the user clicks the “OK” button, you’ll be notified of the user’s action through
354
* the 'on_library_selected' callback if a discovered library was selected or through
355
* the 'on_file_selected' callback if a file was selected.
357
* If an error has posted, the {@link PluginHost} will not honor this request.
359
* @param welcome_message the text to be displayed above the list of discovered
362
* @param discovered_libraries the list of importable libraries that the plugin
363
* has discovered in well known locations.
365
* @param file_select_label the label to display for the file selection
366
* option. If this label is null, the
367
* user will not be presented with a file selection option.
369
public abstract void install_library_selection_pane(
370
string welcome_message,
371
ImportableLibrary[] discovered_libraries,
372
string? file_select_label
376
* Attempts to install a progress pane that provides the user with feedback
377
* on import preparation.
379
* If an error has posted, the {@link PluginHost} will not honor this request.
381
* @param message the text to be displayed above the progress bar.
383
public abstract void install_import_progress_pane(
388
* Update the progress bar installed by install_import_progress_pane.
390
* If an error has posted, the {@link PluginHost} will not honor this request.
392
* @param progress a value between 0.0 and 1.0 identifying progress for the
395
* @param progress_label the text to be displayed below the progress bar. If that
396
* parameter is null, the message will be left unchanged.
398
public abstract void update_import_progress_pane(
400
string? progress_message = null
404
* Sends an importable media item to the host in order to prepare it for import
405
* and update the progress bar installed by install_import_progress_pane.
407
* If an error has posted, the {@link PluginHost} will not honor this request.
409
* @param item the importable media item to prepare for import.
411
* @param progress a value between 0.0 and 1.0 identifying progress for the
414
* @param host_progress_delta the amount of progress the host should update
415
* the progress bar during import preparation. Plugins should ensure that
416
* a proportion of progress for each media item is set aside for the host
417
* in oder to ensure a smoother update to the progress bar.
419
* @param progress_message the text to be displayed below the progress bar. If that
420
* parameter is null, the message will be left unchanged.
422
public abstract void prepare_media_items_for_import(
423
ImportableMediaItem[] items,
425
double host_progress_delta = 0.0,
426
string? progress_message = null
430
* Finalize the import sequence for the plugin. This tells the host that
431
* all media items have been processed and that the plugin has finished all
432
* import work. Once this method has been called, all resources used by the
433
* plugin for import should be released and the plugin should be back to the
434
* state it had just after running the start method. The host will then display
435
* the final message and show progress as fully complete. In a standard import
436
* scenario, the user is expected to click the Close button to dismiss the
437
* dialog. On first run, the host may call the LibrarySelectedCallback again
438
* to import another library handled by the same plugin.
440
* If an error has posted, the {@link PluginHost} will not honor this request.
442
* @param finalize_message the text to be displayed below the progress bar. If that
443
* parameter is null, the message will be left unchanged.
445
public abstract void finalize_import(
446
ImportedItemsCountCallback report_imported_items_count,
447
string? finalize_message = null
451
// For future expansion.
453
protected virtual void reserved0() {}
454
protected virtual void reserved1() {}
455
protected virtual void reserved2() {}
456
protected virtual void reserved3() {}
457
protected virtual void reserved4() {}
458
protected virtual void reserved5() {}
459
protected virtual void reserved6() {}
460
protected virtual void reserved7() {}
464
* Describes the features and capabilities of a data import service.
466
* Developers of data import plugins provide a class that implements this interface.
468
public interface Service : Object, Spit.Pluggable {
470
* A factory method that instantiates and returns a new {@link DataImporter} object
471
* that this Service describes.
473
public abstract Spit.DataImports.DataImporter create_data_importer(Spit.DataImports.PluginHost host);
476
// For future expansion.
478
protected virtual void reserved0() {}
479
protected virtual void reserved1() {}
480
protected virtual void reserved2() {}
481
protected virtual void reserved3() {}
482
protected virtual void reserved4() {}
483
protected virtual void reserved5() {}
484
protected virtual void reserved6() {}
485
protected virtual void reserved7() {}
added
removed
src/plugins/DataImportsInterfaces.vala
