org.blueberry.ui.qt.help

Provides access to Qt Help information from inside the Workbench. More...

Collaboration diagram for org.blueberry.ui.qt.help:

Modules
	Internal
	This subcategory includes the internal classes of the org.blueberry.ui.qt.help plugin. Other plugins must not rely on these classes. They contain implementation details and their interface may change at any time. We mean it.

Detailed Description

Provides access to Qt Help information from inside the Workbench.

This plug-in collects all Qt QCH files (*.qch) from plug-ins in the RESOLVED state and registers them internally. The plug-in can be configured using the CTK Config Admin service and it listens to certain event topics on the CTK Event Admin.

The following configuration properties for the service PID "org.blueberry.services.help" are supported:

• homePage A QString property containing the a qthelp url pointing to the applications home page.

The plug-in subscribes to the following event topics:

• org/blueberry/help/CONTEXTHELP_REQUESTED signals a request for showing context sensitive help. If no properties are attached to the event, a qthelp url is constructed using the currently active part ID from the workbench. If the url is invalid, the home page is shown instead.
  
  Supported event properties are:
  • url Show the given url

The example below demonstrates how to provide configuration data for the org.blueberry.ui.qt.help plug-in.

  void start(ctkPluginContext *context) override
  {
    // Get a service reference for the Config Admin service
    ctkServiceReference cmRef = context->getServiceReference<ctkConfigurationAdmin>();
    ctkConfigurationAdmin *configAdmin = nullptr;
    if (cmRef)
    {
      configAdmin = context->getService<ctkConfigurationAdmin>(cmRef);
    }

    // Use the CTK Configuration Admin service to configure the BlueBerry help system.
    // This assumes that the plug-in providing the Config Admin implementation is
    // already active.
    if (configAdmin)
    {
      // Get a ctkConfiguration object for the PID "org.blueberry.services.help"
      // (or create an unbound instance if it does not exist yet).
      ctkConfigurationPtr conf = configAdmin->getConfiguration("org.blueberry.services.help", QString());

      // Configure the help system using a custom home page
      ctkDictionary helpProps;
      helpProps.insert("homePage", "qthelp://org.company.plugin/bundle/index.html");
      conf->update(helpProps);

      // Unget the service
      context->ungetService(cmRef);
    }
    else
    {
      // Warn that the Config Admin service is unavailable
    }
  }

Requesting context help may look like this:

  void requestHelp(ctkPluginContext *context)
  {
    if (context == nullptr)
    {
      // Warn that the plugin context is zero
      return;
    }

    // Check if the org.blueberry.ui.qt.help plug-in is installed and started
    QList<QSharedPointer<ctkPlugin>> plugins = context->getPlugins();
    foreach (QSharedPointer<ctkPlugin> p, plugins)
    {
      if (p->getSymbolicName() == "org.blueberry.ui.qt.help" && p->getState() != ctkPlugin::ACTIVE)
      {
        // The plug-in is in RESOLVED state but is not started yet.
        // Try to activate the plug-in explicitly, so that it can react
        // to events send via the CTK Event Admin.
        try
        {
          p->start(ctkPlugin::START_TRANSIENT);
        }
        catch (const ctkPluginException &)
        {
          // Warn that activating the org.blueberry.ui.qt.help plug-in failed
          return;
        }
      }
    }

    ctkServiceReference eventAdminRef = context->getServiceReference<ctkEventAdmin>();
    ctkEventAdmin *eventAdmin = nullptr;
    if (eventAdminRef)
    {
      eventAdmin = context->getService<ctkEventAdmin>(eventAdminRef);
    }

    if (eventAdmin == nullptr)
    {
      // Warn that the ctkEventAdmin service was not found
    }
    else
    {
      // Create the event and send it asynchronuously
      ctkEvent ev("org/blueberry/ui/help/CONTEXTHELP_REQUESTED");
      eventAdmin->postEvent(ev);
    }
  }