HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
MOT_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: MOT_HelpManager.h ( BR Library, C++)
7  *
8  * COMMENTS:
9  */
10 
11 #ifndef __MOT_HelpManager__
12 #define __MOT_HelpManager__
13 
14 #include "MOT_API.h"
15 #include <UT/UT_HelpManager.h>
16 #include <UT/UT_StringArray.h>
17 #include <PY/PY_Result.h>
18 
20 class UT_Signal;
21 class OP_Node;
22 class PRM_Parm;
23 
25 {
26 public:
28  ~MOT_HelpManager() override;
29 
30  /// Opens the table of contenst help page.
31  virtual void openContents() override;
32 
33  /// Opens the special essential-skills page on startup.
34  virtual void openStartup() override;
35 
36  /// Opens a help page defined by the file.
37  virtual void openFile(const char *path) override;
38 
39  /// Opens a URL in the help browser (url can be of forms
40  /// "http://u.r.l", "hdox://u.r.l", "operator:table/name", "tool:name" etc)
41  virtual void openURL(const char *url) override;
42 
43  virtual void openHelpPath(const char *help_path) override;
44 
45  /// Displays the buffer data in help browser.
46  virtual void displayData(const char *data,
47  bool is_html) override;
48 
49  /// Obtains a tool tip from the help page pointed to by the URL.
50  bool getTooltip(const char *url,
51  UT_String &tooltip) override;
52 
53  /// Obtains a tool tip for the specified parameter.
54  bool getTooltip(const PRM_Parm *parm,
55  UT_String &tooltip) override;
56 
57  /// Obtains a tool tip conained by the full help text. The url serves
58  /// as a caching key.
59  bool getParsedTooltip(const char *url_key,
60  const char *full_help,
61  UT_String &tooltip) override;
62 
63  /// Obtains a plain text version of the help page pointed to by the URL
64  /// (e.g. 'vex:attrib').
65  bool getTextHelp(const char *url,
66  UT_String &text_help) override;
67 
68  /// Return the text help for the given hscript command.
69  UT_StringHolder getCommandHelp(const char *command) override;
70 
71  /// Return the text help for the given hscript expression command.
72  UT_StringHolder getExprCommandHelp(const char *command) override;
73 
74  /// Return an array of hscript commands whose text help contain
75  /// a match for the given keyword.
76  UT_StringArray getCommandsForHelpKeyword(const char *keyword) override;
77 
78  /// Return an array of hscript expression commands whose text help
79  /// conotain a match for the given keyword.
80  UT_StringArray getExprCommandsForHelpKeyword(const char *keyword) override;
81 
82  // Convenience functions for opening the help cards for operators,
83  // nodes, shelf tools, states, etc.
84  virtual void openHelpCard(OP_Node *node) override;
85  virtual void openHelpCard(
86  OP_Operator *op,
87  const char *node_path=nullptr) override;
88  virtual void openHelpCard(BM_State *state) override;
89  virtual void openHelpCard(SHLF_Tool *tool) override;
90  virtual void openHelpCard(
91  const PYP_Interface *interface) override;
92  virtual void openHelpCard(OP_GalleryEntry *entry)
93  override;
94  virtual void openHelpCard(
95  const PRM_ScriptParm *prop) override;
96 
97  // Obtains a URL that points to the help server web page for the given
98  // operator, state, tool, or topic id.
99  void getHelpCardURL(OP_Operator *op,
100  UT_String &str) override;
101  void getHelpCardURL(BM_State *state,
102  UT_String &url) override;
103  void getHelpCardURL(SHLF_Tool *tool,
104  UT_String &url) override;
105  void getHelpCardURL(const PYP_Interface *interface,
106  UT_String &url) override;
107  void getHelpCardURL(OP_GalleryEntry *entry,
108  UT_String &url) override;
109  void getHelpCardURL(const PRM_ScriptParm *prop,
110  UT_String &url) override;
111  void getHelpCardURL(const char *helpTopicId,
112  UT_String &url) override;
113  void getHelpCardURL(const PRM_Parm* parm,
114  UT_String &help_path) override;
115 
116  /// Sets the base URI that is used to disambiguate the relative URLs.
117  void setBaseURI(const char *base_uri) override;
118 
119  /// Returns the baseURI.
120  const UT_String &getBaseURI() const override
121  { return myBaseURI; }
122 
123  /// Returns true if the help manager is using an external help server.
124  /// Returns false otherwise.
125  bool getUseExternalHelp() const override
126  { return myUseExternalHelp; }
127 
128  /// Sets whether the help manager should use an external help server or not.
129  void setUseExternalHelp(bool use_external) override;
130 
131  /// Sets the address the help server should bind to.
132  void setHelpAddress(const char* help_address) override;
133  const UT_StringHolder &getHelpAddress() const override
134  { return myHelpAddress; }
135 
136  /// Sets if the help server can use ipv6
137  void setUseIPv6(bool use_ipv6) override;
138  bool getUseIPv6() const override
139  { return myUseIPv6; }
140 
141  /// Returns the base url for the external help server.
142  /// Returns "" if no external help server is used.
143  const UT_String &getExternalHelpURL() const override
144  { return myExternalHelpURL; };
145 
146  /// Sets the url to the external help server.
147  void setExternalHelpURL(
148  const char *ext_help_url) override;
149 
150  /// Returns the base URL for all of Houdini's help.
151  const UT_String &getHelpBaseURL() override;
152 
153  /// Returns the url for the help startup page.
154  const UT_String &getStartupURL() override;
155 
156  /// Closes the help pane.
157  virtual void closeFloatingPane() override;
158 
159 protected:
160  /// Helper function for getTooltip(const char *, UT_String&).
161  /// Attempts to extract an operator, gallery entry or parameter
162  /// tooltip from the given url.
163  virtual bool extractTooltip(const char *url,
164  UT_String &tooltip);
165 
166  /// Updates all opened web browsers with the current
167  /// help base URL.
168  virtual void updateBaseURLInHelpBrowsersSubclass();
169 
170  /// Count help cards opening times for FS_datalogger.
171  void countHelpCardPress(const char *message);
172 
173  /// Checks whether the help server has the help page under the given URL.
174  bool getServerHasHelp(const char *url);
175 
176  UT_StringArray &getURLStack() { return myURLStack; }
177 
178  /// Prefixes `help_path` with the help server's base url and
179  /// passes back the final url in `url`.
180  void prefixWithHelpBaseURL(const char *help_path,
181  UT_String &url);
182 
183  /// Parses URL and tries to obtain the entity.
184  OP_Operator *getOpFromURL(const char *url);
185  OP_GalleryEntry *getGalleryEntryFromURL(const char *url);
186  const PRM_ScriptParm *getPropFromURL(const char *url);
187 
188  /// Resolve specified help path by expanding variables and translating
189  /// help protocols to help paths.
190  void resolveHelpPath(
191  const char *help_path,
192  UT_String &resolved_path);
193 
194 private:
195 
196  /// Parses the wiki text into an html text.
197  /// NB: the url is needed for caching key by the help server.
198  virtual void parseWikiToHtml(const char *url_key,
199  const char *wiki_help,
200  UT_String & html_help);
201 
202  /// Helper methods to obtain tool tip from the operator or tool.
203  bool getTooltip(OP_Operator *op,
204  UT_String &tooltip);
205  bool getTooltip(OP_GalleryEntry *entry,
206  UT_String &tooltip);
207  bool getTooltip(const PRM_ScriptParm *prop,
208  UT_String &tooltip);
209 
210  /// Helper for running python code (eg evaluating expression and obtaining
211  /// the result of that expression) within the help python context.
212  /// Returns true evaluation went ok, or false if error occured or the
213  /// returned value type does not match the desired type.
214  // NB: the expression can be only a single python statement; no multiline
215  // scripts are allowed (for now at least).
216  bool runPythonExpr(const char *expr,
217  PY_Result::Type desired_result_type,
218  PY_Result &py_result,
219  PY_EvaluationContext *context=nullptr);
220  bool evalPythonExpr(const char *expr,
221  UT_String &result);
222  bool evalPythonExpr(const char *expr,
224  bool evalPythonExpr(const char *expr, int &result);
225  bool evalPythonExpr(const char *expr,
227 
228  /// Initialize the help server using the houdinihelp Python module.
229  bool initializeHelpServer();
230 
231  /// Initialize the help server if we haven't already tried to / do so, and
232  //return whether or not it could be initialized.
233  bool canAccessHelpServer();
234 
235  /// Returns the listen port of the help server.
236  /// Starts the help server if necessary.
237  int getHelpServerPort();
238 
239  bool myCouldInitializeHelpServer;
240  UT_StringArray myURLStack; // followed url links
241  UT_String myBaseURI; // base URI for relative
242  bool myUseExternalHelp;
243  UT_String myExternalHelpURL;
244  UT_String myHelpBaseURL; // html links
245  UT_String myStartupHelpURL;
246 
247  UT_StringHolder myHelpAddress;
248  bool myUseIPv6;
249 
250  /// The help server's listen port number.
251  static int theHelpServerPort;
252 
253  /// The help server's broken pipe signal handler.
254  static UT_Signal *theHelpServerSigHandler;
255 };
256 
257 #endif
258 
259 
virtual void openFile(const char *path)=0
GLuint GLsizei const GLchar * message
Definition: glcorearb.h:2543
virtual void setHelpAddress(const char *address)=0
Sets the address the server should bind to.
virtual void setBaseURI(const char *base_uri)=0
virtual bool getTextHelp(const char *url, UT_String &text_help)=0
virtual bool getTooltip(const char *url, UT_String &tooltip)=0
Obtains a tool tip from the help page pointed to by the URL.
const UT_StringHolder & getHelpAddress() const override
GLsizei const GLchar *const * path
Definition: glcorearb.h:3341
virtual void setUseExternalHelp(bool use_external)=0
virtual UT_StringArray getExprCommandsForHelpKeyword(const char *keyword)=0
**But if you need a result
Definition: thread.h:613
virtual void openHelpPath(const char *help_path)=0
UT_StringArray & getURLStack()
#define MOT_API
Definition: MOT_API.h:10
virtual const UT_String & getStartupURL()=0
virtual UT_StringArray getCommandsForHelpKeyword(const char *keyword)=0
virtual bool getParsedTooltip(const char *url_key, const char *full_help, UT_String &tooltip)=0
virtual void getHelpCardURL(OP_Operator *op, UT_String &str)=0
virtual void displayData(const char *data, bool is_html)=0
virtual void openHelpCard(OP_Node *node)=0
virtual const UT_String & getHelpBaseURL()=0
virtual void openStartup()=0
virtual void closeFloatingPane()=0
bool getUseExternalHelp() const override
virtual void openContents()=0
virtual void setUseIPv6(bool use_ipv6)=0
Whether the help server should use ipv6 or not.
const UT_String & getExternalHelpURL() const override
const UT_String & getBaseURI() const override
Returns the baseURI.
virtual UT_StringHolder getExprCommandHelp(const char *command)=0
Return the text help for the given hscript expression command.
bool getUseIPv6() const override
virtual void openURL(const char *url)=0
Definition: format.h:895
virtual UT_StringHolder getCommandHelp(const char *command)=0
Return the text help for the given hscript command.
virtual void setExternalHelpURL(const char *ext_help_url)=0