Xojo / Real Studio Trial and Error
標準のヘルプビューアを利用する
目次
はじめに
Macはヘルプ表示用に、標準のビューア（/システム/ライブラリ/CoreServices/HelpViewer）を持っていますが、Real Studioでは、これを利用する仕組みは実装されていないようなので（2013.03現在）、少し調べてみました。
本記事は、当初「Real Studio / REALbasic コラム」の項目としていたものを、（まだ不確定な要素が多く、追加訂正が予想されることから）独立させ、再構成したものです。
追記：本稿は、Carbonビルドを対象としています。Cocoaビルドでは「アプリケーション側の実装」が異なります。詳細は標準のヘルプビューアを利用する・Cocoa編をご覧下さい。
基本方針
Appleのガイドに従います。
参考サイト(1)：Apple Help Programming Guide（PDF版もあります。）
具体的には、
- ヘルプを「Help Book」形式で作成。
- ヘルプを利用するための処理を、アプリケーション側に実装。
- ヘルプを機能させるために、ビルドしたアプリケーションを編集。
ファイル構成
Help Bookはバンドル形式で、フォルダの拡張子を「help」とすることで認識されます。
多言語に対応していますので、日本語化はローカライズ用フォルダ／ファイルを用いて行います。
+- myHelp.help // Help Book
+- Contents // Folder
+- Info.plist // プロパティリスト
+- Resources // Folder
+- shrd // 各言語共用画像格納フォルダ
+- Japanese.lproj // ローカライズ用フォルダ（ 日本語の場合 ）
+- InfoPlist.strings // プロパティリストのローカライズ用
+- myHelp.html // トップページ
+- myHelp.helpindex // indexファイル ( Help Indexerが生成 )
+- pgs // ページ格納フォルダ
+- xpgs // ページ格納フォルダ ( index作成対象外 )
+- gfx // 画像格納フォルダ
+- sty // スタイルシート格納フォルダ
+-My Application.app // Application
+- Contents // Folder ( Real Studioが作成 )
+- Resources // Folder ( Real Studioが作成 )
+- myHelp.help // Help Book
+- Japanese.lproj // ローカライズ用フォルダ（ 日本語の場合 ）
+- InfoPlist.strings // Applicationのプロパティリストのローカライズ用
ヘルプファイルの作成
ヘルプファイルはHTMLで記述します。
書き方は、概ね一般のホームページ等の書き方と同じですが、識別用に以下の一文をトップページに追加します。
注）contentは、後述するCFBundleHelpBookNameと一致させる。（ローカライズする場合はローカライズ後の名前）
<head>
…
<meta name="AppleTitle" content="マイアプリケーション ヘルプ" />
…
</head>
参考サイト(2)：MacWiki - ヘルプ作成のノウハウ
参考サイト(3)：資料室 - BathyScaphe ヘルプ
Info.plist
Help Book内のInfo.plistは、例えば以下のように記述します。
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>CFBundleDevelopmentRegion</key>
<string>ja_JP</string>
<key>CFBundleIdentifier</key>
<string>com.mycompany.myapplication.help</string>
<key>CFBundleInfoDictionaryVersion</key>
<string>6.0</string>
<key>CFBundleName</key>
<string>myHelp</string>
<key>CFBundlePackageType</key>
<string>BNDL</string>
<key>CFBundleShortVersionString</key>
<string>1</string>
<key>CFBundleSignature</key>
<string>hbwr</string>
<key>CFBundleVersion</key>
<string>1</string>
<key>HPDBookAccessPath</key>
<string>myHelp.html</string>
<key>HPDBookIconPath</key>
<string>shrd/icon.png</string>
<key>HPDBookIndexPath</key>
<string>myHelp.helpindex</string>
<key>HPDBookKBProduct</key>
<string>myHelp1</string>
<key>HPDBookTitle</key>
<string>My Application Help</string>
<key>HPDBookType</key>
<string>3</string>
</dict>
</plist>
<key>CFBundleHelpTOCFile</key>
<string>myHelp.html</string>
HPDBookTitle = "マイアプリケーション ヘルプ";
アプリケーション側の実装
アプリケーションがHelp Bookを利用するためには、以下の通り実装します。
- Appクラスに以下のメソッドを追加し、Openイベント等で起動時に呼び出す。
注）Appleのガイドに載っているサンプルは、AHRegisterHelpBookWithURL()を使っているが、これは10.5では利用できない。なので、代わりにAHRegisterHelpBook()を使っている。
メソッド名: RegisterMyHelpBook（注：名前は任意） 戻り値型: Integer Declare Function CFBundleGetMainBundle Lib "Carbon" () As Integer Declare Function CFBundleCopyBundleURL Lib "Carbon" (myApplicationBundle As Integer) As Integer Declare Function CFURLGetFSRef Lib "Carbon" (myBundleURL As Integer, myBundleFSRef As Ptr) As Boolean Declare Function AHRegisterHelpBook Lib "Carbon" (myBundleFSRef As Ptr) As Integer Dim myApplicationBundle As Integer Dim myBundleURL As Integer Dim myBundleFSRef As MemoryBlock Dim err As Integer myApplicationBundle = 0 myBundleURL = 0 myBundleFSRef = NewMemoryBlock(80) myApplicationBundle = CFBundleGetMainBundle() if myApplicationBundle = 0 then return -1 end if myBundleURL = CFBundleCopyBundleURL(myApplicationBundle) if myBundleURL = 0 then return -2 end if if CFURLGetFSRef(myBundleURL, myBundleFSRef) then err = AHRegisterHelpBook(myBundleFSRef) return err else return -3 end if - メニューは何もしなくてよい。
・後述するInfo.plistへの項目追加で、メニューの生成やアクションの紐付け（HelpViewerの起動）は自動的に行われるため、ユーザ側での実装は不要です。
・日本語環境では、メニュー名は「ヘルプ」、メニューアイテム名は「＜アプリケーション名＞ ヘルプ」となります。
・他に追加メニューアイテムがある場合は、あらかじめ「Help」メニューを生成し、アイテムを追加しておきます。
注）IDEからの実行では、Info.plist追加分が存在しないので、メニューが表示されない。（パーソナル版）
ビルド後の作業
ヘルプを機能させるためには、以下の作業を行います。（ビルドの度に毎回行う必要がある。）
- ビルド
- 出来上がった.appファイルを「パッケージの内容を表示」で開き、Help BookをContents/Resources/内にコピー。
- 同じく、Contents直下のInfo.plist（Help BookのInfo.plistではない）を開き、以下を追加する。
注１）タイトルを日本語表記にしたい場合は、ローカライズ用ファイルであるInfoPlist.stringsに、以下のように記述する。<key>CFBundleHelpBookFolder</key> <string>myHelp.help</string> <key>CFBundleHelpBookName</key> <string>My Application Help</string>
（こちらもHelp Book内のInfoPlist.stringsではなく、アプリケーションのContents/Resources/Japanese.lproj下。）
注２）CFBundleHelpBookNameは、前述のヘルプファイルのAppleTitleと一致させる。（ローカライズする場合はローカライズ後の名前）CFBundleHelpBookName = "マイアプリケーション ヘルプ";
問題点
Xcode - Cocoa系アプリでは問題ないのに、今回の方法では問題が発生することがいくつかあります。
また、OSのバージョンによって挙動が微妙に異なります。
項目 10.4 10.5 10.6 10.7 10.8 AppleTitle metaタグが必須 ○ ○ × × × CFBundleHelpBookNameがタイトルに ○ ○ ー ー ー HPDBookTitleがタイトルに ー ー ○ ○ ○ CFBundleHelpBookNameに日本語OK ○ ○ × ○ ○ 「戻る／進む」でタイトルバーからヘルプ名が消える バーなし バーなし バーなし ○ ○
- どうも10.5以前と10.6以降で、仕様が大きく違うようです。例えば、10.5以前ではCFBundleHelpBookNameがトップページのAppleTitleと一致していないと、ビューア起動時に何も表示されません。一方、10.6以降は一致していなくても（というか、タグが存在していなくても？）問題ありません。（HPDxxxというキーは、10.6以降で使われるようです。）
- CFBundleHelpBookNameに日本語が含まれると、10.6ではヘルプビューア起動時にエラーダイアログが表示されます。（Xcode - Cocoa系アプリは問題なし。）
対症療法的確認であり、真相は不明だが、特定の文字やその並びによってエラーになったりならなかったりすることから、いつものパターンっぽい。
10.6以降はHPDBookTitleがタイトルになるため、CFBundleHelpBookNameは英字のまま（ローカライズしない）でも構わないのですが、そうすると今度は、10.5で（AppleTitleも合わせて英字にしなければならないこともあって）ヘルプ名が英字になってしまいます。現状、両者を並立させる方法は見つかっていません。
ただし、ヘルプブック自体は認識していて、ライブラリ（家アイコン）ボタンを押して表示されるリストには現れ、選択すれば表示はされる。
- 10.7以降では、ビューアにヘルプ名（タイトル）を表示するバーが追加されますが、「戻る／進む」ボタンでページ移動するとタイトルが消えてしまいます。（10.7では、Xcode - Cocoa系アプリでも消えますが、10.8ではXcode - Cocoa系は消えません。）
お世話になったサイト
貴重な情報をご提供頂いている皆様に、お礼申し上げます。（以下、順不同）
参考サイト(1)：Apple Help Programming Guide
参考サイト(2)：MacWiki - ヘルプ作成のノウハウ
参考サイト(3)：資料室 - BathyScaphe ヘルプ
更新履歴
2014.09.06 はじめに、に追記を追加
2013.03.12 新規作成