summaryrefslogtreecommitdiff
path: root/src/plugins/DataImportsInterfaces.vala
diff options
context:
space:
mode:
authorJörg Frings-Fürst <debian@jff-webhosting.net>2014-07-23 09:06:59 +0200
committerJörg Frings-Fürst <debian@jff-webhosting.net>2014-07-23 09:06:59 +0200
commit4ea2cc3bd4a7d9b1c54a9d33e6a1cf82e7c8c21d (patch)
treed2e54377d14d604356c86862a326f64ae64dadd6 /src/plugins/DataImportsInterfaces.vala
Imported Upstream version 0.18.1upstream/0.18.1
Diffstat (limited to 'src/plugins/DataImportsInterfaces.vala')
-rw-r--r--src/plugins/DataImportsInterfaces.vala489
1 files changed, 489 insertions, 0 deletions
diff --git a/src/plugins/DataImportsInterfaces.vala b/src/plugins/DataImportsInterfaces.vala
new file mode 100644
index 0000000..154503b
--- /dev/null
+++ b/src/plugins/DataImportsInterfaces.vala
@@ -0,0 +1,489 @@
+/* Copyright 2011-2014 Yorba Foundation
+ *
+ * This software is licensed under the GNU Lesser General Public License
+ * (version 2.1 or later). See the COPYING file in this distribution.
+ */
+
+/**
+ * Shotwell Pluggable Data Imports API
+ *
+ * The Shotwell Pluggable Data Imports API allows you to write plugins that import
+ * information from other media library databases to help migration to Shotwell.
+ * The Shotwell distribution includes import support for F-Spot.
+ * To enable Shotwell to import from additional libaries, developers like you write
+ * data import plugins, dynamically-loadable shared objects that are linked into the
+ * Shotwell process at runtime. Data import plugins are just one of several kinds of
+ * plugins supported by {@link Spit}, the Shotwell Pluggable Interfaces Technology.
+ */
+namespace Spit.DataImports {
+
+/**
+ * The current version of the Pluggable Data Import API
+ */
+public const int CURRENT_INTERFACE = 0;
+
+/**
+ * The error domain for alien databases
+ */
+public errordomain DataImportError {
+ /**
+ * Indicates that the version of the external database being imported is
+ * not supported by this version of the plugin.
+ *
+ * This occurs for example when trying to import an F-Spot database that
+ * has a version that is more recent than what the current plugin supports.
+ */
+ UNSUPPORTED_VERSION
+}
+
+/**
+ * Represents a module that is able to import data from a specific database format.
+ *
+ * Developers of data import plugins provide a class that implements this interface. At
+ * any given time, only one DataImporter can be running. When a data importer is running, it
+ * has exclusive use of the shared user-interface and
+ * configuration services provided by the {@link PluginHost}. Data importers are created in
+ * a non-running state and do not begin running until start( ) is invoked. Data importers
+ * run until stop( ) is invoked.
+ */
+public interface DataImporter : GLib.Object {
+ /**
+ * Returns a {@link Service} object describing the service to which this connects.
+ */
+ public abstract Service get_service();
+
+ /**
+ * Makes this data importer enter the running state and endows it with exclusive access
+ * to the shared services provided by the {@link PluginHost}. Through the host’s interface,
+ * this data importer can install user interface panes and query configuration information.
+ */
+ public abstract void start();
+
+ /**
+ * Returns true if this data importer is in the running state; false otherwise.
+ */
+ public abstract bool is_running();
+
+ /**
+ * Causes this data importer to enter a non-running state. This data importer should stop all
+ * data access operations and cease use of the shared services provided by the {@link PluginHost}.
+ */
+ public abstract void stop();
+
+ /**
+ * Causes this data importer to enter start the import of a library.
+ */
+ public abstract void on_library_selected(ImportableLibrary library);
+
+ /**
+ * Causes this data importer to enter start the import of a library file.
+ */
+ public abstract void on_file_selected(File file);
+
+ //
+ // For future expansion.
+ //
+ protected virtual void reserved0() {}
+ protected virtual void reserved1() {}
+ protected virtual void reserved2() {}
+ protected virtual void reserved3() {}
+ protected virtual void reserved4() {}
+ protected virtual void reserved5() {}
+ protected virtual void reserved6() {}
+ protected virtual void reserved7() {}
+}
+
+/**
+ * Represents a library of importable media items.
+ *
+ * Developers of data import plugins provide a class that implements this interface.
+ */
+public interface ImportableLibrary : GLib.Object {
+ public abstract string get_display_name();
+}
+
+/**
+ * Represents an importable media item such as a photo or a video file.
+ *
+ * Developers of data import plugins provide a class that implements this interface.
+ */
+public interface ImportableMediaItem : GLib.Object {
+ public abstract ImportableTag[] get_tags();
+
+ public abstract ImportableEvent? get_event();
+
+ public abstract ImportableRating get_rating();
+
+ public abstract string? get_title();
+
+ public abstract string get_folder_path();
+
+ public abstract string get_filename();
+}
+
+/**
+ * Represents an importable tag.
+ *
+ * Developers of data import plugins provide a class that implements this interface.
+ */
+public interface ImportableTag : GLib.Object {
+ public abstract string get_name();
+
+ public abstract ImportableTag? get_parent();
+}
+
+/**
+ * Represents an importable event.
+ *
+ * Developers of data import plugins provide a class that implements this interface.
+ */
+public interface ImportableEvent : GLib.Object {
+ public abstract string get_name();
+}
+
+/**
+ * Represents an importable rating value.
+ *
+ * Developers of data import plugins provide a class that implements this interface.
+ * Note that the value returned by the get_value method should be a value between
+ * 1 and 5, unless the rating object is unrated or rejected, in which case the
+ * value is unspecified.
+ */
+public interface ImportableRating : GLib.Object {
+ public abstract bool is_unrated();
+
+ public abstract bool is_rejected();
+
+ public abstract int get_value();
+}
+
+/**
+ * Encapsulates a pane that can be installed in the on-screen import dialog box to
+ * communicate status to and to get information from the user.
+ *
+ */
+public interface DialogPane : GLib.Object {
+
+ /**
+ * Describes how the on-screen publishing dialog box should look and behave when an associated
+ * pane is installed in the on-screen publishing dialog box.
+ */
+ public enum GeometryOptions {
+
+ /**
+ * When the associated pane is installed, the on-screen publishing dialog box will be
+ * sized normally and will not allow the user to change its size.
+ */
+ NONE = 0,
+
+ /**
+ * If this bit is set, when the associated pane is installed, the on-screen publishing
+ * dialog box will grow to a larger size.
+ */
+ EXTENDED_SIZE = 1 << 0,
+
+ /**
+ * If this bit is set, when the associated pane is installed, the on-screen publishing
+ * dialog box will allow the user to change its size.
+ */
+ RESIZABLE = 1 << 1,
+
+ /**
+ * If this bit is set, when the associated pane is installed, the on-screen publishing
+ * dialog box will grow to accommodate a full-width 1024 pixel web page. If both
+ * EXTENDED_SIZE and COLOSSAL_SIZE are set, EXTENDED_SIZE takes precedence.
+ */
+ COLOSSAL_SIZE = 1 << 2;
+ }
+
+ /**
+ * Returns the Gtk.Widget that is this pane's on-screen representation.
+ */
+ public abstract Gtk.Widget get_widget();
+
+ /**
+ * Returns a {@link GeometryOptions} bitfield describing how the on-screen publishing dialog
+ * box should look and behave when this pane is installed.
+ */
+ public abstract GeometryOptions get_preferred_geometry();
+
+ /**
+ * Invoked automatically by Shotwell when this pane has been installed into the on-screen
+ * publishing dialog box and become visible to the user.
+ */
+ public abstract void on_pane_installed();
+
+ /**
+ * Invoked automatically by Shotwell when this pane has been removed from the on-screen
+ * publishing dialog box and is no longer visible to the user.
+ */
+ public abstract void on_pane_uninstalled();
+
+ //
+ // For future expansion.
+ //
+ protected virtual void reserved0() {}
+ protected virtual void reserved1() {}
+ protected virtual void reserved2() {}
+ protected virtual void reserved3() {}
+ protected virtual void reserved4() {}
+ protected virtual void reserved5() {}
+ protected virtual void reserved6() {}
+ protected virtual void reserved7() {}
+}
+
+/**
+ * Called by the data imports system at the end of an import batch to report
+ * to the plugin the number of items that were really imported. This enables
+ * the plugin to display a final message to the user. However, the plugin
+ * should not rely on this callback being called in order to clean up.
+ */
+public delegate void ImportedItemsCountCallback(int imported_items_count);
+
+/**
+ * Manages and provides services for data import plugins.
+ *
+ * Implemented inside Shotwell, the PluginHost provides an interface through which the
+ * developers of data import plugins can query and make changes to the import
+ * environment. Plugins can use the services of the PluginHost only when their
+ * {@link DataImporter} is in the running state. This ensures that non-running data importers
+ * don’t destructively interfere with the actively running importer.
+ */
+public interface PluginHost : GLib.Object, Spit.HostInterface {
+
+ /**
+ * Specifies the label text on the push button control that appears in the
+ * lower-right-hand corner of the on-screen publishing dialog box.
+ */
+ public enum ButtonMode {
+ CLOSE = 0,
+ CANCEL = 1
+ }
+
+ /**
+ * Notifies the user that an unrecoverable import error has occurred and halts
+ * the import process.
+ *
+ * @param err An error object that describes the kind of error that occurred.
+ */
+ public abstract void post_error(Error err);
+
+ /**
+ * Notifies the user that an unrecoverable import error has occurred and halts
+ * the import process.
+ *
+ * @param msg A message that describes the kind of error that occurred.
+ */
+ public abstract void post_error_message(string msg);
+
+ /**
+ * Starts the import process.
+ *
+ * Calling this method starts the import activity for this host.
+ */
+ public abstract void start_importing();
+
+ /**
+ * Halts the import process.
+ *
+ * Calling this method stops all import activity and hides the on-screen import
+ * dialog box.
+ */
+ public abstract void stop_importing();
+
+ /**
+ * Returns a reference to the {@link DataImporter} object that this is currently hosting.
+ */
+ public abstract DataImporter get_data_importer();
+
+ /**
+ * Attempts to install a pane in the on-screen data import dialog box, making the pane visible
+ * and allowing it to interact with the user.
+ *
+ * If an error has posted, the {@link PluginHost} will not honor this request.
+ *
+ * @param pane the pane to install
+ *
+ * @param mode allows you to set the text displayed on the close/cancel button in the
+ * lower-right-hand corner of the on-screen data import dialog box when pane is installed.
+ * If mode is ButtonMode.CLOSE, the button will have the title "Close." If mode is
+ * ButtonMode.CANCEL, the button will be titled "Cancel." You should set mode depending on
+ * whether a cancellable action is in progress. For example, if your importer is in the
+ * middle of processing 3 of 8 videos, then mode should be ButtonMode.CANCEL. However, if
+ * the processing operation has completed and the success pane is displayed, then mode
+ * should be ButtonMode.CLOSE, because all cancellable actions have already
+ * occurred.
+ */
+ public abstract void install_dialog_pane(Spit.DataImports.DialogPane pane,
+ ButtonMode mode = ButtonMode.CANCEL);
+
+ /**
+ * Attempts to install a pane in the on-screen data import dialog box that contains
+ * static text.
+ *
+ * The text appears centered in the data import dialog box and is drawn in
+ * the system font. This is a convenience method only; similar results could be
+ * achieved by manually constructing a Gtk.Label widget, wrapping it inside a
+ * {@link DialogPane}, and installing it manually with a call to
+ * install_dialog_pane( ). To provide visual consistency across data import services,
+ * however, always use this convenience method instead of constructing label panes when
+ * you need to display static text to the user.
+ *
+ * If an error has posted, the {@link PluginHost} will not honor this request.
+ *
+ * @param message the text to show in the pane
+ *
+ * @param mode allows you to set the text displayed on the close/cancel button in the
+ * lower-right-hand corner of the on-screen data import dialog box when pane is installed.
+ * If mode is ButtonMode.CLOSE, the button will have the title "Close." If mode is
+ * ButtonMode.CANCEL, the button will be titled "Cancel." You should set mode depending on
+ * whether a cancellable action is in progress. For example, if your importer is in the
+ * middle of processing 3 of 8 videos, then mode should be ButtonMode.CANCEL. However, if
+ * the processing operation has completed and the success pane is displayed, then mode
+ * should be ButtonMode.CLOSE, because all cancellable actions have already
+ * occurred.
+ */
+ public abstract void install_static_message_pane(string message,
+ ButtonMode mode = ButtonMode.CANCEL);
+
+ /**
+ * Attempts to install a library selection pane that presents a list of
+ * discovered libraries to the user.
+ *
+ * When the user clicks the “OK” button, you’ll be notified of the user’s action through
+ * the 'on_library_selected' callback if a discovered library was selected or through
+ * the 'on_file_selected' callback if a file was selected.
+ *
+ * If an error has posted, the {@link PluginHost} will not honor this request.
+ *
+ * @param welcome_message the text to be displayed above the list of discovered
+ * libraries.
+ *
+ * @param discovered_libraries the list of importable libraries that the plugin
+ * has discovered in well known locations.
+ *
+ * @param file_select_label the label to display for the file selection
+ * option. If this label is null, the
+ * user will not be presented with a file selection option.
+ */
+ public abstract void install_library_selection_pane(
+ string welcome_message,
+ ImportableLibrary[] discovered_libraries,
+ string? file_select_label
+ );
+
+ /**
+ * Attempts to install a progress pane that provides the user with feedback
+ * on import preparation.
+ *
+ * If an error has posted, the {@link PluginHost} will not honor this request.
+ *
+ * @param message the text to be displayed above the progress bar.
+ */
+ public abstract void install_import_progress_pane(
+ string message
+ );
+
+ /**
+ * Update the progress bar installed by install_import_progress_pane.
+ *
+ * If an error has posted, the {@link PluginHost} will not honor this request.
+ *
+ * @param progress a value between 0.0 and 1.0 identifying progress for the
+ * plugin.
+ *
+ * @param progress_label the text to be displayed below the progress bar. If that
+ * parameter is null, the message will be left unchanged.
+ */
+ public abstract void update_import_progress_pane(
+ double progress,
+ string? progress_message = null
+ );
+
+ /**
+ * Sends an importable media item to the host in order to prepare it for import
+ * and update the progress bar installed by install_import_progress_pane.
+ *
+ * If an error has posted, the {@link PluginHost} will not honor this request.
+ *
+ * @param item the importable media item to prepare for import.
+ *
+ * @param progress a value between 0.0 and 1.0 identifying progress for the
+ * plugin.
+ *
+ * @param host_progress_delta the amount of progress the host should update
+ * the progress bar during import preparation. Plugins should ensure that
+ * a proportion of progress for each media item is set aside for the host
+ * in oder to ensure a smoother update to the progress bar.
+ *
+ * @param progress_message the text to be displayed below the progress bar. If that
+ * parameter is null, the message will be left unchanged.
+ */
+ public abstract void prepare_media_items_for_import(
+ ImportableMediaItem[] items,
+ double progress,
+ double host_progress_delta = 0.0,
+ string? progress_message = null
+ );
+
+ /**
+ * Finalize the import sequence for the plugin. This tells the host that
+ * all media items have been processed and that the plugin has finished all
+ * import work. Once this method has been called, all resources used by the
+ * plugin for import should be released and the plugin should be back to the
+ * state it had just after running the start method. The host will then display
+ * the final message and show progress as fully complete. In a standard import
+ * scenario, the user is expected to click the Close button to dismiss the
+ * dialog. On first run, the host may call the LibrarySelectedCallback again
+ * to import another library handled by the same plugin.
+ *
+ * If an error has posted, the {@link PluginHost} will not honor this request.
+ *
+ * @param finalize_message the text to be displayed below the progress bar. If that
+ * parameter is null, the message will be left unchanged.
+ */
+ public abstract void finalize_import(
+ ImportedItemsCountCallback report_imported_items_count,
+ string? finalize_message = null
+ );
+
+ //
+ // For future expansion.
+ //
+ protected virtual void reserved0() {}
+ protected virtual void reserved1() {}
+ protected virtual void reserved2() {}
+ protected virtual void reserved3() {}
+ protected virtual void reserved4() {}
+ protected virtual void reserved5() {}
+ protected virtual void reserved6() {}
+ protected virtual void reserved7() {}
+}
+
+/**
+ * Describes the features and capabilities of a data import service.
+ *
+ * Developers of data import plugins provide a class that implements this interface.
+ */
+public interface Service : Object, Spit.Pluggable {
+ /**
+ * A factory method that instantiates and returns a new {@link DataImporter} object
+ * that this Service describes.
+ */
+ public abstract Spit.DataImports.DataImporter create_data_importer(Spit.DataImports.PluginHost host);
+
+ //
+ // For future expansion.
+ //
+ protected virtual void reserved0() {}
+ protected virtual void reserved1() {}
+ protected virtual void reserved2() {}
+ protected virtual void reserved3() {}
+ protected virtual void reserved4() {}
+ protected virtual void reserved5() {}
+ protected virtual void reserved6() {}
+ protected virtual void reserved7() {}
+}
+
+}
+