[geary/mjog/email-templates: 9/17] Geary.Folder: Add `SpecialUse.CUSTOM` and `set_used_as_custom` method

[Michael Gratton <mjog src gnome org>]

commit a02297d01e4078d0c9b699f2e2c0c9ad81232cf0
Author: Michael Gratton <mike vee net>
Date:   Mon Apr 6 13:06:14 2020 +1000

    Geary.Folder: Add `SpecialUse.CUSTOM` and `set_used_as_custom` method
    
    Support applications setting custom special uses for folders.

 src/engine/api/geary-folder.vala                   | 39 ++++++++++++++++++++--
 src/engine/app/app-search-folder.vala              |  5 +++
 .../imap-engine/imap-engine-minimal-folder.vala    | 25 ++++++++++++--
 src/engine/outbox/outbox-folder.vala               |  5 +++
 test/engine/api/geary-folder-mock.vala             |  5 +++
 5 files changed, 75 insertions(+), 4 deletions(-)
---
diff --git a/src/engine/api/geary-folder.vala b/src/engine/api/geary-folder.vala
index e7069766..7ea9213a 100644
--- a/src/engine/api/geary-folder.vala
+++ b/src/engine/api/geary-folder.vala
@@ -108,7 +108,11 @@ public abstract class Geary.Folder : BaseObject, Logging.Source {
         IMPORTANT,
 
         /** A view of email matching some kind of search criteria. */
-        SEARCH;
+        SEARCH,
+
+        /** A folder with an application-defined use. */
+        CUSTOM;
+
 
         public bool is_outgoing() {
             return this == SENT || this == OUTBOX;
@@ -286,7 +290,15 @@ public abstract class Geary.Folder : BaseObject, Logging.Source {
     /** The folder path represented by this object. */
     public abstract Geary.FolderPath path { get; }
 
-    /** Determines the special use of this folder. */
+    /**
+     * Determines the special use of this folder.
+     *
+     * This will be set by the engine and updated as information about
+     * a folders use is discovered and changed.
+     *
+     * @see use_changed
+     * @see set_used_as_custom
+     */
     public abstract SpecialUse used_as { get; }
 
     /** Monitor for notifying of progress when opening the folder. */
@@ -703,6 +715,29 @@ public abstract class Geary.Folder : BaseObject, Logging.Source {
     public abstract async Geary.Email fetch_email_async(Geary.EmailIdentifier email_id,
         Geary.Email.Field required_fields, ListFlags flags, Cancellable? cancellable = null) throws Error;
 
+    /**
+     * Sets whether this folder has a custom special use.
+     *
+     * If `true`, this set a folder's {@link used_as} property so that
+     * it returns {@link SpecialUse.CUSTOM}. If the folder's existing
+     * special use is not currently set to {@link SpecialUse.NONE}
+     * then {@link EngineError.UNSUPPORTED} is thrown.
+     *
+     * If `false` and the folder's use is currently {@link
+     * SpecialUse.CUSTOM} then it is reset to be {@link
+     * SpecialUse.NONE}, otherwise if the folder's use is something
+     * other than {@link SpecialUse.NONE} then {@link
+     * EngineError.UNSUPPORTED} is thrown.
+     *
+     * If some other engine process causes this folder's use to be
+     * something other than {@link SpecialUse.NONE}, this will
+     * override the custom use.
+     *
+     * @see used_as
+     */
+    public abstract void set_used_as_custom(bool enabled)
+        throws EngineError.UNSUPPORTED;
+
     /** {@inheritDoc} */
     public virtual Logging.State to_logging_state() {
         return new Logging.State(this, this.path.to_string());
diff --git a/src/engine/app/app-search-folder.vala b/src/engine/app/app-search-folder.vala
index 32a3fc0a..f161c9fc 100644
--- a/src/engine/app/app-search-folder.vala
+++ b/src/engine/app/app-search-folder.vala
@@ -369,6 +369,11 @@ public class Geary.App.SearchFolder :
         }
     }
 
+    public override void set_used_as_custom(bool enabled)
+        throws EngineError.UNSUPPORTED {
+        throw new EngineError.UNSUPPORTED("Folder special use cannot be changed");
+    }
+
     private void require_id(EmailIdentifier id)
         throws EngineError.NOT_FOUND {
         if (!this.id_map.has_key(id)) {
diff --git a/src/engine/imap-engine/imap-engine-minimal-folder.vala 
b/src/engine/imap-engine/imap-engine-minimal-folder.vala
index eeb863d7..322dcfd8 100644
--- a/src/engine/imap-engine/imap-engine-minimal-folder.vala
+++ b/src/engine/imap-engine/imap-engine-minimal-folder.vala
@@ -178,12 +178,33 @@ private class Geary.ImapEngine.MinimalFolder : Geary.Folder, Geary.FolderSupport
         notify_email_flags_changed(flag_map);
     }
 
+    public override void set_used_as_custom(bool enabled)
+        throws EngineError.UNSUPPORTED {
+        if (enabled) {
+            if (this._used_as != NONE) {
+                throw new EngineError.UNSUPPORTED(
+                    "Folder already has special use"
+                );
+            }
+            set_use(CUSTOM);
+        } else {
+            if (this._used_as != CUSTOM &&
+                this._used_as != NONE) {
+                throw new EngineError.UNSUPPORTED(
+                    "Folder already has special use"
+                );
+            }
+            set_use(NONE);
+        }
+    }
+
     public void set_use(Folder.SpecialUse new_use) {
         var old_use = this._used_as;
         this._used_as = new_use;
-        if (old_use != new_use)
+        if (old_use != new_use) {
             notify_use_changed(old_use, new_use);
-        update_harvester();
+            update_harvester();
+        }
     }
 
     /** {@inheritDoc} */
diff --git a/src/engine/outbox/outbox-folder.vala b/src/engine/outbox/outbox-folder.vala
index b14aea91..6b5217b1 100644
--- a/src/engine/outbox/outbox-folder.vala
+++ b/src/engine/outbox/outbox-folder.vala
@@ -350,6 +350,11 @@ public class Geary.Outbox.Folder :
         return row_to_email(row);
     }
 
+    public override void set_used_as_custom(bool enabled)
+        throws EngineError.UNSUPPORTED {
+        throw new EngineError.UNSUPPORTED("Folder special use cannot be changed");
+    }
+
     internal async void
         add_to_containing_folders_async(Gee.Collection<Geary.EmailIdentifier> ids,
                                         Gee.MultiMap<Geary.EmailIdentifier,FolderPath> map,
diff --git a/test/engine/api/geary-folder-mock.vala b/test/engine/api/geary-folder-mock.vala
index 283a2079..3786dcc3 100644
--- a/test/engine/api/geary-folder-mock.vala
+++ b/test/engine/api/geary-folder-mock.vala
@@ -119,4 +119,9 @@ public class Geary.MockFolder : Folder, MockObject {
         throw new EngineError.UNSUPPORTED("Mock method");
     }
 
+    public override void set_used_as_custom(bool enabled)
+        throws EngineError.UNSUPPORTED {
+        throw new EngineError.UNSUPPORTED("Mock method");
+    }
+
 }