[Kde-imaging] kdeextragear-libs-1/libkipi/libkipi

[Jesper Pedersen]

CVS commit by blackie: 

CCMAIL: kde-imaging at kde.org
As a conclusion to the path issues I've now implemented the following
changes in libkipi:

In ImageCollection added path() and uploadPath()
These two function must of course be implemented in the inherited version
of ImageCollectionShared, but a default implementation is given if you do
not care.

path() should return a path for the images. If that does not make sense the
host application may return a common root or even an empty URL. The plugins
are in the documentation of the method suggested to look at the feature
KIPI::AlbumEQDir before expecting that the path is the path of the album.

uploadPath() specifies a directory to place new images. By placing this
method in this class, it makes it possible for host application with
Dir==Album to place new images in these albums, and other application may
choose to place new images on common roots or even in one static directory.

A new KIPI::Features has been added, namely AcceptNewImages, which tells
the plugin if the image accept new images at all. Plugins should never call
uploadPath() of this feature is not present. Likewise if this feature is
present, the host application must implement the uploadPath() method.

In KIPI::Interface a new method has been created, namely addImage( KURL ),
with which the plugin must tell the host application about new images.


  M +27 -0     imagecollection.cpp   1.6
  M +2 -1      imagecollection.h   1.7
  M +13 -0     imagecollectionshared.cpp   1.3
  M +2 -0      imagecollectionshared.h   1.5
  M +19 -0     interface.cpp   1.8
  M +3 -1      interface.h   1.10


--- kdeextragear-libs-1/libkipi/libkipi/imagecollection.cpp  #1.5:1.6
@@ -89,2 +89,29 @@ KIPI::ImageCollection& KIPI::ImageCollec
     return *this;
 }
+
+/*!
+  Returns the directory for the image collections.
+  The host application may, however, return anything in case it does not
+  support the KIPI::Features AlbumEQDir, e.g. the directory of the first
+  image in the collection, the root of the image collection (in case all
+  images has a common root), or even an empty URL.
+*/
+KURL KIPI::ImageCollection::path() const
+{
+    return _data->path();
+}
+
+/*!
+  Returns the directory to place images into.
+  This function should only be called if KIPI::Features AcceptNewImages
+  is available.
+  The function may choose to return the directory for the image collection
+  or if images from the collection are not available in a common directory,
+  then instead a common upload directory.
+  In contrast to \ref path, this function must return a valid url.
+*/
+KURL KIPI::ImageCollection::uploadPath() const
+{
+    return _data->uploadPath();
+}
+

--- kdeextragear-libs-1/libkipi/libkipi/imagecollection.h  #1.6:1.7
@@ -15,5 +15,6 @@ namespace KIPI
         QString comment() const;
         KURL::List images() const;
-        KURL root() const ;
+        KURL path() const;
+        KURL uploadPath() const;
 
         // Interface for host application + general stuff

--- kdeextragear-libs-1/libkipi/libkipi/imagecollectionshared.cpp  #1.2:1.3
@@ -19,2 +19,15 @@ void KIPI::ImageCollectionShared::remove
 }
 
+KURL KIPI::ImageCollectionShared::path()
+{
+    return QString::null;
+}
+
+KURL KIPI::ImageCollectionShared::uploadPath()
+{
+    qFatal( "This method should only be invoked if the host application supports the KIPI::Features\n"
+            "AcceptNewImages - if the host application do support that, then this function should\n"
+            "have been overriden in the host application.");
+    return QString::null;
+}
+

--- kdeextragear-libs-1/libkipi/libkipi/imagecollectionshared.h  #1.4:1.5
@@ -15,4 +15,6 @@ namespace KIPI
         virtual QString comment() = 0;
         virtual KURL::List images() = 0;
+        virtual KURL path();
+        virtual KURL uploadPath();
 
     private:

--- kdeextragear-libs-1/libkipi/libkipi/interface.cpp  #1.7:1.8
@@ -50,4 +50,11 @@
 */
 
+/*!
+  \enum KIPI::AcceptNewImages
+  This feature specifies that the host application do accept new images.
+  Use \ref ImageCollection::uploadPath to find the location to place the image, and
+  \ref addImage() to tell the host application about the new image.
+*/
+
 KIPI::Interface::Interface(QObject *parent, const char *name )
     : QObject(parent, name)
@@ -82,3 +89,15 @@ bool KIPI::Interface::hasFeature( const 
 }
 
+/*!
+  Tell the host application that a new image has been made available to it.
+  Returns true if the host application did accept the new image.
+*/
+bool KIPI::Interface::addImage( const KURL& )
+{
+    qFatal( "This method should only be invoked if the host application supports the KIPI::Features\n"
+            "AcceptNewImages - if the host application do support that, then this function should\n"
+            "have been overriden in the host application.");
+    return false;
+}
+
 #include "interface.moc"

--- kdeextragear-libs-1/libkipi/libkipi/interface.h  #1.9:1.10
@@ -36,5 +36,6 @@ namespace KIPI
         ImagesHasComments      = 0x0004,
         ImagesHasTime          = 0x0008,
-        SupportsDateRanges     = 0x0010
+        SupportsDateRanges     = 0x0010,
+        AcceptNewImages        = 0x0020
     };
 
@@ -58,4 +59,5 @@ namespace KIPI
         /** Application keeps owner ship of the returned pointer, will only be valid till next call of this method */
         virtual ImageInfo info( const KURL& ) = 0;
+        virtual bool addImage( const KURL& );
 
         /** Tells the host app that the following images has changed on disk */