Eclipse/プラグイン開発のTIPS集/ヘルプを実装するのバックアップ差分(No.9)

追加された行はこの色です。
削除された行はこの色です。
#topicpath
----
#contents


Eclipseのヘルプはワークベンチのメニューの
 ヘルプ >> ヘルプ目次
にありますが、このhtmlベースのヘルプも拡張して好きなヘルプを載せることができます。そして拡張するための拡張ポイントがorg.eclipse.help.toc拡張ポイントです。

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

***拡張ポイント [#e65d7276]
 org.eclipse.help.toc

***必須プラグイン [#vd99645e]
 org.eclipse.help.appserver
 org.eclipse.help.base
 org.eclipse.help.ui
 org.eclipse.help.webapp
 org.eclipse.tomcat



***plugin.xmlのサンプル [#cb38fa2e]
 <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)のサンプル [#z24cb416]
 <?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 [#pc4d4842]
 <?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>


#ref(capture.png)



**ポイント [#pbeecb8c]
***htmlファイル群は圧縮できる。 [#h51e70ea]


***目次ファイル内で別の目次ファイルを指定できる [#vd9b9873]


*** ヘルプメニューからではなく、アクションやボタンなどでヘルプを起動する [#eacd3e65]
ヘルプメニューの「ヘルプ目次」は
 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();
   }
 });
これでヘルプが起動できます。

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



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




***JavaScriptの読込 [#z8695941]
あらかじめ、
 <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に入って...というパス指定になります。




***ヘルプドキュメント上にリンク [#uf871d0d]

次に通常の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 ページから情報を渡す必要はないため、この例では空のストリングを渡します。 

となっています。


***アクションクラスの実装 [#c51a147a]
さて、上の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>
とかすれば、ヘルプ内で入力した文字をプログラムに渡すことができます。









**関連リンク [#cbfbb9c1]
-[[Eclipseのヘルプ・システムを使ってプロジェクトを文書化する:http://www-6.ibm.com/jp/developerworks/opensource/040326/j_os-echelp.html]]
-Eclipseに同梱されているヘルプで「アクティブ・ヘルプ」で検索して出てくるドキュメント


----
この記事は
#vote(おもしろかった[2],そうでもない[0])
-ヘルプ右初期画面の表紙ってどうやってかえるんでしょ？ -- [[たかひろ]] &new{2005-06-30 12:34:18 (木)};
-一年前にいただいたコメントですが、plugin_customization.iniの org.eclipse.help.base/help_home=/nu.mine.kino.plugin.hoge.help/html/index.html などとすることで変更可能です。 -- [[きの]] &new{2006-04-26 21:45:15 (水)};

#comment
#topicpath


SIZE(10){現在のアクセス:&counter;}
Eclipse/プラグイン開発のTIPS集/ヘルプを実装する のバックアップ差分(No.9)

Eclipse/プラグイン開発のTIPS集/ヘルプを実装するのバックアップ差分(No.9)
