HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
UT_GalleryDataSource.h
Go to the documentation of this file.
1 /*
2  * PROPRIETARY INFORMATION. This software is proprietary to
3  * Side Effects Software Inc., and is not to be reproduced,
4  * transmitted, or disclosed in any way without written permission.
5  *
6  * NAME: UT_SQL.h
7  *
8  * COMMENTS:
9  * Data source for QT_GalleryModel. Uses an abstract implementation class
10  * to do the real work. The implementation class comes from a plugin
11  * framework based onthe requested source identifier string.
12  */
13 
14 #ifndef __UT_GALLERYDATASOURCE_H__
15 #define __UT_GALLERYDATASOURCE_H__
16 
17 #include "UT_API.h"
18 #include "UT_Function.h"
19 #include "UT_GalleryTypes.h"
20 #include "UT_Map.h"
21 #include "UT_NonCopyable.h"
22 #include "UT_Options.h"
23 #include "UT_SharedPtr.h"
24 #include "UT_StringArray.h"
25 #include "UT_StringHolder.h"
26 #include "UT_StringSet.h"
27 #include "UT_WorkBuffer.h"
28 
29 #include <SYS/SYS_Compiler.h>
30 #include <SYS/SYS_Inline.h>
31 #include <SYS/SYS_Time.h>
32 
33 #include <time.h>
34 
36 
37 ///
38 /// Implementation class for UT_GalleryDataSource. Subclass this and register
39 /// it with UT_GalleryDataSource as a plugin to create a new data source.
40 /// See documentation for hou.AssetGalleryDataSource for descriptions of the
41 /// methods that need to be implemented to create a new DataSource subclass.
42 ///
44 {
45 public:
46  virtual ~UT_GalleryDataSourceImpl();
47 
49 
50  ///
51  /// Required overrides
52  ///
53 
54  /// Check if the data source is valid. If not, no other methods will ever
55  /// be called on this object.
56  virtual bool isValid() const = 0;
57  /// If this method returns true, none of the set methods should ever be
58  /// called, or expected to do anything.
59  virtual bool isReadOnly() const = 0;
60  /// Return HTML formatted info about the data source.
61  virtual UT_StringHolder infoHtml() const = 0;
62 
63  /// Populate an array with all valid item ids.
64  virtual void itemIds(UT_StringArray &item_ids) const = 0;
65  virtual void updatedItemIds(UT_StringArray &item_ids) = 0;
66 
67  /// Populate an array with all valid item ids with the given parent 'item_id'. By default there is no hierarchy.
68  virtual void childItemIds(const UT_StringRef &parent_item_id, UT_StringArray &item_ids) const;
69 
70  /// A string identifying the implementation data type.
71  virtual UT_StringHolder sourceTypeName(
72  const UT_StringRef &item_id) const = 0;
73  virtual UT_StringHolder typeName(const UT_StringRef &item_id) const = 0;
74  virtual UT_StringHolder label(const UT_StringRef &item_id) const = 0;
75  virtual UT_WorkBuffer thumbnail(const UT_StringRef &item_id) const = 0;
76  virtual time_t creationDate(const UT_StringRef &item_id) const = 0;
77  virtual time_t modificationDate(const UT_StringRef &item_id) const = 0;
78  virtual bool isStarred(const UT_StringRef &item_id) const = 0;
79  virtual UT_StringHolder colorTag(const UT_StringRef &item_id) const = 0;
80  virtual UT_StringSet tags(const UT_StringRef &item_id) const = 0;
81  virtual UT_Options metadata(const UT_StringRef &item_id) const = 0;
82  virtual UT_StringHolder filePath(const UT_StringRef &item_id) const = 0;
83  virtual bool ownsFile(const UT_StringRef &item_id) const = 0;
84  virtual UT_WorkBuffer blindData(const UT_StringRef &item_id) const = 0;
85  virtual UT_StringHolder status(const UT_StringRef &item_id) const = 0;
86  /// Return the parent item id of the given 'item_id'
87  virtual UT_StringHolder parentId(const UT_StringRef &item_id) const = 0;
88  virtual UT_StringHolder prepareItemForUse(const UT_StringRef &item_id) const = 0;
89 
90  ///
91  /// Required overrides for writable data sources
92  ///
93 
94  virtual bool setLabel(const UT_StringRef &item_id,
95  const UT_StringHolder &label)
96  { return false; }
97  virtual bool setThumbnail(const UT_StringRef &item_id,
98  const UT_WorkBuffer &thumbnail)
99  { return false; }
100  virtual bool setModificationDate(const UT_StringRef &item_id,
101  time_t timestamp)
102  { return false; }
103  virtual bool setIsStarred(const UT_StringRef &item_id,
104  bool isstarred)
105  { return false; }
106  virtual bool setColorTag(const UT_StringRef &item_id,
107  const UT_StringHolder &color_tag)
108  { return false; }
109  virtual bool setMetadata(const UT_StringRef &item_id,
110  const UT_Options &metadata)
111  { return false; }
112  virtual bool setFilePath(const UT_StringRef &item_id,
113  const char *file_path)
114  { return false; }
115  virtual bool setOwnsFile(const UT_StringRef &item_id,
116  bool owns_file)
117  { return false; }
118  virtual bool setBlindData(const UT_StringRef &item_id,
119  const void *data, int data_size)
120  { return false; }
121  virtual bool setStatus(const UT_StringRef &item_id,
122  const UT_StringHolder &status)
123  { return false; }
124  virtual bool setParentId(const UT_StringRef &item_id,
125  const UT_StringHolder &parent_item_id)
126  { return false; }
127 
128  virtual bool createTag(const char *tag)
129  { return false; }
130  virtual bool deleteTag(const char *tag, bool delete_if_assigned) const
131  { return false; }
132  virtual bool addTag(const UT_StringRef &item_id, const char *tag)
133  { return false; }
134  virtual bool removeTag(const UT_StringRef &item_id, const char *tag) const
135  { return false; }
136 
137  /// Generates a file path to associate with a particular item id, for
138  /// cases where the new item needs a new file, as in a snapshot data source
139  /// (rather than referring to an existing file, as in an asset data source).
141  const UT_StringRef &item_id,
142  const char *file_ext)
144 
145  /// Add a new gallery item to the data source.
146  virtual UT_StringHolder addItem(const UT_StringRef &item_type_name,
147  const UT_StringRef &name,
148  const void *thumbnail_data,
149  int thumbnail_data_size,
150  const char *item_file,
151  bool item_owns_file,
152  const void *item_data,
153  int item_data_size,
154  time_t *creation_date,
155  const UT_StringRef &parent_id)
157 
158  /// Mark items for deletion in the data source.
159  /// Do nothing for invalid item ids or items that are already
160  /// marked for deletion.
161  virtual bool markItemsForDeletion(const UT_StringArray &item_ids)
162  { return false; }
163  /// Unmark items for deletion in the data source.
164  /// Do nothing for invalid item ids or items that are not
165  /// marked for deletion.
166  virtual bool unmarkItemsForDeletion(const UT_StringArray &item_ids)
167  { return false; }
168 
169  ///
170  /// Optional overrides
171  ///
172 
173  virtual void startTransaction() const
174  { }
175  virtual void endTransaction(bool commit = true) const
176  { }
177 
178  /// For file-based sources, does the equivalent of a "save as" operation.
179  /// The source identifier of the data source should be updated if the
180  /// implementation's save as operation reports success.
181  virtual bool saveAs(const UT_StringHolder &source_identifier)
182  { return false; }
183 
184 protected:
186 
187  void addOwner(const UT_GalleryDataSource *owner)
188  { myOwnerUpdatedIds.emplace(owner, UT_StringSet()); }
190  { myOwnerUpdatedIds.erase(owner); }
191  void ownerFetchedUpdatedIds(const UT_GalleryDataSource *owner,
192  UT_StringArray &item_ids);
193 
195 
196  friend class UT_GalleryDataSource;
197 };
198 
199 ///
200 /// Provides a stable API for QT_GalleryModel and its subclasses for populating
201 /// the model from a variety of data sources. Provides a plugin architecture
202 /// for adding new UT_GalleryDataSourceImpl subclasses which are constructed
203 /// based on the source_identifier sent to this object's constructor. Also
204 /// provides a global registry of UT_GalleryDataSource objects, so there is
205 /// always only one data source created for a given source_identifier.
206 ///
208 {
209 public:
210  UT_GalleryDataSource(const UT_StringHolder &source_identifier,
211  const UT_StringHolder &args);
213 
215 
216  typedef UT_Function
217  <bool (const UT_StringHolder &)> ValidatorFunc;
218  typedef UT_Function
221  static void registerDataSourceImplementation(
222  const ValidatorFunc &validator,
223  const CreatorFunc &creator);
224 
225  /// Return true if this gallery data source owns a valid data source
226  /// implementation object. You can still call all the methods on an
227  /// invalid object, but they do nothing. This check allows the UI to
228  /// present an error message for an invalid source identifier.
229  bool isValid() const
230  { return myImpl && myImpl->isValid(); }
231  /// Return true if the source implementation is read only.
232  bool isReadOnly() const
233  { return myImpl->isReadOnly(); }
234  /// Return the source identifier.
236  { return mySourceIdentifier; }
237  /// Return the source args.
239  { return mySourceArgs; }
240  /// Return HTML formatted info about the data source.
242  { return myImpl->infoHtml(); }
243 
244  /// Begins/ends transactions so that functions which end up
245  /// generating large numbers of queries/modifications can be
246  /// more efficient.
247  void startTransaction() const
248  { myImpl->startTransaction(); }
249  void endTransaction(bool commit = true) const
250  { myImpl->endTransaction(); }
251 
252  /// Populate an array with all valid item ids.
253  void itemIds(UT_StringArray &item_ids) const
254  { item_ids.clear(); myImpl->itemIds(item_ids); }
255  void updatedItemIds(UT_StringArray &item_ids);
256 
257  /// Populate an array with all valid item ids with the given parent 'item_id'
258  void childItemIds(const UT_StringRef &parent_item_id, UT_StringArray &item_ids) const
259  { item_ids.clear(); myImpl->childItemIds(parent_item_id, item_ids); }
260 
261  /// Return the source type.
263  { return myImpl->sourceTypeName(item_id); }
264  UT_StringHolder typeName(const UT_StringRef &item_id) const
265  { return myImpl->typeName(item_id); }
266  UT_StringHolder label(const UT_StringRef &item_id) const
267  { return myImpl->label(item_id); }
268  UT_WorkBuffer thumbnail(const UT_StringRef &item_id) const
269  { return myImpl->thumbnail(item_id); }
270  time_t creationDate(const UT_StringRef &item_id) const
271  { return myImpl->creationDate(item_id); }
272  time_t modificationDate(const UT_StringRef &item_id) const
273  { return myImpl->modificationDate(item_id); }
274  bool isStarred(const UT_StringRef &item_id) const
275  { return myImpl->isStarred(item_id); }
276  UT_StringHolder colorTag(const UT_StringRef &item_id) const
277  { return myImpl->colorTag(item_id); }
278  UT_StringSet tags(const UT_StringRef &item_id) const
279  { return myImpl->tags(item_id); }
280  UT_Options metadata(const UT_StringRef &item_id) const
281  { return myImpl->metadata(item_id); }
282  UT_StringHolder filePath(const UT_StringRef &item_id) const
283  { return myImpl->filePath(item_id); }
284  bool ownsFile(const UT_StringRef &item_id) const
285  { return myImpl->ownsFile(item_id); }
286  UT_WorkBuffer blindData(const UT_StringRef &item_id) const
287  { return myImpl->blindData(item_id); }
288  UT_StringHolder status(const UT_StringRef &item_id) const
289  { return myImpl->status(item_id); }
290  UT_StringHolder parentId(const UT_StringRef &item_id) const
291  { return myImpl->parentId(item_id); }
293  { return myImpl->prepareItemForUse(item_id); }
294 
295  bool setLabel(const UT_StringRef &item_id,
296  const UT_StringHolder &label);
297  bool setThumbnail(const UT_StringRef &item_id,
298  const UT_WorkBuffer &thumbnail);
299  bool setModificationDate(const UT_StringRef &item_id,
300  time_t timestamp);
301  bool setIsStarred(const UT_StringRef &item_id,
302  bool isstarred);
303  bool setColorTag(const UT_StringRef &item_id,
304  const UT_StringHolder &color_tag);
305  bool setMetadata(const UT_StringRef &item_id,
306  const UT_Options &metadata);
307  bool setFilePath(const UT_StringRef &item_id,
308  const char *file_path);
309  bool setOwnsFile(const UT_StringRef &item_id,
310  bool owns_file);
311  bool setBlindData(const UT_StringRef &item_id,
312  const void *data, int data_size);
313  bool setStatus(const UT_StringRef &item_id,
314  const UT_StringHolder &status);
315  bool setParentId(const UT_StringRef &item_id,
316  const UT_StringRef &parent_item_id);
317 
318  bool createTag(const char *tag);
319  bool deleteTag(const char *tag, bool delete_if_assigned);
320  bool addTag(const UT_StringRef &item_id, const char *tag);
321  bool removeTag(const UT_StringRef &item_id, const char *tag);
322 
323  /// Generates a file path to associate with a particular item id, for
324  /// cases where the new item needs a new file, as in a snapshot data source
325  /// (rather than referring to an existing file, as in an asset data source).
326  UT_StringHolder generateItemFilePath(
327  const UT_StringRef &item_id,
328  const char *file_ext);
329 
330  /// Add a new gallery item to the data source.
331  UT_StringHolder addItem(const UT_StringRef &item_type_name,
332  const UT_StringRef &name,
333  const void *thumbnail_data,
334  int thumbnail_data_size,
335  const char *item_file = nullptr,
336  bool item_owns_file = false,
337  const void *item_data = nullptr,
338  int item_data_size = 0,
339  time_t *creation_date = nullptr,
340  const UT_StringRef &parent_id = UT_StringHolder::theEmptyString);
341 
342  /// Mark items for deletion in the data source.
343  /// Do nothing for invalid item ids or items that are already
344  /// marked for deletion.
345  bool markItemsForDeletion(const UT_StringArray &item_ids);
346  /// Unmark items for deletion in the data source.
347  /// Do nothing for invalid item ids or items that are not
348  /// marked for deletion.
349  bool unmarkItemsForDeletion(const UT_StringArray &item_ids);
350 
351  /// For file-based sources, does the equivalent of a "save as" operation.
352  /// The source identifier of the data source should be updated if the
353  /// implementation's save as operation reports success.
354  bool saveAs(const UT_StringHolder &source_identifier);
355 
356 private:
357  UT_StringHolder mySourceIdentifier;
358  UT_StringHolder mySourceArgs;
359  UT_StringHolder myExpandedSourceIdentifier;
361 };
362 
363 #endif
GLuint GLsizei const GLchar * label
Definition: glcorearb.h:2545
#define UT_API
Definition: UT_API.h:14
GLintptr GLsizeiptr GLboolean commit
Definition: glcorearb.h:3363
std::shared_ptr< T > UT_SharedPtr
Wrapper around std::shared_ptr.
Definition: UT_SharedPtr.h:36
static const UT_StringHolder theEmptyString
#define UT_NON_COPYABLE(CLASS)
Define deleted copy constructor and assignment operator inside a class.
GLuint const GLchar * name
Definition: glcorearb.h:786
std::function< T > UT_Function
Definition: UT_Function.h:37
A map of string to various well defined value types.
Definition: UT_Options.h:84
**If you just want to fire and args
Definition: thread.h:609
void clear()
Resets list to an empty list.
Definition: UT_Array.h:729
Definition: format.h:895