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  /// Obtains a plain text version of the help page pointed to by the URL
79  /// (e.g. 'vex:attrib').
80  virtual bool getTextHelp(const char *url, UT_String &text_help) = 0;
81 
82  /// Return the text help for the given hscript command.
83  virtual UT_StringHolder getCommandHelp(const char *command) = 0;
84 
85  /// Return the text help for the given hscript expression command.
86  virtual UT_StringHolder getExprCommandHelp(const char *command) = 0;
87 
88  /// Return an array of hscript commands whose text help contain
89  /// a match for the given keyword.
90  virtual UT_StringArray getCommandsForHelpKeyword(const char *keyword) = 0;
91 
92  /// Return an array of hscript expression commands whose text help
93  /// conotain a match for the given keyword.
94  virtual UT_StringArray getExprCommandsForHelpKeyword(
95  const char *keyword) = 0;
96 
97  /// Obtains a tool tip conained by the full help text. The url serves
98  /// as a caching key.
99  virtual bool getParsedTooltip( const char * url_key,
100  const char * full_help,
101  UT_String & tooltip) = 0;
102 
103  // These methods help pop up a helpcard for a specific operator,
104  // state, or tool. The help text associated with the entity can come
105  // from the central help server, or if no such help exists from the
106  // URL provided by the entity or from the text internally defined by the op
107  // (HDA/HDK) or the tool, or from a file on disk associated with the
108  // operator or state.
109  virtual void openHelpCard( OP_Node * node ) = 0;
110  virtual void openHelpCard(
111  OP_Operator * op, const char *node_path=nullptr ) = 0;
112  virtual void openHelpCard( BM_State * state ) = 0;
113  virtual void openHelpCard( SHLF_Tool * tool ) = 0;
114  virtual void openHelpCard( const PYP_Interface * interface ) = 0;
115  virtual void openHelpCard( OP_GalleryEntry * entry ) = 0;
116  virtual void openHelpCard( const PRM_ScriptParm * prop ) = 0;
117 
118  // Obtains a URL that points to the help server web page for the given
119  // operator, state, tool, or topic id.
120  virtual void getHelpCardURL( OP_Operator * op, UT_String & str ) =0;
121  virtual void getHelpCardURL( BM_State * state, UT_String & url ) =0;
122  virtual void getHelpCardURL( SHLF_Tool * tool, UT_String & url ) =0;
123  virtual void getHelpCardURL( const PYP_Interface * interface,
124  UT_String & url ) = 0;
125  virtual void getHelpCardURL( OP_GalleryEntry * entry,
126  UT_String & url ) = 0;
127  virtual void getHelpCardURL( const PRM_ScriptParm * prop,
128  UT_String & url ) = 0;
129  virtual void getHelpCardURL( const char *helpTopicId,
130  UT_String & url ) = 0;
131  virtual void getHelpCardURL( const PRM_Parm * parm,
132  UT_String &url) = 0;
133 
134  virtual void setBaseURI(const char *base_uri) = 0;
135  virtual const UT_String &getBaseURI() const = 0;
136 
137  // Returns true if the help manager is using an external help server.
138  // Returns false otherwise.
139  virtual bool getUseExternalHelp() const = 0;
140 
141  // Sets whether the help manager should use an external help server or not.
142  virtual void setUseExternalHelp(bool use_external) = 0;
143 
144  /// Sets the address the server should bind to.
145  virtual void setHelpAddress(const char* address) = 0;
146  virtual const UT_StringHolder& getHelpAddress() const = 0;
147 
148  /// Whether the help server should use ipv6 or not.
149  virtual void setUseIPv6(bool use_ipv6) = 0;
150  virtual bool getUseIPv6() const = 0;
151 
152  // Returns the base url for the external help server.
153  // Returns "" if no external help server is used.
154  virtual const UT_String &getExternalHelpURL() const = 0;
155 
156  // Sets the url to the external help server.
157  virtual void setExternalHelpURL(const char *ext_help_url) = 0;
158 
159  // Returns the base URL for all of Houdini's help.
160  virtual const UT_String &getHelpBaseURL() = 0;
161 
162  // Returns the url for the help startup page.
163  virtual const UT_String &getStartupURL() = 0;
164 
165  // By setting the desired help location, any calls to openFile() or
166  // displayData() that need to create a floating pane will create it
167  // near the specified location. Typically, the location is the mouse
168  // location when the help button was pressed. Call
169  // clearDesiredHelpLocation() after the call to openFile() or displayData().
170  void setDesiredHelpLocation(fpreal x, fpreal y);
171  void clearDesiredHelpLocation();
172 
173  // When the help is displayed in a floating pane, the floating pane gets
174  // a unique id. When there is no floating help pane, the floating help
175  // pane id is 0. This help pane id lets the op help buttons decide
176  // whether to display the help for an op or close the floating help pane.
177  void setFloatingHelpPaneId(int pane_id)
178  { myFloatingHelpPaneId = pane_id; }
180  { return myFloatingHelpPaneId; }
181  virtual void closeFloatingPane() = 0;
182 
183  // Does this platform support html help? This method is static so it
184  // can be called from a non-graphical program, since UTsetHelpManager()
185  // may not have been called.
186  static bool platformSupportsHtmlHelp();
187 
188  /// Concatenates the operator table name, operator type name, some
189  /// extra information into a help URL.
190  static void constructOpBasedURL( const char *protocol,
191  const char *optable, const char *optype,
192  const char *extra, UT_String &url);
193 
194  /// Parses the help URL into the operator table name, operator type name,
195  /// extra info string, given the url and the required protocol prefix.
196  /// Returns true on success, and false otherwise.
197  static bool parseOpBasedURL( const char * url,
198  const char *protocol,
199  UT_String &optable, UT_String &optype,
200  UT_String &extra );
201 
202  // These methods are used by UTgetHelpManager() and UTsetHelpManager().
203  // You should never have to call them directly.
204  static UT_HelpManager *getHelpManager() { return ourHelpManager; }
205  static void setHelpManager(UT_HelpManager *help_manager);
206 
207 protected:
208  // This method is used by subclasses to determine if and where to position
209  // the help location.
210  bool getDesiredHelpLocation(float &x, float &y);
211 
212 private:
213  static UT_HelpManager *ourHelpManager;
214 
215  float myDesiredHelpLocationX;
216  float myDesiredHelpLocationY;
217  int myFloatingHelpPaneId;
218 };
219 
220 static inline UT_HelpManager *UTgetHelpManager()
221 { return UT_HelpManager::getHelpManager(); }
222 
223 static inline void UTsetHelpManager(UT_HelpManager *help_manager)
224 { UT_HelpManager::setHelpManager(help_manager); }
225 
226 #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
fpreal64 fpreal
Definition: SYS_Types.h:277
int getFloatingHelpPaneId() const
static void setHelpManager(UT_HelpManager *help_manager)
Definition: format.h:895