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  virtual void initializeData();
50  virtual void setSource(
51  const UT_StringHolder &source_identifier,
53 
54  ///
55  /// Required overrides
56  ///
57 
58  /// Check if the data source is valid. If not, no other methods will ever
59  /// be called on this object.
60  virtual bool isValid() const = 0;
61  /// If this method returns true, none of the set methods should ever be
62  /// called, or expected to do anything.
63  virtual bool isReadOnly() const = 0;
64  /// Return HTML formatted info about the data source.
65  virtual UT_StringHolder infoHtml() const = 0;
66 
67  /// Populate an array with all valid item ids.
68  virtual void itemIds(UT_StringArray &item_ids) const = 0;
69  virtual void updatedItemIds(UT_StringArray &item_ids) = 0;
70 
71  /// Populate an array with all valid item ids with the given parent 'item_id'. By default there is no hierarchy.
72  virtual void childItemIds(const UT_StringRef &parent_item_id, UT_StringArray &item_ids) const;
73 
74  /// A string identifying the implementation data type.
75  virtual UT_StringHolder sourceTypeName(
76  const UT_StringRef &item_id) const = 0;
77  virtual UT_StringHolder typeName(const UT_StringRef &item_id) const = 0;
78  virtual UT_StringHolder renderMethod(const UT_StringRef &item_id) const = 0;
79  virtual UT_StringHolder label(const UT_StringRef &item_id) const = 0;
80  virtual UT_WorkBuffer thumbnail(const UT_StringRef &item_id) const = 0;
81  virtual time_t creationDate(const UT_StringRef &item_id) const = 0;
82  virtual time_t modificationDate(const UT_StringRef &item_id) const = 0;
83  virtual bool isStarred(const UT_StringRef &item_id) const = 0;
84  virtual UT_StringHolder colorTag(const UT_StringRef &item_id) const = 0;
85  virtual UT_StringSet tags(const UT_StringRef &item_id) const = 0;
86  virtual UT_Options metadata(const UT_StringRef &item_id) const = 0;
87  virtual UT_StringHolder filePath(const UT_StringRef &item_id) const = 0;
88  virtual bool ownsFile(const UT_StringRef &item_id) const = 0;
89  virtual UT_WorkBuffer blindData(const UT_StringRef &item_id) const = 0;
90  virtual UT_StringHolder status(const UT_StringRef &item_id) const = 0;
91  /// Return the parent item id of the given 'item_id'
92  virtual UT_StringHolder parentId(const UT_StringRef &item_id) const = 0;
93  virtual UT_StringHolder prepareItemForUse(const UT_StringRef &item_id) const = 0;
94 
95  ///
96  /// Required overrides for writable data sources
97  ///
98 
99  virtual bool setRenderMethod(const UT_StringRef &item_id,
100  const UT_StringHolder &render_method)
101  { return false; }
102  virtual bool setLabel(const UT_StringRef &item_id,
103  const UT_StringHolder &label)
104  { return false; }
105  virtual bool setThumbnail(const UT_StringRef &item_id,
106  const UT_WorkBuffer &thumbnail)
107  { return false; }
108  virtual bool setModificationDate(const UT_StringRef &item_id,
109  time_t timestamp)
110  { return false; }
111  virtual bool setIsStarred(const UT_StringRef &item_id,
112  bool isstarred)
113  { return false; }
114  virtual bool setColorTag(const UT_StringRef &item_id,
115  const UT_StringHolder &color_tag)
116  { return false; }
117  virtual bool setMetadata(const UT_StringRef &item_id,
118  const UT_Options &metadata)
119  { return false; }
120  virtual bool setFilePath(const UT_StringRef &item_id,
121  const char *file_path)
122  { return false; }
123  virtual bool setOwnsFile(const UT_StringRef &item_id,
124  bool owns_file)
125  { return false; }
126  virtual bool setBlindData(const UT_StringRef &item_id,
127  const void *data, int data_size)
128  { return false; }
129  virtual bool setStatus(const UT_StringRef &item_id,
130  const UT_StringHolder &status)
131  { return false; }
132  virtual bool setParentId(const UT_StringRef &item_id,
133  const UT_StringHolder &parent_item_id)
134  { return false; }
135 
136  virtual bool createTag(const char *tag)
137  { return false; }
138  virtual bool deleteTag(const char *tag, bool delete_if_assigned) const
139  { return false; }
140  virtual bool addTag(const UT_StringRef &item_id, const char *tag)
141  { return false; }
142  virtual bool removeTag(const UT_StringRef &item_id, const char *tag) const
143  { return false; }
144 
145  virtual bool isFilePathEditable(const UT_StringRef &item_id) const
146  { return true; }
147 
148  /// Generates a file path to associate with a particular item id, for
149  /// cases where the new item needs a new file, as in a snapshot data source
150  /// (rather than referring to an existing file, as in an asset data source).
152  const UT_StringRef &item_id,
153  const char *file_ext)
155 
156  /// Add a new gallery item to the data source.
157  virtual UT_StringHolder addItem(const UT_StringRef &item_type_name,
158  const UT_StringRef &name,
159  const void *thumbnail_data,
160  int thumbnail_data_size,
161  const char *item_file,
162  bool item_owns_file,
163  const void *item_data,
164  int item_data_size,
165  time_t *creation_date,
166  const UT_StringRef &parent_id)
168 
169  /// Mark items for deletion in the data source.
170  /// Do nothing for invalid item ids or items that are already
171  /// marked for deletion.
172  virtual bool markItemsForDeletion(const UT_StringArray &item_ids)
173  { return false; }
174  /// Unmark items for deletion in the data source.
175  /// Do nothing for invalid item ids or items that are not
176  /// marked for deletion.
177  virtual bool unmarkItemsForDeletion(const UT_StringArray &item_ids)
178  { return false; }
179 
180  ///
181  /// Optional overrides
182  ///
183 
184  virtual void startTransaction() const
185  { }
186  virtual void endTransaction(bool commit = true) const
187  { }
188 
189  /// For file-based sources, does the equivalent of a "save as" operation.
190  /// The source identifier of the data source should be updated if the
191  /// implementation's save as operation reports success.
192  virtual bool saveAs(const UT_StringHolder &source_identifier)
193  { return false; }
194 
195 protected:
197 
198  void addOwner(const UT_GalleryDataSource *owner)
199  { myOwnerUpdatedIds.emplace(owner, UT_StringSet()); }
201  { myOwnerUpdatedIds.erase(owner); }
202  void ownerFetchedUpdatedIds(const UT_GalleryDataSource *owner,
203  UT_StringArray &item_ids);
204 
206 
207  friend class UT_GalleryDataSource;
208 };
209 
210 ///
211 /// Provides a stable API for QT_GalleryModel and its subclasses for populating
212 /// the model from a variety of data sources. Provides a plugin architecture
213 /// for adding new UT_GalleryDataSourceImpl subclasses which are constructed
214 /// based on the source_identifier sent to this object's constructor. Also
215 /// provides a global registry of UT_GalleryDataSource objects, so there is
216 /// always only one data source created for a given source_identifier.
217 ///
219 {
220 public:
221  UT_GalleryDataSource(const UT_StringHolder &source_identifier,
222  const UT_StringHolder &args);
224 
226 
227  typedef UT_Function
229  typedef UT_Function
232  static void registerDataSourceImplementation(
233  const ValidatorFunc &validator,
234  const CreatorFunc &creator);
235 
236  /// Return true if this gallery data source owns a valid data source
237  /// implementation object. You can still call all the methods on an
238  /// invalid object, but they do nothing. This check allows the UI to
239  /// present an error message for an invalid source identifier.
240  bool isValid() const
241  { return myImpl && myImpl->isValid(); }
242  /// Return true if the source implementation is read only.
243  bool isReadOnly() const
244  { return myImpl->isReadOnly(); }
245  /// Return the source identifier.
247  { return mySourceIdentifier; }
248  /// Return the source args.
250  { return mySourceArgs; }
251  /// Return HTML formatted info about the data source.
253  { return myImpl->infoHtml(); }
254 
255  /// Begins/ends transactions so that functions which end up
256  /// generating large numbers of queries/modifications can be
257  /// more efficient.
258  void startTransaction() const
259  { myImpl->startTransaction(); }
260  void endTransaction(bool commit = true) const
261  { myImpl->endTransaction(); }
262 
263  /// Populate an array with all valid item ids.
264  void itemIds(UT_StringArray &item_ids) const
265  { item_ids.clear(); myImpl->itemIds(item_ids); }
266  void updatedItemIds(UT_StringArray &item_ids);
267 
268  /// Populate an array with all valid item ids with the given parent 'item_id'
269  void childItemIds(const UT_StringRef &parent_item_id, UT_StringArray &item_ids) const
270  { item_ids.clear(); myImpl->childItemIds(parent_item_id, item_ids); }
271 
272  /// Return the source type.
274  { return myImpl->sourceTypeName(item_id); }
275  UT_StringHolder typeName(const UT_StringRef &item_id) const
276  { return myImpl->typeName(item_id); }
278  { return myImpl->renderMethod(item_id); }
279  UT_StringHolder label(const UT_StringRef &item_id) const
280  { return myImpl->label(item_id); }
281  UT_WorkBuffer thumbnail(const UT_StringRef &item_id) const
282  { return myImpl->thumbnail(item_id); }
283  time_t creationDate(const UT_StringRef &item_id) const
284  { return myImpl->creationDate(item_id); }
285  time_t modificationDate(const UT_StringRef &item_id) const
286  { return myImpl->modificationDate(item_id); }
287  bool isStarred(const UT_StringRef &item_id) const
288  { return myImpl->isStarred(item_id); }
289  UT_StringHolder colorTag(const UT_StringRef &item_id) const
290  { return myImpl->colorTag(item_id); }
291  UT_StringSet tags(const UT_StringRef &item_id) const
292  { return myImpl->tags(item_id); }
293  UT_Options metadata(const UT_StringRef &item_id) const
294  { return myImpl->metadata(item_id); }
295  UT_StringHolder filePath(const UT_StringRef &item_id) const
296  { return myImpl->filePath(item_id); }
297  bool ownsFile(const UT_StringRef &item_id) const
298  { return myImpl->ownsFile(item_id); }
299  UT_WorkBuffer blindData(const UT_StringRef &item_id) const
300  { return myImpl->blindData(item_id); }
301  UT_StringHolder status(const UT_StringRef &item_id) const
302  { return myImpl->status(item_id); }
303  UT_StringHolder parentId(const UT_StringRef &item_id) const
304  { return myImpl->parentId(item_id); }
306  { return myImpl->prepareItemForUse(item_id); }
307  bool isFilePathEditable(const UT_StringRef &item_id) const
308  { return myImpl->isFilePathEditable(item_id); }
309 
310  bool setRenderMethod(const UT_StringRef &item_id,
311  const UT_StringHolder &render_method);
312  bool setLabel(const UT_StringRef &item_id,
313  const UT_StringHolder &label);
314  bool setThumbnail(const UT_StringRef &item_id,
315  const UT_WorkBuffer &thumbnail);
316  bool setModificationDate(const UT_StringRef &item_id,
317  time_t timestamp);
318  bool setIsStarred(const UT_StringRef &item_id,
319  bool isstarred);
320  bool setColorTag(const UT_StringRef &item_id,
321  const UT_StringHolder &color_tag);
322  bool setMetadata(const UT_StringRef &item_id,
323  const UT_Options &metadata);
324  bool setFilePath(const UT_StringRef &item_id,
325  const char *file_path);
326  bool setOwnsFile(const UT_StringRef &item_id,
327  bool owns_file);
328  bool setBlindData(const UT_StringRef &item_id,
329  const void *data, int data_size);
330  bool setStatus(const UT_StringRef &item_id,
331  const UT_StringHolder &status);
332  bool setParentId(const UT_StringRef &item_id,
333  const UT_StringRef &parent_item_id);
334 
335  bool createTag(const char *tag);
336  bool deleteTag(const char *tag, bool delete_if_assigned);
337  bool addTag(const UT_StringRef &item_id, const char *tag);
338  bool removeTag(const UT_StringRef &item_id, const char *tag);
339 
340  /// Generates a file path to associate with a particular item id, for
341  /// cases where the new item needs a new file, as in a snapshot data source
342  /// (rather than referring to an existing file, as in an asset data source).
343  UT_StringHolder generateItemFilePath(
344  const UT_StringRef &item_id,
345  const char *file_ext);
346 
347  /// Add a new gallery item to the data source.
348  UT_StringHolder addItem(const UT_StringRef &item_type_name,
349  const UT_StringRef &name,
350  const void *thumbnail_data,
351  int thumbnail_data_size,
352  const char *item_file = nullptr,
353  bool item_owns_file = false,
354  const void *item_data = nullptr,
355  int item_data_size = 0,
356  time_t *creation_date = nullptr,
357  const UT_StringRef &parent_id = UT_StringHolder::theEmptyString);
358 
359  /// Mark items for deletion in the data source.
360  /// Do nothing for invalid item ids or items that are already
361  /// marked for deletion.
362  bool markItemsForDeletion(const UT_StringArray &item_ids);
363  /// Unmark items for deletion in the data source.
364  /// Do nothing for invalid item ids or items that are not
365  /// marked for deletion.
366  bool unmarkItemsForDeletion(const UT_StringArray &item_ids);
367 
368  /// For file-based sources, does the equivalent of a "save as" operation.
369  /// The source identifier of the data source should be updated if the
370  /// implementation's save as operation reports success.
371  bool saveAs(const UT_StringHolder &source_identifier);
372  void initializeData();
373  void setSource(
374  const UT_StringHolder &source_identifier,
376 
377 private:
378  UT_StringHolder mySourceIdentifier;
379  UT_StringHolder mySourceArgs;
380  UT_StringHolder myExpandedSourceIdentifier;
382 };
383 
384 #endif
GLuint GLsizei const GLchar * label
Definition: glcorearb.h:2545
#define UT_API
Definition: UT_API.h:14
OutGridT const XformOp bool bool
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:618
int setSource(int source) override
void clear()
Resets list to an empty list.
Definition: UT_Array.h:736
Definition: format.h:1821