Top / Eclipse / プラグイン開発のTIPS集 / ヘルプを実装する

Eclipseのヘルプはワークベンチのメニューの

ヘルプ >> ヘルプ目次

にありますが、このhtmlベースのヘルプも拡張して好きなヘルプを載せることができます。そして拡張するための拡張ポイントがorg.eclipse.help.toc拡張ポイントです。

この拡張ポイントで目次となるファイル(xml形式)を指定し、そのxmlファイルで目次に対応するhtmlファイルを指定します。

拡張ポイント

org.eclipse.help.toc

必須プラグイン

org.eclipse.help.appserver
org.eclipse.help.base
org.eclipse.help.ui
org.eclipse.help.webapp
org.eclipse.tomcat

plugin.xmlのサンプル

<extension
    point="org.eclipse.help.toc">
   <toc primary="true" file="toc.xml"/>  <-トップの目次となるxmlファイル。
   <toc file="tocconcepts.xml"/>
   <toc file="tocgettingstarted.xml"/>
   <toc file="tocreference.xml"/>
   <toc file="tocsamples.xml"/>
   <toc file="toctasks.xml"/>
</extension>

目次となるxml(ここではtoc.xml)のサンプル

<?xml version="1.0" encoding="UTF-8"?>
<?NLS TYPE="org.eclipse.help.toc"?>

<toc label="Sample Table of Contents" topic="html/toc.html">
↑目次のSample Table of Contents をクリックしたときに
  表示されるhtmlはhtml/toc.htmlです、の意味
   <topic label="Getting Started">
      <anchor id="gettingstarted"/>
   </topic>
   <topic label="Concepts"> <-目次にConceptsと表示
      <anchor id="concepts"/> <-toc.xml#conceptsとなってる箇所をここに挿入
   </topic>
   <topic label="Tasks">
      <anchor id="tasks"/>
   </topic>
   <topic label="Reference">
      <anchor id="reference"/>
   </topic>
   <topic label="Samples">
      <anchor id="samples"/>
   </topic>
</toc>

<anchor id="concepts"/> でリンクされるtocconcepts.xml

<?xml version="1.0" encoding="UTF-8"?>
<?NLS TYPE="org.eclipse.help.toc"?>

<toc label="Concepts" link_to="toc.xml#concepts"> <-ここでリンクされてる
  <topic label="Main Topic"  href="html/concepts/maintopic.html"> 
    <topic label="Sub Topic" href="html/concepts/subtopic.html" /> 
  </topic>
  <topic label="Main Topic 2">
    <topic label="Sub Topic 2" href="html/concepts/subtopic2.html" /> 
  </topic> 
</toc>
capture.png

ポイント

htmlファイル群は圧縮できる。

目次ファイル内で別の目次ファイルを指定できる

ヘルプメニューからではなく、アクションやボタンなどでヘルプを起動する

ヘルプメニューの「ヘルプ目次」は

ActionFactory.HELP_CONTENTS.create(window)

でアクションを取得できます。このクラスは実体は

org.eclipse.ui.internal.actions.HelpContentsAction

なのですが、このrunメソッドからヘルプの起動方法を拝借しました。なかでは以下のようなことをやってます。

final IWorkbenchWindow workbenchWindow = getSite().getWorkbenchWindow();
if (workbenchWindow == null) {
  // action has been disposed
  return;
}
// This may take a while, so use the busy indicator
BusyIndicator.showWhile(null, new Runnable() {
  public void run() {
    workbenchWindow.getWorkbench().getHelpSystem()
        .displayHelp();
  }
});

これでヘルプが起動できます。

ヘルプから、プログラムを呼び出す

org.eclipse.help.ILiveHelpAction? クラスを使うと、ヘルプ上からプログラムを呼び出すことができます。例えば、ヘルプで「下のリンクをクリックするとパースペクティブを変更します」なんてリンクを作ることができるわけです。Eclipseのヘルプってようするにhtmlなわけですが、htmlからクライアントのプログラムが起動できるのって、レガシーなJ2EEを作ってきた私からすると、なんか衝撃的です。

やり方は、あらかじめヘルプドキュメント内で「アクション」を起動するJavaScript?を読み込んでおいて、そのJavaScript?を実行するだけです。そのJavaScript?を呼び出すと、指定された「アクション」クラスが実行される、という機構ですね。もちろんその「アクション」クラスはあるインタフェースの実装クラスとなっています。

JavaScript?の読込

あらかじめ、

<script language="JavaScript" src="../../../org.eclipse.help/livehelp.js"> </script>

としてJavaScript?を読み込んでおきます。srcのパスはそのhtmlファイルからorg.eclipse.helpプラグインへの相対パスになります。例えばあるプラグイン内にある、ルートから見て hoge/fuga.htm というドキュメントhtmlの場合、

<script language="JavaScript" src="../../org.eclipse.help/livehelp.js"> </script> 

という指定、つまりプラグインのルートからさらに一つ上に上がってorg.eclipse.helpに入って...というパス指定になります。

ヘルプドキュメント上にリンク

次に通常のhtmlのリンクの様にJavaScript?を実行するリンクを作成します。呼び出すメソッドはliveActionです。使い方ですが、例えば

<a href='javascript:liveAction("nu.mine.kino.plugin.forms.proto.help",
"nu.mine.kino.plugin.forms.proto.help.actions.ActivehelpOpenDialogAction",
"")'>Click here for a Message.</a></p>

などとします。各引数の意味ですが、

  • アクションを含むプラグインの ID
  • アクションをインプリメントするクラスの名前
  • setInitializationString? を使用してライブ・ヘルプ・アクションに渡される String。HTML ページから情報を渡す必要はないため、この例では空のストリングを渡します。

となっています。

アクションクラスの実装

さて、上のnu.mine.kino.plugin.forms.proto.help.actions.ActivehelpOpenDialogAction? クラスは

org.eclipse.help.ILiveHelpAction

をimplementsしています。インタフェースは

public void setInitializationString(String data);
public void run();

です。run内に、実行させたい処理を記述します。例えば

Display.getDefault().syncExec(new Runnable() {
  public void run() {
    IWorkbenchWindow window = PlatformUI.getWorkbench()
        .getActiveWorkbenchWindow();
    if (window != null) {
      Shell shell = window.getShell();
      shell.setMinimized(false);
      shell.forceActive();
      MessageDialog.openInformation(window.getShell(),
          "Hello World.", "Hello World. " + data);
    }
  }
});

とかですね。注意点としては、この処理は別スレッドで実行されるため、UIの処理をする場合は

 Display.getDefault().syncExec(new Runnable() ...

でラップしないといけないところです。

ちょっとJavaScript?のはなし。苦手なので、スニペット。。

<script type="text/javascript">
<!--
function execute() {
  liveAction("nu.mine.kino.plugin.forms.proto.help", 
  "nu.mine.kino.plugin.forms.proto.help.actions.ActivehelpOpenDialogAction",
  document.form1.textfield.value);
}
// -->
</script>
......
......
<form name="form1" >
  <p><input type="text" name="textfield"></p>
</form>

としておいて

<p><a href='javascript:execute()'>Click here for a execute.</a></p>

とかすれば、ヘルプ内で入力した文字をプログラムに渡すことができます。

関連リンク


この記事は

選択肢 投票
おもしろかった 8  
そうでもない 2  
  • ヘルプ右初期画面の表紙ってどうやってかえるんでしょ? -- たかひろ? 2005-06-30 12:34:18 (木)
  • 一年前にいただいたコメントですが、plugin_customization.iniの org.eclipse.help.base/help_home=/nu.mine.kino.plugin.hoge.help/html/index.html などとすることで変更可能です。 -- きの? 2006-04-26 21:45:15 (水)
  • Ganymedeになって触ってみたら、GUIのTOCエディタがあるみたいです:-) -- きの? 2009-03-21 (土) 15:46:33

Top / Eclipse / プラグイン開発のTIPS集 / ヘルプを実装する

現在のアクセス:14246


添付ファイル: filecapture.png 1061件 [詳細]

トップ   編集 凍結 差分 バックアップ 添付 複製 名前変更 リロード   新規 一覧 単語検索 最終更新   ヘルプ   最終更新のRSS
Last-modified: 2013-02-26 (火) 16:08:01 (2400d)