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