HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Pages
UT_HelpManager.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_HelpManager.h
7  *
8  * COMMENTS:
9  * This class allows any code in Houdini to load a help file or display
10  * arbitrary text in a help pane.
11  *
12  * Note that UTgetHelpManager() will return null in applications that
13  * don't support help panes.
14  */
15 
16 #ifndef __UT_HelpManager_h__
17 #define __UT_HelpManager_h__
18 
19 #include "UT_API.h"
20 #include <SYS/SYS_Types.h>
21 #include "UT_Assert.h"
22 
23 class UT_String;
24 class OP_Operator;
25 class OP_Node;
26 class OP_GalleryEntry;
27 class BM_State;
28 class SHLF_Tool;
29 class PRM_Parm;
30 class PRM_ScriptParm;
31 class PYP_Interface;
32 
33 // The help URL protocols used by the help system.
34 #define UT_OP_PROTOCOL_PREFIX "operator:"
35 #define UT_PROP_PROTOCOL_PREFIX "prop:"
36 #define UT_GALLERY_PROTOCOL_PREFIX "gallery:"
37 #define UT_PARM_PROTOCOL_PREFIX "parm:"
38 
39 
41 {
42 public:
44  virtual ~UT_HelpManager();
45 
46  // openContents() will display the help contents page.
47  virtual void openContents() = 0;
48 
49  // openStartup() brings up the special welcome/essential skills page
50  // of help upon startup:
51  virtual void openStartup() = 0;
52 
53  // openFile() and displayData() are the main methods of the help manager
54  // to display help. They will ensure a help browser pane exists and
55  // they will open a text/html file or display text/html data. Note
56  // that both of these methods call clearDesiredHelpLocation() when
57  // they finish. setBaseURI() will set the URI used to resolve links
58  // to other files when html data is passed in with displayData().
59  virtual void openFile(const char *path) = 0;
60  virtual void openURL(const char *url) = 0;
61  virtual void openHelpPath(const char *help_path) = 0;
62  virtual void displayData(const char *data, bool is_html) = 0;
63 
64  /// Obtains a tool tip from the help page pointed to by the URL.
65  virtual bool getTooltip( const char * url, UT_String & tooltip ) =0;
66 
67  /// Obtains a tool tip for the specified parameter.
68  virtual bool getTooltip(
69  const PRM_Parm *parm, UT_String &tooltip)
70  = 0;
71 
72  /// Obtains a tool tip conained by the full help text. The url serves
73  /// as a caching key.
74  virtual bool getParsedTooltip( const char * url_key,
75  const char * full_help,
76  UT_String & tooltip) = 0;
77 
78  // These methods help pop up a helpcard for a specific operator,
79  // state, or tool. The help text associated with the entity can come
80  // from the central help server, or if no such help exists from the
81  // URL provided by the entity or from the text internally defined by the op
82  // (HDA/HDK) or the tool, or from a file on disk associated with the
83  // operator or state.
84  virtual void openHelpCard( OP_Node * node ) = 0;
85  virtual void openHelpCard(
86  OP_Operator * op, const char *node_path=nullptr ) = 0;
87  virtual void openHelpCard( BM_State * state ) = 0;
88  virtual void openHelpCard( SHLF_Tool * tool ) = 0;
89  virtual void openHelpCard( const PYP_Interface * interface ) = 0;
90  virtual void openHelpCard( OP_GalleryEntry * entry ) = 0;
91  virtual void openHelpCard( const PRM_ScriptParm * prop ) = 0;
92 
93  // Obtains a URL that points to the help server web page for the given
94  // operator, state, tool, or topic id.
95  virtual void getHelpCardURL( OP_Operator * op, UT_String & str ) =0;
96  virtual void getHelpCardURL( BM_State * state, UT_String & url ) =0;
97  virtual void getHelpCardURL( SHLF_Tool * tool, UT_String & url ) =0;
98  virtual void getHelpCardURL( const PYP_Interface * interface,
99  UT_String & url ) = 0;
100  virtual void getHelpCardURL( OP_GalleryEntry * entry,
101  UT_String & url ) = 0;
102  virtual void getHelpCardURL( const PRM_ScriptParm * prop,
103  UT_String & url ) = 0;
104  virtual void getHelpCardURL( const char *helpTopicId,
105  UT_String & url ) = 0;
106  virtual void getHelpCardURL( const PRM_Parm * parm,
107  UT_String &url) = 0;
108 
109  virtual void setBaseURI(const char *base_uri) = 0;
110  virtual const UT_String &getBaseURI() const = 0;
111 
112  // Returns true if the help manager is using an external help server.
113  // Returns false otherwise.
114  virtual bool getUseExternalHelp() const = 0;
115 
116  // Sets whether the help manager should use an external help server or not.
117  virtual void setUseExternalHelp(bool use_external) = 0;
118 
119  // Returns the base url for the external help server.
120  // Returns "" if no external help server is used.
121  virtual const UT_String &getExternalHelpURL() const = 0;
122 
123  // Sets the url to the external help server.
124  virtual void setExternalHelpURL(const char *ext_help_url) = 0;
125 
126  // Returns the base URL for all of Houdini's help.
127  virtual const UT_String &getHelpBaseURL() = 0;
128 
129  // Returns the url for the help startup page.
130  virtual const UT_String &getStartupURL() = 0;
131 
132  // By setting the desired help location, any calls to openFile() or
133  // displayData() that need to create a floating pane will create it
134  // near the specified location. Typically, the location is the mouse
135  // location when the help button was pressed. Call
136  // clearDesiredHelpLocation() after the call to openFile() or displayData().
137  void setDesiredHelpLocation(fpreal x, fpreal y);
138  void clearDesiredHelpLocation();
139 
140  // When the help is displayed in a floating pane, the floating pane gets
141  // a unique id. When there is no floating help pane, the floating help
142  // pane id is 0. This help pane id lets the op help buttons decide
143  // whether to display the help for an op or close the floating help pane.
144  void setFloatingHelpPaneId(int pane_id)
145  { myFloatingHelpPaneId = pane_id; }
147  { return myFloatingHelpPaneId; }
148  virtual void closeFloatingPane() = 0;
149 
150  // Does this platform support html help? This method is static so it
151  // can be called from a non-graphical program, since UTsetHelpManager()
152  // may not have been called.
153  static bool platformSupportsHtmlHelp();
154 
155  /// Concatenates the operator table name, operator type name, some
156  /// extra information into a help URL.
157  static void constructOpBasedURL( const char *protocol,
158  const char *optable, const char *optype,
159  const char *extra, UT_String &url);
160 
161  /// Parses the help URL into the operator table name, operator type name,
162  /// extra info string, given the url and the required protocol prefix.
163  /// Returns true on success, and false otherwise.
164  static bool parseOpBasedURL( const char * url,
165  const char *protocol,
166  UT_String &optable, UT_String &optype,
167  UT_String &extra );
168 
169  // These methods are used by UTgetHelpManager() and UTsetHelpManager().
170  // You should never have to call them directly.
171  static UT_HelpManager *getHelpManager() { return ourHelpManager; }
172  static void setHelpManager(UT_HelpManager *help_manager);
173 
174 protected:
175  // This method is used by subclasses to determine if and where to position
176  // the help location.
177  bool getDesiredHelpLocation(float &x, float &y);
178 
179 private:
180  static UT_HelpManager *ourHelpManager;
181 
182  float myDesiredHelpLocationX;
183  float myDesiredHelpLocationY;
184  int myFloatingHelpPaneId;
185 };
186 
187 static inline UT_HelpManager *UTgetHelpManager()
188 { return UT_HelpManager::getHelpManager(); }
189 
190 static inline void UTsetHelpManager(UT_HelpManager *help_manager)
191 { UT_HelpManager::setHelpManager(help_manager); }
192 
193 #endif
GLsizei const GLchar *const * path
Definition: glcorearb.h:3340
void setFloatingHelpPaneId(int pane_id)
#define UT_API
Definition: UT_API.h:12
GLint y
Definition: glcorearb.h:102
static UT_HelpManager * getHelpManager()
GLboolean * data
Definition: glcorearb.h:130
double fpreal
Definition: SYS_Types.h:263
GLint GLenum GLint x
Definition: glcorearb.h:408
int getFloatingHelpPaneId() const
static void setHelpManager(UT_HelpManager *help_manager)