UT_GalleryDataSource.h

Go to the documentation of this file.

/*
 * PROPRIETARY INFORMATION.  This software is proprietary to
 * Side Effects Software Inc., and is not to be reproduced,
 * transmitted, or disclosed in any way without written permission.
 *
 * NAME:        UT_SQL.h
 *
 * COMMENTS:
 *      Data source for QT_GalleryModel. Uses an abstract implementation class
 *      to do the real work. The implementation class comes from a plugin
 *      framework based onthe requested source identifier string.
 */

#ifndef __UT_GALLERYDATASOURCE_H__
#define __UT_GALLERYDATASOURCE_H__

#include "UT_API.h"
#include "UT_Function.h"
#include "UT_GalleryTypes.h"
#include "UT_Map.h"
#include "UT_NonCopyable.h"
#include "UT_Options.h"
#include "UT_SharedPtr.h"
#include "UT_StringArray.h"
#include "UT_StringHolder.h"
#include "UT_StringSet.h"
#include "UT_WorkBuffer.h"

#include <SYS/SYS_Compiler.h>
#include <SYS/SYS_Inline.h>
#include <SYS/SYS_Time.h>

#include <time.h>

class UT_GalleryDataSource;

///
/// Implementation class for UT_GalleryDataSource. Subclass this and register
/// it with UT_GalleryDataSource as a plugin to create a new data source.
/// See documentation for hou.AssetGalleryDataSource for descriptions of the
/// methods that need to be implemented to create a new DataSource subclass.
///
class UT_API UT_GalleryDataSourceImpl
{
public:
    virtual ~UT_GalleryDataSourceImpl();
    UT_NON_COPYABLE(UT_GalleryDataSourceImpl)

    ///
    /// Required overrides
    ///

    /// Check if the data source is valid. If not, no other methods will ever
    /// be called on this object.
    virtual bool isValid() const = 0;
    /// If this method returns true, none of the set methods should ever be
    /// called, or expected to do anything.
    /// Exception: if this method returns true but supportsAnnotations()
    /// also returns true, then some set methods will be called. These
    /// are: setIsStarred, setColorTag, setMetadata, createTag, deleteTag,
    /// addTag, removeTag.
    virtual bool isReadOnly() const = 0;
    /// Per-item equivalent of isReadOnly(), only relevant when
    /// isReadOnly() is false. The exception documented on isReadOnly()
    /// applies here too.
    virtual bool isItemReadOnly(const UT_StringRef &item_id) const
    { return false; }
    /// Indicates whether annotations (stars, tags, etc) can be edited
    /// even when the gallery item contents are read-only.
    virtual bool supportsAnnotations() const
    { return false; }
    /// Return HTML formatted info about the data source.
    virtual UT_StringHolder infoHtml() const = 0;

    /// Populate an array with all valid item ids.
    virtual void itemIds(UT_StringArray &item_ids) const = 0;
    virtual void updatedItemIds(UT_StringArray &item_ids) = 0;

    /// Populate an array with all valid item ids with the given parent 'item_id'.  By default there is no hierarchy.
    virtual void childItemIds(const UT_StringRef &parent_item_id, UT_StringArray &item_ids) const;

    /// A string identifying the implementation data type.
    virtual UT_StringHolder sourceTypeName(
            const UT_StringRef &item_id) const = 0;
    virtual UT_StringHolder typeName(const UT_StringRef &item_id) const = 0;
    virtual UT_StringHolder renderMethod(const UT_StringRef &item_id) const = 0;
    virtual UT_StringHolder label(const UT_StringRef &item_id) const = 0;
    virtual UT_WorkBuffer thumbnail(const UT_StringRef &item_id) const = 0;
    /// Return a Qt resource path for an icon to display in tree view mode.
    /// If empty, the gallery falls back to the item's thumbnail.
    virtual UT_StringHolder treeIcon(const UT_StringRef &item_id) const
    { return UT_StringHolder::theEmptyString; }
    virtual time_t creationDate(const UT_StringRef &item_id) const = 0;
    virtual time_t modificationDate(const UT_StringRef &item_id) const = 0;
    virtual bool isStarred(const UT_StringRef &item_id) const = 0;
    virtual UT_StringHolder colorTag(const UT_StringRef &item_id) const = 0;
    virtual UT_StringSet tags(const UT_StringRef &item_id) const = 0;
    virtual UT_Options metadata(const UT_StringRef &item_id) const = 0;
    virtual UT_StringHolder filePath(const UT_StringRef &item_id) const = 0;
    virtual bool ownsFile(const UT_StringRef &item_id) const = 0;
    virtual UT_WorkBuffer blindData(const UT_StringRef &item_id) const = 0;
    virtual UT_StringHolder status(const UT_StringRef &item_id) const = 0;
    /// Return the parent item id of the given 'item_id'
    virtual UT_StringHolder parentId(const UT_StringRef &item_id) const = 0;
    virtual UT_StringHolder prepareItemForUse(const UT_StringRef &item_id) const = 0;

    ///
    /// Required overrides for writable data sources
    ///

    virtual bool setRenderMethod(const UT_StringRef &item_id,
            const UT_StringHolder &render_method)
    { return false; }
    virtual bool setLabel(const UT_StringRef &item_id,
            const UT_StringHolder &label)
    { return false; }
    virtual bool setThumbnail(const UT_StringRef &item_id,
            const UT_WorkBuffer &thumbnail)
    { return false; }
    virtual bool setModificationDate(const UT_StringRef &item_id,
            time_t timestamp)
    { return false; }
    virtual bool setIsStarred(const UT_StringRef &item_id,
            bool isstarred)
    { return false; }
    virtual bool setColorTag(const UT_StringRef &item_id,
            const UT_StringHolder &color_tag)
    { return false; }
    virtual bool setMetadata(const UT_StringRef &item_id,
            const UT_Options &metadata)
    { return false; }
    virtual bool setFilePath(const UT_StringRef &item_id,
            const char *file_path)
    { return false; }
    virtual bool setOwnsFile(const UT_StringRef &item_id,
            bool owns_file)
    { return false; }
    virtual bool setBlindData(const UT_StringRef &item_id,
            const void *data, int data_size)
    { return false; }
    virtual bool setStatus(const UT_StringRef &item_id,
            const UT_StringHolder &status)
    { return false; }
    virtual bool setParentId(const UT_StringRef &item_id,
            const UT_StringHolder &parent_item_id)
    { return false; }

    virtual bool createTag(const char *tag)
    { return false; }
    virtual bool deleteTag(const char *tag, bool delete_if_assigned) const
    { return false; }
    virtual bool addTag(const UT_StringRef &item_id, const char *tag)
    { return false; }
    virtual bool removeTag(const UT_StringRef &item_id, const char *tag) const
    { return false; }

    virtual bool isFilePathEditable(const UT_StringRef &item_id) const
    { return true; }

    /// Generates a file path to associate with a particular item id, for
    /// cases where the new item needs a new file, as in a snapshot data source
    /// (rather than referring to an existing file, as in an asset data source).
    virtual UT_StringHolder generateItemFilePath(
        const UT_StringRef &item_id,
        const char *file_ext)
    { return UT_StringHolder::theEmptyString; }

    /// Add a new gallery item to the data source.
    virtual UT_StringHolder addItem(const UT_StringRef &item_type_name,
        const UT_StringRef &name,
        const void *thumbnail_data,
        int thumbnail_data_size,
        const char *item_file,
        bool item_owns_file,
        const void *item_data,
        int item_data_size,
        time_t *creation_date,
        const UT_StringRef &parent_id)
    { return UT_StringHolder::theEmptyString; }

    /// Mark items for deletion in the data source.
    /// Do nothing for invalid item ids or items that are already
    /// marked for deletion.
    virtual bool markItemsForDeletion(const UT_StringArray &item_ids)
    { return false; }
    /// Unmark items for deletion in the data source.
    /// Do nothing for invalid item ids or items that are not
    /// marked for deletion.
    virtual bool unmarkItemsForDeletion(const UT_StringArray &item_ids)
    { return false; }

    ///
    /// Optional overrides
    ///

    virtual void startTransaction() const
    { }
    virtual void endTransaction(bool commit = true) const
    { }

    /// For file-based sources, does the equivalent of a "save as" operation.
    /// The source identifier of the data source should be updated if the
    /// implementation's save as operation reports success.
    virtual bool saveAs(const UT_StringHolder &source_identifier)
    { return false; }

protected:
    UT_GalleryDataSourceImpl();

    void         addOwner(const UT_GalleryDataSource *owner)
                 { myOwnerUpdatedIds.emplace(owner, UT_StringSet()); }
    void         removeOwner(const UT_GalleryDataSource *owner)
                 { myOwnerUpdatedIds.erase(owner); }
    void         ownerFetchedUpdatedIds(const UT_GalleryDataSource *owner,
                        UT_StringArray &item_ids);

    UT_Map<const UT_GalleryDataSource *, UT_StringSet> myOwnerUpdatedIds;

    friend class UT_GalleryDataSource;
};

///
/// Provides a stable API for QT_GalleryModel and its subclasses for populating
/// the model from a variety of data sources. Provides a plugin architecture
/// for adding new UT_GalleryDataSourceImpl subclasses which are constructed
/// based on the source_identifier sent to this object's constructor. Also
/// provides a global registry of UT_GalleryDataSource objects, so there is
/// always only one data source created for a given source_identifier.
///
class UT_API UT_GalleryDataSource
{
public:
     UT_GalleryDataSource(const UT_StringHolder &source_identifier,
            const UT_StringHolder &args);
    ~UT_GalleryDataSource();

    UT_NON_COPYABLE(UT_GalleryDataSource)

    typedef UT_Function
            <bool (const UT_StringHolder &)> ValidatorFunc;
    typedef UT_Function
            <UT_SharedPtr<UT_GalleryDataSourceImpl> (
                const UT_StringHolder &, const UT_StringHolder &)> CreatorFunc;
    static void registerDataSourceImplementation(
            const ValidatorFunc &validator,
            const CreatorFunc &creator);

    /// Return true if this gallery data source owns a valid data source
    /// implementation object. You can still call all the methods on an
    /// invalid object, but they do nothing. This check allows the UI to
    /// present an error message for an invalid source identifier.
    bool isValid() const
    { return myImpl && myImpl->isValid(); }
    /// Return true if the source implementation is read only.
    bool isReadOnly() const
    { return myImpl->isReadOnly(); }
    /// Return true if the source supports mutable per-item annotations even
    /// when isReadOnly() is true.
    bool supportsAnnotations() const
    { return myImpl->supportsAnnotations(); }
    /// Return true if this specific item is read-only. Only called
    /// when isReadOnly() is false.
    bool isItemReadOnly(const UT_StringRef &item_id) const
    { return myImpl->isItemReadOnly(item_id); }
    /// Return the source identifier.
    const UT_StringHolder &sourceIdentifier() const
    { return mySourceIdentifier; }
    /// Return the source args.
    const UT_StringHolder &sourceArgs() const
    { return mySourceArgs; }
    /// Return HTML formatted info about the data source.
    UT_StringHolder infoHtml() const
    { return myImpl->infoHtml(); }

    /// Begins/ends transactions so that functions which end up
    /// generating large numbers of queries/modifications can be
    /// more efficient.
    void startTransaction() const
    { myImpl->startTransaction(); }
    void endTransaction(bool commit = true) const
    { myImpl->endTransaction(); }

    /// Populate an array with all valid item ids.
    void itemIds(UT_StringArray &item_ids) const
    { item_ids.clear(); myImpl->itemIds(item_ids); }
    void updatedItemIds(UT_StringArray &item_ids);

    /// Populate an array with all valid item ids with the given parent 'item_id'
    void childItemIds(const UT_StringRef &parent_item_id, UT_StringArray &item_ids) const
    { item_ids.clear(); myImpl->childItemIds(parent_item_id, item_ids); }

    /// Return the source type.
    UT_StringHolder sourceTypeName(const UT_StringRef &item_id) const
    { return myImpl->sourceTypeName(item_id); }
    UT_StringHolder typeName(const UT_StringRef &item_id) const
    { return myImpl->typeName(item_id); }
    UT_StringHolder renderMethod(const UT_StringRef &item_id) const
    { return myImpl->renderMethod(item_id); }
    UT_StringHolder label(const UT_StringRef &item_id) const
    { return myImpl->label(item_id); }
    UT_WorkBuffer thumbnail(const UT_StringRef &item_id) const
    { return myImpl->thumbnail(item_id); }
    UT_StringHolder treeIcon(const UT_StringRef &item_id) const
    { return myImpl->treeIcon(item_id); }
    time_t creationDate(const UT_StringRef &item_id) const
    { return myImpl->creationDate(item_id); }
    time_t modificationDate(const UT_StringRef &item_id) const
    { return myImpl->modificationDate(item_id); }
    bool isStarred(const UT_StringRef &item_id) const
    { return myImpl->isStarred(item_id); }
    UT_StringHolder colorTag(const UT_StringRef &item_id) const
    { return myImpl->colorTag(item_id); }
    UT_StringSet tags(const UT_StringRef &item_id) const
    { return myImpl->tags(item_id); }
    UT_Options metadata(const UT_StringRef &item_id) const
    { return myImpl->metadata(item_id); }
    UT_StringHolder filePath(const UT_StringRef &item_id) const
    { return myImpl->filePath(item_id); }
    bool ownsFile(const UT_StringRef &item_id) const
    { return myImpl->ownsFile(item_id); }
    UT_WorkBuffer blindData(const UT_StringRef &item_id) const
    { return myImpl->blindData(item_id); }
    UT_StringHolder status(const UT_StringRef &item_id) const
    { return myImpl->status(item_id); }
    UT_StringHolder parentId(const UT_StringRef &item_id) const
    { return myImpl->parentId(item_id); }
    UT_StringHolder prepareItemForUse(const UT_StringRef &item_id) const
    { return myImpl->prepareItemForUse(item_id); }
    bool isFilePathEditable(const UT_StringRef &item_id) const
    { return myImpl->isFilePathEditable(item_id); }

    bool setRenderMethod(const UT_StringRef &item_id,
            const UT_StringHolder &render_method);
    bool setLabel(const UT_StringRef &item_id,
            const UT_StringHolder &label);
    bool setThumbnail(const UT_StringRef &item_id,
            const UT_WorkBuffer &thumbnail);
    bool setModificationDate(const UT_StringRef &item_id,
            time_t timestamp);
    bool setIsStarred(const UT_StringRef &item_id,
            bool isstarred);
    bool setColorTag(const UT_StringRef &item_id,
            const UT_StringHolder &color_tag);
    bool setMetadata(const UT_StringRef &item_id,
            const UT_Options &metadata);
    bool setFilePath(const UT_StringRef &item_id,
            const char *file_path);
    bool setOwnsFile(const UT_StringRef &item_id,
            bool owns_file);
    bool setBlindData(const UT_StringRef &item_id,
            const void *data, int data_size);
    bool setStatus(const UT_StringRef &item_id,
            const UT_StringHolder &status);
    bool setParentId(const UT_StringRef &item_id,
            const UT_StringRef &parent_item_id);

    bool createTag(const char *tag);
    bool deleteTag(const char *tag, bool delete_if_assigned);
    bool addTag(const UT_StringRef &item_id, const char *tag);
    bool removeTag(const UT_StringRef &item_id, const char *tag);

    /// Generates a file path to associate with a particular item id, for
    /// cases where the new item needs a new file, as in a snapshot data source
    /// (rather than referring to an existing file, as in an asset data source).
    UT_StringHolder generateItemFilePath(
            const UT_StringRef &item_id,
            const char *file_ext);

    /// Add a new gallery item to the data source.
    UT_StringHolder addItem(const UT_StringRef &item_type_name,
            const UT_StringRef &name,
            const void *thumbnail_data,
            int thumbnail_data_size,
            const char *item_file = nullptr,
            bool item_owns_file = false,
            const void *item_data = nullptr,
            int item_data_size = 0,
            time_t *creation_date = nullptr,
            const UT_StringRef &parent_id = UT_StringHolder::theEmptyString);

    /// Mark items for deletion in the data source.
    /// Do nothing for invalid item ids or items that are already
    /// marked for deletion.
    bool markItemsForDeletion(const UT_StringArray &item_ids);
    /// Unmark items for deletion in the data source.
    /// Do nothing for invalid item ids or items that are not
    /// marked for deletion.
    bool unmarkItemsForDeletion(const UT_StringArray &item_ids);

    /// For file-based sources, does the equivalent of a "save as" operation.
    /// The source identifier of the data source should be updated if the
    /// implementation's save as operation reports success.
    bool saveAs(const UT_StringHolder &source_identifier);

private:
    UT_StringHolder                          mySourceIdentifier;
    UT_StringHolder                          mySourceArgs;
    UT_StringHolder                          myExpandedSourceIdentifier;
    UT_SharedPtr<UT_GalleryDataSourceImpl>   myImpl;
};

#endif