MOT_HelpManager.h

Go to the documentation of this file.

/*
 * PROPRIETARY INFORMATION.  This software is proprietary to
 * Side Effects Software Inc., and is not to be reproduced,
 * transmitted, or disclosed in any way without written permission.
 *
 * NAME:        MOT_HelpManager.h ( BR Library, C++)
 *
 * COMMENTS:
 */

#ifndef __MOT_HelpManager__
#define __MOT_HelpManager__

#include "MOT_API.h"
#include <UT/UT_HelpManager.h>
#include <UT/UT_StringArray.h>
#include <PY/PY_Result.h>

class PY_EvaluationContext;
class UT_Signal;
class OP_Node;
class PRM_Parm;

/// Format used when building a parameter's help-card URL.
enum class MOT_ParmHelpURLFormat
{
    Embedded,
    Structured,
};

class MOT_API MOT_HelpManager : public UT_HelpManager
{
public:
             MOT_HelpManager();
            ~MOT_HelpManager() override;

    /// Opens the table of contenst help page.
    virtual void                 openContents() override;

    /// Opens the special essential-skills page on startup.
    virtual void                 openStartup() override;

    /// Opens a help page defined by the file.
    virtual void                 openFile(const char *path) override;

    /// Opens a URL in the help browser (url can be of forms
    /// "http://u.r.l", "hdox://u.r.l", "operator:table/name", "tool:name" etc)
    virtual void                 openURL(const char *url) override;

    virtual void                 openHelpPath(const char *help_path) override;

    /// Displays the buffer data in help browser.
    virtual void                 displayData(const char *data,
                                             bool is_html) override;

    /// Open the requested tooltip in a popup window.
    /// You can either pass the tooltip's help URL, the tooltip's help text,
    /// or both.
    ///
    /// x,y,w,h represents the native screen position and size of the 
    /// source feel that the tooltip is for.  If there is no source feel,
    /// then pass in (0,0,0,0) for x,y,w,h.
    ///
    /// You can optionally pass in additional information to appear
    /// in the tooltip -- help title, hotkey symbol, resolved hotkey string.
    virtual void                 openTooltipWindow(
                                    const char *url, const char *help,
                                    int x, int y, int w, int h,
                                    const char *title=nullptr,
                                    const char *hotkey_symbol=nullptr,
                                    const char *hotkey_str=nullptr,
                                    bool use_fixed_font=false)
                                    const override;

    /// Close all tooltip popup windows.
    /// Do nothing if there are no open tooltip popup windows.
    virtual void                 closeAllTooltipWindows() const override;

    /// Obtains a tool tip from the help page pointed to by the URL.
    bool                         getTooltip(const char *url, 
                                            UT_String &tooltip) override;

    /// Obtains a tool tip for the specified parameter.
    bool                         getTooltip(const PRM_Parm *parm,
                                            UT_String &tooltip) override;

    /// Obtains a tool tip conained by the full help text. The url serves
    /// as a caching key.
    bool                         getParsedTooltip(const char *url_key, 
                                                  const char *full_help, 
                                                  UT_String &tooltip) override;

    /// Obtains a plain text version of the help page pointed to by the URL
    /// (e.g. 'vex:attrib').
    bool                         getTextHelp(const char *url,
                                             UT_String &text_help) override;

    /// Return the text help for the given hscript command.
    UT_StringHolder getCommandHelp(const char *command) override;

    /// Return the text help for the given hscript expression command.
    UT_StringHolder getExprCommandHelp(const char *command) override;

    /// Return an array of hscript commands whose text help contain
    /// a match for the given keyword.
    UT_StringArray getCommandsForHelpKeyword(const char *keyword) override;

    /// Return an array of hscript expression commands whose text help
    /// conotain a match for the given keyword.
    UT_StringArray getExprCommandsForHelpKeyword(const char *keyword) override;

    // Convenience functions for opening the help cards for operators,
    // nodes, shelf tools, states, etc.
    virtual void                 openHelpCard(OP_Node *node) override;
    virtual void                 openHelpCard(
                                    OP_Operator *op, 
                                    const char *node_path=nullptr) override;
    virtual void                 openHelpCard(BM_State *state) override;
    virtual void                 openHelpCard(SHLF_Tool *tool) override;
    virtual void                 openHelpCard(
                                    const PYP_Interface *interface) override;
    virtual void                         openHelpCard(OP_GalleryEntry *entry) 
                                    override;
    virtual void                 openHelpCard(
                                    const PRM_ScriptParm *prop) override;

    // Obtains a URL that points to the help server web page for the given
    // operator, state, tool, or topic id.
    void                         getHelpCardURL(OP_Operator *op, 
                                                UT_String &str) override;
    void                         getHelpCardURL(BM_State *state, 
                                                UT_String &url) override;
    void                         getHelpCardURL(SHLF_Tool *tool, 
                                                UT_String &url) override;
    void                         getHelpCardURL(const PYP_Interface *interface,
                                                UT_String &url) override;
    void                         getHelpCardURL(OP_GalleryEntry *entry,
                                                UT_String &url) override;
    void                         getHelpCardURL(const PRM_ScriptParm *prop,
                                                UT_String &url) override;
    void                         getHelpCardURL(const char *helpTopicId, 
                                                UT_String &url) override;
    void                         getHelpCardURL(const PRM_Parm* parm,
                                                UT_String &help_path) override;
    
    /// Sets the base URI that is used to disambiguate the relative URLs.
    void                         setBaseURI(const char *base_uri) override;

    /// Returns the baseURI.
    const UT_String             &getBaseURI() const override
                                    { return myBaseURI; }

    /// Returns true if the help manager is using an external help server.
    /// Returns false otherwise.
    bool                         getUseExternalHelp() const override
                                    { return myUseExternalHelp; }

    /// Sets whether the help manager should use an external help server or not.
    void                         setUseExternalHelp(bool use_external) override;

    /// Sets the address the help server should bind to.
    void                         setHelpAddress(const char* help_address) override;
    const UT_StringHolder       &getHelpAddress() const override
                                    { return myHelpAddress; }

    /// Sets if the help server can use ipv6
    void                         setUseIPv6(bool use_ipv6) override;
    bool                         getUseIPv6() const override
                                    { return myUseIPv6; }

    /// Returns the base url for the external help server.
    /// Returns "" if no external help server is used.
    const UT_String             &getExternalHelpURL() const override 
                                    { return myExternalHelpURL; };

    /// Sets the url to the external help server.
    void                         setExternalHelpURL(
                                    const char *ext_help_url) override;

    /// Returns the base URL for all of Houdini's help.
    const UT_String             &getHelpBaseURL() override;

    /// Returns the url for the help startup page.
    const UT_String             &getStartupURL() override;

    /// Closes the help pane.
    virtual void                 closeFloatingPane() override;

protected:
    /// Format used by getHelpCardURL(const PRM_Parm*, UT_String&).
    MOT_ParmHelpURLFormat        myParmHelpURLFormat
                                    = MOT_ParmHelpURLFormat::Embedded;

    /// Helper function for getTooltip(const char *, UT_String&).
    /// Attempts to extract an operator, gallery entry or parameter
    /// tooltip from the given url.
    virtual bool                 extractTooltip(const char *url, 
                                                UT_String &tooltip);

    /// Updates all opened web browsers with the current
    /// help base URL.
    virtual void                 updateBaseURLInHelpBrowsersSubclass();
    
    /// Count help cards opening times for FS_datalogger.
    void                         countHelpCardPress(const char *message);

    /// Checks whether the help server has the help page under the given URL.
    bool                         getServerHasHelp(const char *url);

    UT_StringArray              &getURLStack() { return myURLStack; }

    /// Prefixes `help_path` with the help server's base url and
    /// passes back the final url in `url`.
    void                         prefixWithHelpBaseURL(const char *help_path, 
                                                       UT_String &url);

    /// Parses URL and tries to obtain the entity. 
    OP_Operator                 *getOpFromURL(const char *url);
    OP_GalleryEntry             *getGalleryEntryFromURL(const char *url);
    const PRM_ScriptParm        *getPropFromURL(const char *url);

    /// Resolve specified help path by expanding variables and translating
    /// help protocols to help paths.
    void                         resolveHelpPath(
                                    const char *help_path, 
                                    UT_String &resolved_path);

private:

    /// Parses the wiki text into an html text.
    /// NB: the url is needed for caching key by the help server.
    virtual void                 parseWikiToHtml(const char *url_key,
                                                 const char *wiki_help, 
                                                 UT_String & html_help);

    /// Builds the legacy URL with the label embedded in the path.
    void                         buildEmbeddedParmHelpURL(
                                    const PRM_Parm *parm, UT_String &url);
    /// Builds the structured URL with label and path as query string args.
    void                         buildStructuredParmHelpURL(
                                    const PRM_Parm *parm, UT_String &url);

    /// Helper methods to obtain tool tip from the operator or tool.
    bool                         getTooltip(OP_Operator *op, 
                                            UT_String &tooltip);
    bool                         getTooltip(OP_GalleryEntry *entry,
                                            UT_String &tooltip);
    bool                         getTooltip(const PRM_ScriptParm *prop,
                                            UT_String &tooltip);

    /// Helper for running python code (eg evaluating expression and obtaining
    /// the result of that expression) within the help python context.
    /// Returns true evaluation went ok, or false if error occured or the
    /// returned value type does not match the desired type.
    // NB: the expression can be only a single python statement; no multiline
    //     scripts are allowed (for now at least).
    bool                         runPythonExpr(const char *expr, 
                                        PY_Result::Type desired_result_type,
                                        PY_Result &py_result,
                                        PY_EvaluationContext *context=nullptr);
    bool                         evalPythonExpr(const char *expr, 
                                        UT_String &result);
    bool                         evalPythonExpr(const char *expr, 
                                        UT_StringHolder &result);
    bool                         evalPythonExpr(const char *expr, int &result);
    bool                         evalPythonExpr(const char *expr, 
                                        UT_StringArray &result);

    /// Initialize the help server using the houdinihelp Python module.
    bool                         initializeHelpServer();

    /// Initialize the help server if we haven't already tried to / do so, and
    //return whether or not it could be initialized.
    bool                         canAccessHelpServer();

    /// Returns the listen port of the help server.
    /// Starts the help server if necessary.
    int                          getHelpServerPort();

    bool                         myCouldInitializeHelpServer;
    UT_StringArray               myURLStack;        // followed url links
    UT_String                    myBaseURI;         // base URI for relative
    bool                         myUseExternalHelp;
    UT_String                    myExternalHelpURL;
    UT_String                    myHelpBaseURL;     //   html links
    UT_String                    myStartupHelpURL;

    UT_StringHolder              myHelpAddress;
    bool                         myUseIPv6;

    /// The help server's listen port number.
    static int                   theHelpServerPort;

    /// The help server's broken pipe signal handler.
    static UT_Signal            *theHelpServerSigHandler;
};

#endif