Commit a5d2ee01 authored by Jim Nelson's avatar Jim Nelson

Valadoc-ed the SPIT and transitions interfaces and added a docs target in the...

Valadoc-ed the SPIT and transitions interfaces and added a docs target in the Makefile to generate Valadoc for Shotwell's plugin API.
parent 946fe7ef
......@@ -598,6 +598,17 @@ $(PLUGINS_DIR): $(PLUGIN_VAPI) $(PLUGIN_HEADER) $(PLUGIN_DEPS)
$(call check_valac_version)
@$(MAKE) --directory=$@ PLUGINS_VERSION="$(VERSION)"
.PHONY: docs
docs:
# valadoc complains if the directory already exists
@rm -rf docs
valadoc --directory=docs --package-name=shotwell-plugin-dev --package-version=$(VERSION) --verbose \
--no-protected \
$(foreach def,$(DEFINES),--define=$(def)) \
$(foreach pkg,$(VALA_PKGS),--pkg=$(pkg)) \
$(foreach vapidir,$(VAPI_DIRS),--vapidir=$(vapidir)) \
$(PLUGIN_INTERFACES)
glade: lib$(PROGRAM).so
lib$(PROGRAM).so: $(EXPANDED_OBJ_FILES) $(RESOURCES) $(LANG_STAMP)
......
......@@ -7,7 +7,7 @@
public class FacebookService : Object, Spit.Pluggable, Spit.Publishing.Service {
public int get_pluggable_interface(int min_host_interface, int max_host_interface) {
return Spit.negotiate_interfaces(min_host_interface, max_host_interface,
Spit.Publishing.CURRENT_API_VERSION);
Spit.Publishing.CURRENT_INTERFACE);
}
public unowned string get_id() {
......
......@@ -7,7 +7,7 @@
public class FlickrService : Object, Spit.Pluggable, Spit.Publishing.Service {
public int get_pluggable_interface(int min_host_interface, int max_host_interface) {
return Spit.negotiate_interfaces(min_host_interface, max_host_interface,
Spit.Publishing.CURRENT_API_VERSION);
Spit.Publishing.CURRENT_INTERFACE);
}
public unowned string get_id() {
......
......@@ -7,7 +7,7 @@
public class PicasaService : Object, Spit.Pluggable, Spit.Publishing.Service {
public int get_pluggable_interface(int min_host_interface, int max_host_interface) {
return Spit.negotiate_interfaces(min_host_interface, max_host_interface,
Spit.Publishing.CURRENT_API_VERSION);
Spit.Publishing.CURRENT_INTERFACE);
}
public unowned string get_id() {
......
......@@ -75,13 +75,28 @@ public abstract class ShotwellTransitionDescriptor : Object, Spit.Pluggable, Spi
public void get_info(out Spit.PluggableInfo info) {
info.authors = "Maxim Kartashev, Jim Nelson";
info.copyright = _("Copyright 2010 Maxim Kartashev, Copyright 2011 Yorba Foundation");
// TODO: Include license here
info.license = null;
info.is_licensed_wordwrapped = false;
info.translators = _("translator-credits");
info.version = _VERSION;
info.website_name = _("Visit the Yorba web site");
info.website_url = "http://www.yorba.org";
info.is_license_wordwrapped = true;
info.license = """
Shotwell is free software; you can redistribute it and/or modify it under the
terms of the GNU Lesser General Public License as published by the Free
Software Foundation; either version 2.1 of the License, or (at your option)
any later version.
Shotwell is distributed in the hope that it will be useful, but WITHOUT
ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for
more details.
You should have received a copy of the GNU Lesser General Public License
along with Shotwell; if not, write to the Free Software Foundation, Inc.,
51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
""";
}
public void activation(bool enabled) {
......
......@@ -82,7 +82,7 @@ public class ManifestWidgetMediator {
about_dialog.comments = info.brief_description;
about_dialog.copyright = info.copyright;
about_dialog.license = info.license;
about_dialog.wrap_license = info.is_licensed_wordwrapped;
about_dialog.wrap_license = info.is_license_wordwrapped;
about_dialog.logo = info.icon;
about_dialog.program_name = get_pluggable_name(id);
about_dialog.translator_credits = info.translators;
......
......@@ -6,7 +6,7 @@
namespace Spit.Publishing {
public const int CURRENT_API_VERSION = 0;
public const int CURRENT_INTERFACE = 0;
public errordomain PublishingError {
NO_ANSWER,
......@@ -37,14 +37,14 @@ public interface Publisher : GLib.Object {
//
// For future expansion.
//
public virtual void reserved0() {}
public virtual void reserved1() {}
public virtual void reserved2() {}
public virtual void reserved3() {}
public virtual void reserved4() {}
public virtual void reserved5() {}
public virtual void reserved6() {}
public virtual void reserved7() {}
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() {}
}
public interface DialogPane : GLib.Object {
......@@ -56,7 +56,7 @@ public interface DialogPane : GLib.Object {
public abstract Gtk.Widget get_widget();
/* the publishing dialog may give you what you want; then again, it may not ;-) */
/* the publishing dialog may give you what you want; then again, it may not ;-) */
public abstract GeometryOptions get_preferred_geometry();
public abstract void on_pane_installed();
......@@ -66,14 +66,14 @@ public interface DialogPane : GLib.Object {
//
// For future expansion.
//
public virtual void reserved0() {}
public virtual void reserved1() {}
public virtual void reserved2() {}
public virtual void reserved3() {}
public virtual void reserved4() {}
public virtual void reserved5() {}
public virtual void reserved6() {}
public virtual void reserved7() {}
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() {}
}
/* fraction_complete should be between 0.0 and 1.0 inclusive */
......@@ -125,14 +125,14 @@ public interface PluginHost : GLib.Object, Spit.HostInterface {
//
// For future expansion.
//
public virtual void reserved0() {}
public virtual void reserved1() {}
public virtual void reserved2() {}
public virtual void reserved3() {}
public virtual void reserved4() {}
public virtual void reserved5() {}
public virtual void reserved6() {}
public virtual void reserved7() {}
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() {}
}
public interface Publishable : GLib.Object {
......@@ -149,14 +149,14 @@ public interface Publishable : GLib.Object {
//
// For future expansion.
//
public virtual void reserved0() {}
public virtual void reserved1() {}
public virtual void reserved2() {}
public virtual void reserved3() {}
public virtual void reserved4() {}
public virtual void reserved5() {}
public virtual void reserved6() {}
public virtual void reserved7() {}
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() {}
}
public interface Service : Object, Spit.Pluggable {
......@@ -166,14 +166,14 @@ public interface Service : Object, Spit.Pluggable {
//
// For future expansion.
//
public virtual void reserved0() {}
public virtual void reserved1() {}
public virtual void reserved2() {}
public virtual void reserved3() {}
public virtual void reserved4() {}
public virtual void reserved5() {}
public virtual void reserved6() {}
public virtual void reserved7() {}
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() {}
}
}
......
......@@ -4,193 +4,334 @@
* (version 2.1 or later). See the COPYING file in this distribution.
*/
// This is the front-end interface for all modules (i.e. .so/.la files) that allows for Shotwell
// to query them for information and to get a list of all plug-ins stored in the module. This
// is named Shotwell Pluggable Interface Technology (SPIT). This is intended only to last long
// enough for another generic plug-in library (most like Peas) to be used later.
// The Spit namespace is used for all interfaces and code that are made available to plugins or
// are exposed by plugins.
/**
* Shotwell Pluggable Interface Technology (SPIT)
*
* This is the front-end interface for all modules (i.e. .so/.la files) that allows for Shotwell
* to query them for information and to get a list of all plug-ins stored in the module. This
* is named Shotwell Pluggable Interface Technology (SPIT). This is intended only to last long
* enough for another generic plug-in library (most likely Peas) to be used later.
*
* The Spit namespace is used for all interfaces and code that are made available to plugins or
* are exposed by plugins.
*
* More information can be found at [[http://trac.yorba.org/wiki/ShotwellArchWritingPlugins]]
*/
namespace Spit {
/**
* Reserved interface value denoting an unsupported interface version.
*
* All interface versions should be zero-based and incrementing.
*/
public const int UNSUPPORTED_INTERFACE = -1;
/**
* Current version of the SPIT interface.
*/
public const int CURRENT_INTERFACE = 0;
// A utility function for checking host interfaces against one's own and returning the right value.
// Note that this only works if the caller operates on only one interface version (and cannot mutate
// between multiple ones).
/**
* A utility function for checking host interfaces against one's own and returning the right value.
*
* Note that this only works if the caller operates on only one interface version (and cannot mutate
* between multiple ones).
*
* @param min_host_interface The minimum supported host interface version.
* @param max_host_interface The maximum supported host interface version.
* @param plugin_interface The interface version supported by the Pluggable.
*
* @return The plugin's interface version if supported, {@link UNSUPPORTED_INTERFACE} otherwise.
*/
public int negotiate_interfaces(int min_host_interface, int max_host_interface, int plugin_interface) {
return (min_host_interface > plugin_interface || max_host_interface < plugin_interface)
? UNSUPPORTED_INTERFACE : plugin_interface;
}
//
// SPIT API entry point. Host application passes in the minimum and maximum version of the SPIT
// inteface it supports (values are inclusive). The module returns the version it wishes to
// use and a pointer to a Spit.Module (which will remain ref'ed as long as the module is loaded in
// memory). The module should return UNSUPPORTED_SPIT_VERSION is the min/max are out of its
// range and null for its Spit.Module.
//
/**
* SPIT API entry point.
*
* Host application passes in the minimum and maximum version of the SPIT
* inteface it supports (values are inclusive). The module returns the version it wishes to
* use and a pointer to a {@link Spit.Module} (which will remain ref'ed as long as the module is
* loaded in memory). The module should return {@link UNSUPPORTED_INTERFACE} is the min/max
* are out of its range and null for its Spit.Module. ({@link negotiate_interfaces} is good for
* dealing with this.)
*
* @param host_min_spit_interface The host's minimum supported interface version.
* @param host_max_spit_interface The host's maximum supported interface version.
* @param module_spit_interface The interface version of SPIT the module supports,
* {@link UNSUPPORTED_INTERFACE} otherwise.
*
* @return A {@link Spit.Module} if the interface negotiation is acceptable, null otherwise.
*/
[CCode (has_target = false)]
public delegate unowned Module? EntryPoint(int host_min_spit_interface, int host_max_spit_interface,
out int module_spit_interface);
//
// SPIT entry point name, which matches SpitEntryPoint's interface
//
/**
* SPIT entry point name, which matches {@link EntryPoint}'s interface
*/
public const string ENTRY_POINT_NAME = "spit_entry_point";
//
// A Module represents an entire module (i.e. a .so/.la) which contains zero or more Shotwell
// plug-ins. Once the module has been loaded into process space and this object has been
// loaded and held by Shotwell, all calls to the module and plug-ins are resolved through this
// interface.
//
/**
* A Module represents the resources of an entire dynamically-linked module (i.e. a .so/.la).
*
* A module holds zero or more Shotwell plugins ({@link Pluggable}). Once the module has been
* loaded into process space this object is retrieved by Shotwell. All calls to the module and
* its plugins are resolved through this interface.
*
* Note: The module is responsible for holding the reference to the Module object, of which there
* should be only one in the library file. The module should implement a g_module_unload method
* and drop the reference there.
*/
public interface Module : Object {
//
// Returns a (potentially) user-visible string describing the module (i.e. the .so/.la file).
//
/**
* Returns a user-visible string describing the module.
*/
public abstract unowned string get_module_name();
//
// Returns a (potentially) user-visible string describing the module version. Note that this
// may be programmatically interpreted at some point, so use a widespread versioning scheme.
//
/**
* Returns a user-visible string describing the module version.
*
* Note that this may be programmatically interpreted at some point, so use a widespread
* versioning scheme.
*/
public abstract unowned string get_version();
//
// Returns a unique identifier for this module. This is used to differentiate between multiple
// installed versions and to determine which one should be used (i.e. if a module is available
// in a system directory and a user directory). This name is case-sensitive.
//
// Best practice: use a reverse-DNS-order scheme, a la Java's packages
// (i.e. "org.yorba.shotwell.frotz").
//
/**
* Returns a unique identifier for this module.
*
* This is used to differentiate between multiple
* installed versions and to determine which one should be used (i.e. if a module is available
* in a system directory and a user directory). This name is case-sensitive.
*
* Best practice: use a reverse-DNS-order scheme, a la Java's packages
* (i.e. "org.yorba.shotwell.frotz").
*/
public abstract unowned string get_id();
//
// Returns an array of Pluggables that represent each plug-in available in the module.
// May return NULL or an empty array.
//
/**
* Returns an array of {@link Pluggable} that represent each plugin available in the module.
*
* May return NULL or an empty array.
*/
public abstract unowned Pluggable[]? get_pluggables();
//
// For future expansion.
//
public virtual void reserved0() {}
public virtual void reserved1() {}
public virtual void reserved2() {}
public virtual void reserved3() {}
public virtual void reserved4() {}
public virtual void reserved5() {}
public virtual void reserved6() {}
public virtual void reserved7() {}
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() {}
}
/**
* A structure holding an assortment of information about a {@link Pluggable}.
*/
public struct PluggableInfo {
public string? version;
public string? brief_description;
/**
* A comma-delimited list of the authors of this {@link Pluggable}.
*/
public string? authors;
public string? copyright;
public string? license;
public bool is_licensed_wordwrapped;
public bool is_license_wordwrapped;
public string? website_url;
public string? website_name;
public string? translators;
public Gdk.Pixbuf? icon;
}
//
// Each plug-in in a module needs to implement this interface at a minimum. Specific plug-in
// points may have (and probably will have) specific interface requirements as well.
//
/**
* A generic interface to all Shotwell plugins.
*
* Each plugin in a module needs to implement this interface at a minimum. Extension
* points may have (and probably will have) specific interface requirements as well.
*/
public interface Pluggable : Object {
//
// Like the Spit entry point, this mechanism allows for the host to negotiate with the Pluggable
// for its interface version. If the pluggable does not support an interface between the
// two ranges (inclusive), it should return UNSUPPORTED_INTERFACE.
//
/**
* Pluggable interface version negotiation.
*
* Like the {@link EntryPoint}, this mechanism allows for the host to negotiate with the Pluggable
* for its interface version. If the pluggable does not support an interface between the
* two ranges (inclusive), it should return {@link UNSUPPORTED_INTERFACE}.
*
* Note that this is ''not'' a negotiation of the SPIT interface versions (which is the
* responsibility of {@link EntryPoint}. Rather, each extension point is expected to version
* its own cluster of interfaces. It is that interface version that is being negotiated here.
*
* {@link negotiate_interfaces} can be used to implement this method.
*
* @param min_host_interface The host's minimum supported interface version number
* //for this Pluggable's intended extension point//.
* @param max_host_interface The host's maximum supported interface version number
* //for this Pluggable's intended extension point//.
*
* @return The version number supported by the host and the Pluggable or
* {@link UNSUPPORTED_INTERFACE}.
*/
public abstract int get_pluggable_interface(int min_host_interface, int max_host_interface);
//
// Returns a unique identifier for this Pluggable. Like Spit.Module.get_id(), best practice is
// to use a reverse-DNS-order scheme to avoid conflicts.
//
/**
* Returns a unique identifier for this Pluggable.
*
* Like {@link Module.get_id}, best practice is to use a reverse-DNS-order scheme to avoid
* conflicts.
*/
public abstract unowned string get_id();
//
// Returns a user-visible name for the Pluggable.
//
/**
* Returns a user-visible name for the Pluggable.
*/
public abstract unowned string get_pluggable_name();
//
// Returns extra information about the Pluggable that is used to identify it to the user.
//
/**
* Returns extra information about the Pluggable that is used to identify it to the user.
*/
public abstract void get_info(out PluggableInfo info);
//
// Called when the Pluggable is enabled (activated) or disabled (deactivated). It will be
// called at the start of the program if the user previously enabled/disabled it as well as
// during program execution if the user changes its state. Note that disabling a Pluggable
// does not require destroying existing resources or objects the Pluggable has previously
// handed off to the host.
//
// This is purely informational. The Pluggable should acquire any long-term resources it
// may be holding onto here, or wait until an extension-specific call is made to it.
//
/**
* Called when the Pluggable is enabled (activated) or disabled (deactivated).
*
* activation will be called at the start of the program if the user previously
* enabled/disabled it as well as during program execution if the user changes its state. Note
* that disabling a Pluggable does not require destroying existing resources or objects
* the Pluggable has previously handed off to the host.
*
* This is purely informational. The Pluggable should acquire any long-term resources
* it may be holding onto here, or wait until an extension-specific call is made to it.
*
* @param enabled ``true`` if the Pluggable has been enabled, ``false`` otherwise.
*/
public abstract void activation(bool enabled);
//
// For future expansion.
//
public virtual void reserved0() {}
public virtual void reserved1() {}
public virtual void reserved2() {}
public virtual void reserved3() {}
public virtual void reserved4() {}
public virtual void reserved5() {}
public virtual void reserved6() {}
public virtual void reserved7() {}
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() {}
}
//
// Each Pluggable is offered a Host interface for needs common to most plug-ins. Note that the
// Host is not explicitly handed to the Pluggable through that interface, but is expected to be
// offer to the Pluggable through the interface applicable to the extension point. This also allows
// the extension point to extend Host to offer other services applicable to the type of plug-in.
//
/**
* An interface to common services supplied by the host (Shotwell).
*
* Each {@link Pluggable} is offered a HostInterface for needs common to most plugins.
*
* Note that
* a HostInterface is not explicitly handed to the Pluggable through the SPIT interface, but is expected
* to be offered to the Pluggable through an interface applicable to the extension point. This
* also allows the extension point to extend HostInterface to offer other services applicable to the
* type of plugin.
*/
public interface HostInterface : Object {
/**
* Returns a File object representing the library file (.so/la.) that the plugin was loaded
* from.
*/
public abstract File get_module_file();
/**
* Get a boolean from a persistent configuration store.
*
* @param key The name of the value to be retrieved.
* @param def The default value (returned if the key has not been previously set).
*
* @return The value associated with key, def if not set.
*/
public abstract bool get_config_bool(string key, bool def);
/**
* Store a boolean in a persistent configuration store.
*
* @param key The name of the value to be stored.
* @param val The value to be stored.
*/
public abstract void set_config_bool(string key, bool val);
/**
* Get an integer from a persistent configuration store.
*
* @param key The name of the value to be retrieved.
* @param def The default value (returned if the key has not been previously set).
*
* @return The value associated with key, def if not set.
*/
public abstract int get_config_int(string key, int def);
/**
* Store an integer in a persistent configuration store.
*
* @param key The name of the value to be stored.
* @param val The value to be stored.
*/
public abstract void set_config_int(string key, int val);
/**
* Get a string from a persistent configuration store.
*
* @param key The name of the value to be retrieved.
* @param def The default value (returned if the key has not been previously set).
*
* @return The value associated with key, def if not set.
*/
public abstract string? get_config_string(string key, string? def);
/**
* Store a string in a persistent configuration store.
*
* @param key The name of the value to be stored.
* @param val The value to be stored.
*/
public abstract void set_config_string(string key, string? val);
/**
* Get a double from a persistent configuration store.
*
* @param key The name of the value to be retrieved.
* @param def The default value (returned if the key has not been previously set).
*
* @return The value associated with key, def if not set.
*/
public abstract double get_config_double(string key, double def);
/**
* Store a double in a persistent configuration store.
*
* @param key The name of the value to be stored.
* @param val The value to be stored.
*/
public abstract void set_config_double(string key, double val);
/**
* Delete the value from the persistent configuration store.
*/
public abstract void unset_config_key(string key);
//
// For future expansion.
//
public virtual void reserved0() {}
public virtual void reserved1() {}
public virtual void reserved2() {}
public virtual void reserved3() {}
public virtual void reserved4() {}
public virtual void reserved5() {}
public virtual void reserved6() {}
public virtual void reserved7() {}
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() {}
}
}
......
......@@ -4,43 +4,91 @@
* (version 2.1 or later). See the COPYING file in this distribution.
*/
// Transitions are used in Shotwell for interstitial effects in slideshow mode. They may
// also be used elsewhere in future releases.
/**
* Transitions are used in Shotwell for interstitial effects in slideshow mode. They may
* also be used elsewhere in future releases.
*
* Plugin writers should start by implementing a {@link Descriptor} which in turn Shotwell uses
* to instantiate an {@link Effect}.
*/
namespace Spit.Transitions {
/**
* The current version of the Transitions plugin interface.
*/
public const int CURRENT_INTERFACE = 0;
// Direction indicates what direction (animated motion) the Effect should simulate the images are
// moving, if appropriate. The direction indicates from what side or corner of the screen the
// new image should come in from. Thus, a LEFT slide means the current image exits via the
// left-hand edge of the screen and the new image moves into place from the right-hand edge.
//
// UP, DOWN, and diagonals may be added at some point.
/**
* Direction indicates what direction (animated motion) the {@link Effect} should simulate the
* images are moving, if appropriate.
*
* The direction indicates from what side or corner of the screen the new image should come in from.
* Thus, a LEFT slide means the current image exits via the left-hand edge of the screen and the
* new image moves into place from the right-hand edge.
*
* UP, DOWN, and diagonals may be added at some point.
*/
public enum Direction {
LEFT = 0,
RIGHT = 1,
// convenience definitions (for LTR readers)
/**
* Convenience definition (for LTR readers).
*/
FORWARD = LEFT,
/**
* Convenience definition (for LTR readers).
*/
BACKWARD = RIGHT
}
// Visuals contains the pertinent drawing information for the transition that must occur. This is
// supplied to Effect at the start of the transition and during each call to paint to the screen.
//
// Note that if starting from a blank screen, from_pixbuf will be null and from_pos will be
// zeroed. The transition should be considered to start from a blank screen of the supplied
// background color.
//
// Also note that if transitioning to a blank screen, to_pixbuf will be null and to_pos will be
// zeroes. Like the prior case, the transition should move toward a blank screen of the background
// color.
/**
* Visuals contains the pertinent drawing information for the transition that must occur.
*
* A Visuals object is supplied to {@link Effect} at the start of the transition and during each
* call to paint to the screen.
*
* Note that if starting with a blank screen, from_pixbuf will be null and from_pos will be
* zeroed. The transition should be considered to start from a blank screen of the supplied