HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups 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 "UT_Assert.h"
21 #include "UT_NonCopyable.h"
22 #include "UT_StringArray.h"
23 #include "UT_StringHolder.h"
24 #include <SYS/SYS_Types.h>
25 
26 class UT_String;
27 class OP_Operator;
28 class OP_Node;
29 class OP_GalleryEntry;
30 class BM_State;
31 class SHLF_Tool;
32 class PRM_Parm;
33 class PRM_ScriptParm;
34 class PYP_Interface;
35 
36 // The help URL protocols used by the help system.
37 #define UT_OP_PROTOCOL_PREFIX "operator:"
38 #define UT_PROP_PROTOCOL_PREFIX "prop:"
39 #define UT_GALLERY_PROTOCOL_PREFIX "gallery:"
40 #define UT_PARM_PROTOCOL_PREFIX "parm:"
41 #define UT_DOC_PROTOCOL_PREFIX "doc:"
42 
43 
45 {
46 public:
48  virtual ~UT_HelpManager();
49 
51 
52  // openContents() will display the help contents page.
53  virtual void openContents() = 0;
54 
55  // openStartup() brings up the special welcome/essential skills page
56  // of help upon startup:
57  virtual void openStartup() = 0;
58 
59  // openFile() and displayData() are the main methods of the help manager
60  // to display help. They will ensure a help browser pane exists and
61  // they will open a text/html file or display text/html data. Note
62  // that both of these methods call clearDesiredHelpLocation() when
63  // they finish. setBaseURI() will set the URI used to resolve links
64  // to other files when html data is passed in with displayData().
65  virtual void openFile(const char *path) = 0;
66  virtual void openURL(const char *url) = 0;
67  virtual void openHelpPath(const char *help_path) = 0;
68  virtual void displayData(const char *data, bool is_html) = 0;
69 
70  /// Obtains a tool tip from the help page pointed to by the URL.
71  virtual bool getTooltip( const char * url, UT_String & tooltip ) =0;
72 
73  /// Obtains a tool tip for the specified parameter.
74  virtual bool getTooltip(
75  const PRM_Parm *parm, UT_String &tooltip)
76  = 0;
77 
78  /// Open the requested tooltip in a popup window.
79  /// x,y,w,h represents the native screen position and size of the
80  /// source feel that the tooltip is for. If there is no source feel,
81  /// then pass in (0,0,0,0) for x,y,w,h.
82  /// {
83  virtual void openTooltipWindow(
84  const char *text,
85  int x, int y, int w, int h) const = 0;
86  virtual void openTooltipURLWindow(
87  const char *url,
88  int x, int y, int w, int h) const = 0;
89  /// }
90 
91  /// Close all tooltip popup windows.
92  /// Do nothing if there are no open tooltip popup windows.
93  virtual void closeAllTooltipWindows() const = 0;
94 
95  /// Obtains a plain text version of the help page pointed to by the URL
96  /// (e.g. 'vex:attrib').
97  virtual bool getTextHelp(const char *url, UT_String &text_help) = 0;
98 
99  /// Return the text help for the given hscript command.
100  virtual UT_StringHolder getCommandHelp(const char *command) = 0;
101 
102  /// Return the text help for the given hscript expression command.
103  virtual UT_StringHolder getExprCommandHelp(const char *command) = 0;
104 
105  /// Return an array of hscript commands whose text help contain
106  /// a match for the given keyword.
107  virtual UT_StringArray getCommandsForHelpKeyword(const char *keyword) = 0;
108 
109  /// Return an array of hscript expression commands whose text help
110  /// conotain a match for the given keyword.
111  virtual UT_StringArray getExprCommandsForHelpKeyword(
112  const char *keyword) = 0;
113 
114  /// Obtains a tool tip conained by the full help text. The url serves
115  /// as a caching key.
116  virtual bool getParsedTooltip( const char * url_key,
117  const char * full_help,
118  UT_String & tooltip) = 0;
119 
120  // These methods help pop up a helpcard for a specific operator,
121  // state, or tool. The help text associated with the entity can come
122  // from the central help server, or if no such help exists from the
123  // URL provided by the entity or from the text internally defined by the op
124  // (HDA/HDK) or the tool, or from a file on disk associated with the
125  // operator or state.
126  virtual void openHelpCard( OP_Node * node ) = 0;
127  virtual void openHelpCard(
128  OP_Operator * op, const char *node_path=nullptr ) = 0;
129  virtual void openHelpCard( BM_State * state ) = 0;
130  virtual void openHelpCard( SHLF_Tool * tool ) = 0;
131  virtual void openHelpCard( const PYP_Interface * interface ) = 0;
132  virtual void openHelpCard( OP_GalleryEntry * entry ) = 0;
133  virtual void openHelpCard( const PRM_ScriptParm * prop ) = 0;
134 
135  // Obtains a URL that points to the help server web page for the given
136  // operator, state, tool, or topic id.
137  virtual void getHelpCardURL( OP_Operator * op, UT_String & str ) =0;
138  virtual void getHelpCardURL( BM_State * state, UT_String & url ) =0;
139  virtual void getHelpCardURL( SHLF_Tool * tool, UT_String & url ) =0;
140  virtual void getHelpCardURL( const PYP_Interface * interface,
141  UT_String & url ) = 0;
142  virtual void getHelpCardURL( OP_GalleryEntry * entry,
143  UT_String & url ) = 0;
144  virtual void getHelpCardURL( const PRM_ScriptParm * prop,
145  UT_String & url ) = 0;
146  virtual void getHelpCardURL( const char *helpTopicId,
147  UT_String & url ) = 0;
148  virtual void getHelpCardURL( const PRM_Parm * parm,
149  UT_String &url) = 0;
150 
151  virtual void setBaseURI(const char *base_uri) = 0;
152  virtual const UT_String &getBaseURI() const = 0;
153 
154  // Returns true if the help manager is using an external help server.
155  // Returns false otherwise.
156  virtual bool getUseExternalHelp() const = 0;
157 
158  // Sets whether the help manager should use an external help server or not.
159  virtual void setUseExternalHelp(bool use_external) = 0;
160 
161  /// Sets the address the server should bind to.
162  virtual void setHelpAddress(const char* address) = 0;
163  virtual const UT_StringHolder& getHelpAddress() const = 0;
164 
165  /// Whether the help server should use ipv6 or not.
166  virtual void setUseIPv6(bool use_ipv6) = 0;
167  virtual bool getUseIPv6() const = 0;
168 
169  // Returns the base url for the external help server.
170  // Returns "" if no external help server is used.
171  virtual const UT_String &getExternalHelpURL() const = 0;
172 
173  // Sets the url to the external help server.
174  virtual void setExternalHelpURL(const char *ext_help_url) = 0;
175 
176  // Returns the base URL for all of Houdini's help.
177  virtual const UT_String &getHelpBaseURL() = 0;
178 
179  // Returns the url for the help startup page.
180  virtual const UT_String &getStartupURL() = 0;
181 
182  // By setting the desired help location, any calls to openFile() or
183  // displayData() that need to create a floating pane will create it
184  // near the specified location. Typically, the location is the mouse
185  // location when the help button was pressed. Call
186  // clearDesiredHelpLocation() after the call to openFile() or displayData().
187  void setDesiredHelpLocation(fpreal x, fpreal y);
188  void clearDesiredHelpLocation();
189 
190  // When the help is displayed in a floating pane, the floating pane gets
191  // a unique id. When there is no floating help pane, the floating help
192  // pane id is 0. This help pane id lets the op help buttons decide
193  // whether to display the help for an op or close the floating help pane.
194  void setFloatingHelpPaneId(int pane_id)
195  { myFloatingHelpPaneId = pane_id; }
197  { return myFloatingHelpPaneId; }
198  virtual void closeFloatingPane() = 0;
199 
200  // Does this platform support html help? This method is static so it
201  // can be called from a non-graphical program, since UTsetHelpManager()
202  // may not have been called.
203  static bool platformSupportsHtmlHelp();
204 
205  /// Concatenates the operator table name, operator type name, some
206  /// extra information into a help URL.
207  static void constructOpBasedURL( const char *protocol,
208  const char *optable, const char *optype,
209  const char *extra, UT_String &url);
210 
211  /// Parses the help URL into the operator table name, operator type name,
212  /// extra info string, given the url and the required protocol prefix.
213  /// Returns true on success, and false otherwise.
214  static bool parseOpBasedURL( const char * url,
215  const char *protocol,
216  UT_String &optable, UT_String &optype,
217  UT_String &extra );
218 
219  // These methods are used by UTgetHelpManager() and UTsetHelpManager().
220  // You should never have to call them directly.
221  static UT_HelpManager *getHelpManager() { return ourHelpManager; }
222  static void setHelpManager(UT_HelpManager *help_manager);
223 
224 protected:
225  // This method is used by subclasses to determine if and where to position
226  // the help location.
227  bool getDesiredHelpLocation(float &x, float &y);
228 
229 private:
230  static UT_HelpManager *ourHelpManager;
231 
232  float myDesiredHelpLocationX;
233  float myDesiredHelpLocationY;
234  int myFloatingHelpPaneId;
235 };
236 
237 static inline UT_HelpManager *UTgetHelpManager()
238 { return UT_HelpManager::getHelpManager(); }
239 
240 static inline void UTsetHelpManager(UT_HelpManager *help_manager)
241 { UT_HelpManager::setHelpManager(help_manager); }
242 
243 #endif
GLsizei const GLchar *const * path
Definition: glcorearb.h:3341
void setFloatingHelpPaneId(int pane_id)
#define UT_API
Definition: UT_API.h:14
GLint y
Definition: glcorearb.h:103
static UT_HelpManager * getHelpManager()
#define UT_NON_COPYABLE(CLASS)
Define deleted copy constructor and assignment operator inside a class.
GLint GLenum GLint x
Definition: glcorearb.h:409
GLfloat GLfloat GLfloat GLfloat h
Definition: glcorearb.h:2002
fpreal64 fpreal
Definition: SYS_Types.h:278
GLubyte GLubyte GLubyte GLubyte w
Definition: glcorearb.h:857
int getFloatingHelpPaneId() const
state
Definition: core.h:2289
static void setHelpManager(UT_HelpManager *help_manager)
Definition: format.h:1821