HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
AP_Interface.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: AP_Interface.h ( SI Library, C++)
7  *
8  * COMMENTS:
9  */
10 
11 #ifndef __AP_Interface__
12 #define __AP_Interface__
13 
14 #include "SI_API.h"
15 #include <stdio.h>
16 
17 #include <UI/UI_Object.h>
18 
19 #include <UT/UT_Error.h>
20 #include <UT/UT_Signal.h>
21 #include <UT/UT_ValArray.h>
22 #include <UT/UT_String.h>
23 #include <UT/UT_WorkBuffer.h>
24 #include <UT/UT_SharedPtr.h>
25 #include <UT/UT_UniquePtr.h>
26 
27 #include <utility>
28 
29 class UT_Url;
30 
31 class AP_Interface;
32 class UI_Value;
33 class UI_Manager;
34 template<typename T> class UT_SymbolMap;
35 class UI_Feel;
36 class UI_KeyDelegate;
39 class UI_Window;
43 
44 /// Base class for interfaces.
45 /// This class' main responsibility is to maintain hash tables of named
46 /// UI_Feel "object symbol" and UI_Value "value symbol" items.
47 class SI_API AP_Interface : public UI_Object {
48 public:
49  AP_Interface();
50 
51  /// Construct with given name and predefined value names with corresponding
52  /// interests. The actual values are not created until wireInteface() is
53  /// called. Typically, initApplication() is first called to create the
54  /// the values and then wireInterface() is called afterwards to attach the
55  /// methods to the corresponding values.
56  AP_Interface(const char *myname,
57  const char *const *names,
58  UI_EventMethod const *methods);
59 
60  ~AP_Interface() override;
61 
62  const char *className() const override;
63 
64  /// Return the name passed in the constructor
65  const UT_String &getName() const { return myName; }
66 
67  /// Attach values names to the methods passed in the constructor.
68  /// The actual UI_Value's are typically created by calling
69  /// initApplication() first. If the values do not exist yet, then they are
70  /// automatically created into uims (if not nullptr), else they will
71  /// created in this object.
72  ///
73  /// This method also calls processKeyBindingProxyRequests().
74  void wireInterface(UI_Manager *uims);
75 
76  // Removes interests from all the value names passed in the constructor.
77  void unwireInterface(UI_Manager *uims);
78 
79  /// Turns a .ui file into UI gadgets. If quiet is true, no errors or
80  /// warnings are printed.
81  bool readUIFile(const char *ui_filename,
82  bool quiet = false);
83 
84  /// Create new preference file given its base name using standard rules
85  /// (eg. in $HOME/houdiniX.Y). This may return nullptr if a .nosave file is
86  /// found.
87  static FILE *createPreferenceFile(const char *filename);
88 
89  /// Read the given preference file given its base name using standard
90  /// rules. The values will be initialized according to the parsed file into
91  /// this object.
92  bool readPreferenceFile(const char *pref_filename,
93  bool quiet = false);
94 
95  /// Set the named value symbol to the corresponding pointer. If warn is
96  /// true, then a warning will be issued if the name already exists as an
97  /// object or key delegate symbol, or if the value symbol name already
98  /// previously existed.
99  void setValueSymbol(const char *symbol, UI_Value *value,
100  bool warn = true);
101 
102  /// Find the UI_Value for the given named value symbol
103  UI_Value *findValueSymbol(const char *symbol) const;
104 
105  /// Get the UI_Value for the given named value symbol, creating it if it
106  /// doesn't exist yet. If 'create' is false, then getValueSymbol() is the
107  /// same as findValueSymbol().
108  UI_Value *getValueSymbol(const char *symbol, int create = 1);
109 
110  /// Returns all the Symbol/UI_Value's pairs from the ValueSymbol table
111  /// return array will contain nullptr values if its symbol doesn't exist.
112  int getValueSymbols(UT_StringArray &symbols,
114 
115  /// Set the named object symbol to the corresponding pointer. If warn is
116  /// true, then a warning will be issued if the name already exists as a
117  /// value or key delegate symbol, or if the object symbol name already
118  /// previously existed.
119  void setObjectSymbol(const char *symbol, UI_Object *who,
120  int warn = 1);
121 
122  /// Find the UI_Object for the given object symbol name. Returns nullptr if
123  /// it doesn't exist.
124  UI_Object *getObjectSymbol(const char *symbol) const;
125 
126  /// Find the UI_Feel for the given object symbol name. Returns nullptr if
127  /// it doesn't exist. This is equivalent to findObject<UI_Feel*>(symbol).
128  UI_Feel *getFeelSymbol(const char *symbol) const;
129 
130  /// Find the UI_Feel for the given value pointer. Returns nullptr if
131  /// it doesn't exist.
132  UI_Feel *findValueFeel( UI_Value * value) const;
133 
134  /// Returns all the Symbol/UI_Feel's pairs from the FeelSymbol table
135  /// return array will contain nullptr values if its symbol doesn't exist.
136  int getFeelSymbols(UT_StringArray &symbols,
137  UT_Array<UI_Feel *> &feels) const;
138 
139  /// Set the named key delegate symbol to the corresponding pointer. If warn
140  /// is true, then a warning will be issued if the name already exists as an
141  /// object or value symbol, or if the key delegate symbol name already
142  /// previously existed.
143  void setKeyDelegateSymbol(const char *symbol,
144  UI_KeyDelegateSPtr delegate,
145  bool warn = true);
146 
147  /// Returns whether the current key delegate symbol is defined.
148  bool hasKeyDelegateSymbol(const char *symbol) const;
149 
150  /// Find the UI_KeyDelegate for the given named key delegate symbol.
151  UI_KeyDelegateSPtr findKeyDelegateSymbol(const char *symbol) const;
152 
153  /// Get the UI_KeyDelegate for the given named key delegate symbol,
154  /// creating it if it doesn't exist yet. If 'create' is false, then
155  /// getKeyDelegateSymbol() is the same as findKeyDelegateSymbol().
156  UI_KeyDelegateSPtr getKeyDelegateSymbol(const char *symbol,
157  int create = 1);
158 
159  /// Delete the entry for the given object symbol name
160  void removeObjectSymbol(const char *symbol);
161 
162  /// Delete the entry for the given value symbol name
163  void removeValueSymbol(const char *symbol);
164 
165  /// Find the pointer for the given object symbol name, dynamically casted
166  /// to the given template type.
167  template<typename T>
168  T *findObject(const char *name) const
169  {
170  return dynamic_cast<T *>(getObjectSymbol(name));
171  }
172 
173  /// Find the pointer for the given value symbol name, dynamically casted
174  /// to the given template type.
175  template<typename T>
176  T *findValue(const char *name) const
177  {
178  return dynamic_cast<T *>(findValueSymbol(name));
179  }
180 
181  /// This class maintains a table of requests to assign some feels as
182  /// binding proxies for other feels.
183  ///
184  /// Such requests often originate during the parsing of .ui files that
185  /// occurs in subclass initApplication() overrides. These requests are
186  /// identified by a name, and the order in which the source and references
187  /// are registered does not matter.
188  ///
189  /// The pointers to the feels are only temporarily stored until a call to
190  /// processKeyBindingProxyRequests() occurs. At the moment this occurs as
191  /// part of the wireInterface() method.
192  /// @{
193  void setKeyBindingProxySrc(const char *symbol, UI_Feel *src,
194  bool warn = true);
195  void addKeyBindingProxyRef(const char *symbol, UI_Feel *ref,
196  bool warn = true);
197  /// @}
198 
199  /// Initialize this object. This method is intended to be overriden by
200  /// subclasses since the base class implementation is empty. The subclass
201  /// typically calls readUIFile() here to create the interface which
202  /// populates the object and value symbols.
203  virtual void initApplication(UI_Manager *uims,
204  int argc,
205  const char **argv);
206 
207  // The outputUsage() method should simply output the usage text to
208  // the standard error stream.
209  // The application is terminated after invoking this method.
210  virtual void outputUsage(int argc, const char **argv) const;
211 
212  /// Resets this object by calling unwireInterface() and then destroying all
213  /// objects and values.
214  void resetApplication();
215 
216  void handleEvent(UI_Event *event) override;
217 
218  // These are methods which are called only if the APP is "the"
219  // registered main application in the program. By default, they
220  // do nothing.
221  virtual int saveAppData(const char *filename); // ret 1 on success
222  virtual int loadAppState(); // Allows app to load context
223  virtual int saveAppState(); // Allows app to save context
224  virtual void saveOnCoreDump(); // To do stuff when...yikes!
225  virtual bool getCoreDumpFileName(UT_WorkBuffer &name);
226 
227  // Utility methods for managing the common ui.pref file
228  // Load the UI pref file; should be used by Main.C only.
229  bool loadUIInitPrefs();
230  // Save the current UI state to the pref file. The layout level is
231  // the desired level to be saved.
232  void saveUIInitPrefs(
233  const char * layout_level,
234  fpreal uiscale,
235  int playbarui);
236  // Restore UI prefs from file. Similar to load but does not explicitly
237  // set the layout level, which can only be done by Main.C; so this method
238  // is used everywhere else to load the prefs from file.
239  bool restoreUIInitPrefs();
240 
241  /// Menu items and their mapping for file chooser style preference.
242  static const std::pair<const char *, int> theFileChooserStyleMap[];
243 
244  // Helper methods to convert enums to labels, and vice versa.
245  static int mapStrToInt(const char *label,
246  const std::pair<const char *, int> *map);
247  static const char * mapIntToStr(int index,
248  const std::pair<const char *, int> *map);
249 
250  // If a function key is pressed and a script is attached to it,
251  // this will return the script.
252  //
253  bool getFunctionKeyScript(int key, UI_Event *event,
254  UT_String &script);
255 
256  // These static methods will get/set the exit code that the UI application
257  // will exit with. The default exit code is 0. Note that these methods
258  // are implemented in AP_Main.C.
259  static void setAppExitCode(int exit_code);
260  static int getAppExitCode();
261 
262  /// Returns @c true if the application is exiting.
263  static bool isAppExiting();
264 
265  // Returns the desktop specified by the -desktop argument.
266  // Returns nullptr if no such argument was specified.
267  static const char *getStartupDesktop();
268 
269  // Helper class for being able to call the private installSignalHandlers().
270  class InstallSignalHandlersHelper;
271 
272 protected:
273  static void setTheMainApplication(AP_Interface *app);
274  static AP_Interface *getMainApplication() { return theMainApplication; }
275  static void clearTheMainApplication();
276 
278  const char * const *myValueNames;
280 
281  UI_NamedValueMap *getValueTable() const { return myValueTable; }
282  UI_NamedObjectMap *getObjectTable() const { return myObjectTable; }
283 
284  // Processes any registered binding proxy requests. After this call
285  // the key binding proxy request table will be cleared.
286  void processKeyBindingProxyRequests();
287 
288  // Updates the given UI_Window object using the -geometry or pref file
289  static void loadWindowGeometry(
290  UI_Window *window,
291  bool default_maximized,
292  bool use_pref);
293 
294  // Returns true if the -geometry arg was parsed out and false otherwise.
295  // NOTE: The values are returned in pixels!
296  static bool getWindowGeometry(int &width, int &height,
297  int &left, int &bottom,
298  bool &maximized,
299  bool use_pref);
300  static bool getSaveWindowGeoPref();
301  static void saveWindowGeoPref();
302  static bool loadWindowGeoPref(
303  int &w, int &h, int &left, int &bottom,
304  bool &maximized);
305 
306 private:
307  class si_CrashHandler;
308  friend class si_CrashHandler;
309 
310  // WARNING: The installSignalHandlers() method calls UTgetInterrupt(), so
311  // should not be called before the call to UTsetInterrupt().
312  static void installSignalHandlers();
313  static void getSignalList(UT_Array<int> &signals);
314 
315  void assignUIInitPrefs();
316 
317  static const char *mainApplicationName();
318 
319  static void createCrashLog(UTsignalHandlerArg sig_arg,
320  const char *appname, const char *filename);
321  static void terminateSignalHandler(UTsignalHandlerArg sig_arg);
322  static bool coredumpHandler(UTsignalHandlerArg sig_arg);
323  static void coreDumpChaser(UTsignalHandlerArg sig_arg);
324  static void installCallbacks();
325  static void powerFailHandlerSignalHandler(UTsignalHandlerArg);
326  static void powerFailHandler(
327  UT_String &saved_file_name,
328  const UT_StringRef &details);
329  static void terminationWarning(uint nseconds);
330 
331  static AP_Interface *theMainApplication;
332 
333  class ProxyRequest
334  {
335  public:
336  ProxyRequest() : myTarget(nullptr) {}
337 
338  UI_Feel *myTarget;
339  UT_Array<UI_Feel *> myReferences;
340  };
341  typedef UT_SymbolMap<ProxyRequest> NamedProxyRequestMap;
342 
343 private:
344  UI_NamedValueMap *myValueTable;
345  UI_NamedObjectMap *myObjectTable;
346  UI_NamedKeyDelegateMap *myKeyDelegateTable;
347  NamedProxyRequestMap *myKeyBindingProxyRequestTable;
348 };
349 
350 
351 /// Base class for bootstrapping code for executable applications, with
352 /// the main UI implemented by an AP_Interface.
353 ///
354 /// Instances are created as static objects so that the constructor runs
355 /// during static initialization before the main() function in AP_Main.C.
356 ///
357 /// The createApplication() method will be called on any existing bootstrap
358 /// objects during the execution of main() to allocate an AP_Interface that
359 /// main() will initialize and wire, and finally destroy before terminating.
361 {
362 public:
363  AP_Bootstrap();
364  virtual ~AP_Bootstrap();
365 
366  virtual AP_InterfaceUPtr createApplication() = 0;
367 
368 protected:
369  //
370  // Set the application to run in the fore or background. This MUST
371  // be called from a static constructor (i.e. before main is run).
372  //
373  static void setAppForeground();
374 };
375 
376 
377 // A convenience template for a trivial bootstrapper subclass that creates
378 // an application with a trivial constructor.
379 template <typename APP_T>
381 {
382 public:
384  { return UTmakeUnique<APP_T>(); }
385 };
386 
387 extern void APregister (AP_Interface *app);
388 extern void APderegister(AP_Interface *app);
389 
390 extern void APregister (AP_Bootstrap *bootstrap);
391 extern void APderegister(AP_Bootstrap *bootstrap);
392 
393 // These template functions allow you to get & cast to the appropriate
394 // object/value type in one step, ie:
395 //
396 // UI_Button *button = UIgetObject<UI_Button>(this, "button.gad");
397 // UI_StringList *menu = UIgetValue<UI_StringList>(this, "rmb.menu");
398 
399 template<class ObjectClass> inline
400 ObjectClass *SIgetObject(const AP_Interface *app, const char *name)
401 {
402  return dynamic_cast<ObjectClass *>(app->getObjectSymbol(name));
403 }
404 
405 template<class ValueClass> inline
406 ValueClass *SIgetValue(const AP_Interface *app, const char *name)
407 {
408  return dynamic_cast<ValueClass *>(app->findValueSymbol(name));
409 }
410 
411 #endif
ValueClass * SIgetValue(const AP_Interface *app, const char *name)
Definition: AP_Interface.h:406
GT_API const UT_StringHolder filename
GLuint GLsizei const GLchar * label
Definition: glcorearb.h:2545
T * findValue(const char *name) const
Definition: AP_Interface.h:176
#define SI_API
Definition: SI_API.h:10
GLint left
Definition: glcorearb.h:2005
AP_InterfaceUPtr createApplication() override
Definition: AP_Interface.h:383
void APregister(AP_Interface *app)
UT_SymbolMap< UI_Value * > UI_NamedValueMap
Definition: AP_Interface.h:39
std::unique_ptr< T, Deleter > UT_UniquePtr
A smart pointer for unique ownership of dynamically allocated objects.
Definition: UT_UniquePtr.h:39
struct _cl_event * event
Definition: glcorearb.h:2961
virtual void handleEvent(UI_Event *event)
GLint GLsizei GLsizei height
Definition: glcorearb.h:103
GLint ref
Definition: glcorearb.h:124
std::shared_ptr< T > UT_SharedPtr
Wrapper around std::shared_ptr.
Definition: UT_SharedPtr.h:36
const UT_String & getName() const
Return the name passed in the constructor.
Definition: AP_Interface.h:65
UT_UniquePtr< AP_Interface > AP_InterfaceUPtr
Definition: AP_Interface.h:38
static AP_Interface * getMainApplication()
Definition: AP_Interface.h:274
const char *const * myValueNames
Definition: AP_Interface.h:278
Definition: UT_Url.h:22
UI_EventMethod const * myMethods
Definition: AP_Interface.h:279
GLuint const GLchar * name
Definition: glcorearb.h:786
GLint GLint bottom
Definition: glcorearb.h:2005
UT_SymbolMap< UI_Object * > UI_NamedObjectMap
Definition: AP_Interface.h:41
UI_NamedObjectMap * getObjectTable() const
Definition: AP_Interface.h:282
UI_Object * getObjectSymbol(const char *symbol) const
GLfloat GLfloat GLfloat GLfloat h
Definition: glcorearb.h:2002
GLenum GLsizei GLsizei GLint * values
Definition: glcorearb.h:1602
fpreal64 fpreal
Definition: SYS_Types.h:277
T * findObject(const char *name) const
Definition: AP_Interface.h:168
GLuint index
Definition: glcorearb.h:786
void(UI_Object::* UI_EventMethod)(UI_Event *)
Definition: UI_Object.h:36
virtual const char * className() const
Definition: UI_Object.h:87
GLint GLsizei width
Definition: glcorearb.h:103
UT_String myName
Definition: AP_Interface.h:277
GLubyte GLubyte GLubyte GLubyte w
Definition: glcorearb.h:857
Definition: core.h:1131
UI_Value * findValueSymbol(const char *symbol) const
Find the UI_Value for the given named value symbol.
UT_SymbolMap< UI_KeyDelegateSPtr > UI_NamedKeyDelegateMap
Definition: AP_Interface.h:42
unsigned int uint
Definition: SYS_Types.h:45
void APderegister(AP_Interface *app)
UI_NamedValueMap * getValueTable() const
Definition: AP_Interface.h:281
GLenum src
Definition: glcorearb.h:1793
UT_SharedPtr< UI_KeyDelegate > UI_KeyDelegateSPtr
Definition: AP_Interface.h:37
ObjectClass * SIgetObject(const AP_Interface *app, const char *name)
Definition: AP_Interface.h:400