<!DOCTYPE linuxdoctr system>

<article>

<!--
<title>Palm OS Application Development
<author>by David H. Silber
<htmlurl url="mailto:palm@orbits.com" name="palm@orbits.com">
<date>v0.6.7, 25 September 1998
-->

<title>Palm OS アプリケーション開発
<author>by David H. Silber
  <htmlurl url="mailto:palm@orbits.com" name="palm@orbits.com">
  <date>v0.6.7, 20 September 1998
  <trans>川島 浩、<tt><htmlurl url="mailto:kawashima@iname.com"
    name="kawashima@iname.com"></tt>
  <tdate>v0.6.7j, 25 June 1999

<!--
<abstract>
This document provides the information you need to develop applications
for Palm OS devices, using Linux as a development platform.
While examples and details apply specifically to Linux systems, most
of the information is applicable to any environment in which the tools
will function.
</abstract>
-->
<abstract>
この文書には、Palm OS デバイス上のアプリケーションを開発するために
必要な情報が書かれています。
文書中の例や説明は Linux を前提として書かれていますが、
これらのツールが動作する環境ならば(訳注: 種々の Unixや、GNU Win32環境
ですね。)、ほとんどの情報がそのまま役立つはずです。
</abstract>

<!--
<toc>
<sect>Introduction
<p>
So, you have this nifty little Palm OS device, and you want to write
your own programs for it.
At first glance, it may appear that what you need to do is go out and
buy the commercial development kit.
However, that kit requires a MacOS or Windows system.
Thanks to the hard work of various people (see the appendix 
``Credits'')
we have freeware tools for building Palm OS programs.
-->

<toc>
<sect>はじめに
<p>
こんなに小さくてすばらしい Palm OS デバイスを持っていたら、きっと
あなたも自分でプログラムを書きたくなるに決まってますよね。
一見すると、まず市販されている開発キットを買う必要があるように
思えるかもしれませんが、実はこれらのキットは MacOS か Windows の上で
しか動作しないのです。
しかし、さまざまな人たちのたゆみない努力により、(付録の``謝辞''を参照)
Palm OS 上のプログラムを開発するためのフリーウエアツールが開発されました。

<!--
This document will explain how to install and use these tools and then
provide a tutorial on writing Palm OS programs.
Initially, the prc-tools collection, which provides a `C' language
cross-compiler built upon the GNU gcc compiler and includes pilrc to
compile resources will be featured in my directions and examples.

In the tutorial sections, I am presuming that you are familiar with
programming in general, the ``C'' programming language, and unix
commands, such as ``make''.

You should now backup up the data on your Palm OS device, especially if
you intend to install the programs presented in the tutorial sections
of this document.

You may want to read the API documentation described under ``See Also''.
-->
この文書では、これらのツールをインストールする方法とその使い方について
述べ、さらに Palm OS プログラムを書くためのチュートリアルを提供しています。
最初に prc-tools を、私の説明と例を交えて紹介します。
prc-tools は、GNU gcc コンパイラの上に作成された、`C' 言語の
クロスコンパイル環境を提供します。また、prc-tools には pilrc という、
リソースをコンパイルするためのツールも含まれています。

チュートリアルの章では、読者はすでに一般的なプログラミングや
`C' 言語や UNIX の ``make'' などのコマンドに慣れ親しんでいる
ことを前提としています。

さて、チュートリアルの章で説明しているプログラムをインストールする
つもりならば、まずあなたの Palm OS デバイスのデータをバックアップ
しておきましょう。

``参考文献''で説明されている API 文書も参考になります。



<!--
<sect1>This Document
<p>
The latest version of this document can be read at
<htmlurl url="http://www.orbits.com/Palm/PalmDevelopment-HOWTO.html"
name="http://www.orbits.com/Palm/PalmDevelopment-HOWTO.html">.
Errata, future plans, miscellaneous notes and Palm links may be found at
<htmlurl url="http://www.orbits.com/Palm/"
name="http://www.orbits.com/Palm/">.
This document is part of the Linux Documentation Project (LDP).
See
<htmlurl url="http://sunsite.unc.edu/LDP/"
name="http://sunsite.unc.edu/LDP/">
for further information about the LDP and other HOWTO documents.
-->

<sect1>この文書について
<p>
このドキュメントの最新版は以下のURLで読むことができます:
<htmlurl url="http://www.orbits.com/Palm/PalmDevelopment-HOWTO.html"
name="http://www.orbits.com/Palm/PalmDevelopment-HOWTO.html">
正誤表、将来計画、いろいろな注意点や Palm 関係のリンクは以下からたどること
ができると思います:
<htmlurl url="http://www.orbits.com/Palm/"
name="http://www.orbits.com/Palm/">.
この文書は Linux Documentation Project (LDP) の一部です。
LDP に関しての詳細や、他の HOWTO 文書に関しては:
<htmlurl url="http://sunsite.unc.edu/LDP/"
name="http://sunsite.unc.edu/LDP/">
をご覧ください。

<!--
If you find anything in this document which needs to be corrected or
better explained, please send email to the address above and
specify which version of this document you are referring to.

If you wish to translate this document, please check
<htmlurl url="http://www.orbits.com/Palm/"
name="http://www.orbits.com/Palm/">
first to avoid duplication of effort.
When you have completed the translation, send me the SGML source, and
I will make it available in parallel with the american english original.

This document is Copyright &copy; 1997 - 1998 by David H. Silber.
It is released under the copyright terms in the LDP HOWTO-INDEX document.
-->

この文書に関して、修正の必要な箇所や、もっとよい説明などありましたら、
上に書いたメイルアドレスまでメイルをください。その時には文書の
バージョン情報も添えてくださいね。

この文書を翻訳したいという方がいらっしゃいましたら、
<htmlurl url="http://www.orbits.com/Palm/"
name="http://www.orbits.com/Palm/">
をまずチェックしてみてください。すでに他の方が翻訳をしているかも
しれません。
翻訳ができあがったら、私に SGML のソースをぜひ送ってください。
元の英語文書と一緒に参照できるようにしたいと思っていますので。

この文書は Copyright &copy; 1997 - 1998 by David H. Silber です。
LDP HOWTO-INDEX 文書の著作権条件のもとに配布されています。


<!--
<sect1>See Also
<p>
The <it/Palm OS Linux Desktop HOWTO/
<htmlurl url="http://www.orbits.com/Palm/PalmOS-HOWTO.html"
name="http://www.orbits.com/Palm/PalmOS-HOWTO.html">
document describes more basic information, including how
to install the HotSync cradle and the pilot-link software.

Programmers unfamiliar with <tt/C/ might want to work their way through
<tscreen>
The C Programming Language, by Brian W. Kernighan and Dennis M. Ritchie
</tscreen>
before attempting to understand the tutorial section of this document.

Reading the API documents from <it>Palm Computing</it> will get you detail
beyond the scope of this document.
<itemize>
<item>
Developing Palm OS 3.0 Applications &#045;&#045; Part I: Interface Management
<htmlurl url="http://palm.3com.com/devzone/docs/Ref1.zip"
name="http://palm.3com.com/devzone/docs/Ref1.zip">
<item>
Developing Palm OS 3.0 Applications &#045;&#045; Part II: System Management
<htmlurl url="http://palm.3com.com/devzone/docs/Ref2.zip"
name="http://palm.3com.com/devzone/docs/Ref2.zip">
<item>
Developing Palm OS 3.0 Applications &#045;&#045; Part III: Memory and Communications
Management
<htmlurl url="http://palm.3com.com/devzone/docs/Ref3.zip"
name="http://palm.3com.com/devzone/docs/Ref3.zip">
</itemize>

The <it/Palm OS Conduit Development HOWTO/
<htmlurl url="http://www.orbits.com/Palm/PalmConduit-HOWTO.html"
name="http://www.orbits.com/Palm/PalmConduit-HOWTO.html">
document describes how to use the pilot-link libraries to write
Linux-resident conduits for use with Palm OS devices.
-->

<sect1>参考
<p>
The <it>Palm OS Linux Desktop HOWTO</it>
<htmlurl url="http://www.orbits.com/Palm/PalmOS-HOWTO.html"
name="http://www.orbits.com/Palm/PalmOS-HOWTO.html">
この文書では、HotSync クレードルや pilot-link ソフトウエアの
インストール方法など、より基本的なことを解説しています。

<tt>C</tt> 言語に詳しくない方には、チュートリアルの章を読む前に
<tscreen>
The C Programming Language, by Brian W. Kernighan and Dennis M. Ritchie
</tscreen>
を読まれることをお勧めします。
(訳注: この本は日本語訳があります。「プログラミング言語C(第２版)」
共立出版 ISBN 4-320-02483-4)

この文書で解説している内容よりも詳しいことを知りたい場合には、
<it>Palm Computing</it> の以下の文書を読むことをお勧めします。
<itemize>
<item>
Developing Palm OS 3.0 Applications &#045;&#045; Part I: Interface Management
<htmlurl url="http://palm.3com.com/devzone/docs/Ref1.zip"
name="http://palm.3com.com/devzone/docs/Ref1.zip">
<item>
Developing Palm OS 3.0 Applications &#045;&#045; Part II: System Management
<htmlurl url="http://palm.3com.com/devzone/docs/Ref2.zip"
name="http://palm.3com.com/devzone/docs/Ref2.zip">
<item>
Developing Palm OS 3.0 Applications &#045;&#045; Part III: Memory and Communications
Management
<htmlurl url="http://palm.3com.com/devzone/docs/Ref3.zip"
name="http://palm.3com.com/devzone/docs/Ref3.zip">
</itemize>

(訳注: 上記ドキュメントの日本語訳が販売されています。
「PalmOSバイブル」監訳：山田達司さん(日経BP社刊)
また、「ここまでできるPalm/WorkPadプログラミングWindows版」
著者：漆畑広樹さん(オーム社刊) もとても参考になります。)


<!--
FIXME &#045;&#045; 日本語ドキュメント
-->

The <it>Palm OS Conduit Development HOWTO</it>
<htmlurl url="http://www.orbits.com/Palm/PalmConduit-HOWTO.html"
name="http://www.orbits.com/Palm/PalmConduit-HOWTO.html">
この文書は、pilot-link ライブラリを使って Linux 用のコンジット
プログラムを書く方法について書かれています。

<!--
<sect1>Mailing List<label id="pilot-unix">
<p>
The pilot-unix mailing list is maintained by
<url url="mailto:pilot-unix-owner@lists.best.com" name="Matthew Cravit">.
Its mandate is:
<tscreen><verb>
The pilot-unix mailing list is for discussion and idea-sharing for those
interested in using the US Robotics Pilot PDAs with UNIX systems. This
includes people who are interested in helping to develop tools to allow the
Pilot to operate with UNIX, and possibly to develop an SDK for the Pilot
for Unix.
</verb></tscreen>

For more information, including how to subscribe to the list, send 
mail containing the word ``<tt>INFO</tt>''
to <htmlurl url="mailto:pilot-unix-request@lists.best.com"
name="pilot-unix-request@lists.best.com">.
The subject line does not matter.
-->

<sect1>メイリングリスト<label id="pilot-unix">
<p>
Pilot-unix メイリングリストは、
<url url="mailto:pilot-unix-owner@lists.best.com" name="Matthew Cravit">.
によって運営されています。
このメイリングリストのルール(mandate)は:
<tscreen><verb>
pilot-unix メイリングリストは、US Robotics Pilot PDA を UNIX システムと
一緒に使うことに興味のある人のための、議論と知識共有のためのものです。
これには、Pilot を UNIX と一緒に使うためのツール開発や、
Unix 上の Pilot 用 SDK の開発の助けをすることに興味のある人なども含まれます。
</verb></tscreen>

さらに詳細な情報(メイリングリストへの参加も含めて)については、
``<tt>INFO</tt>''
という単語を含むメイルを
<htmlurl url="mailto:pilot-unix-request@lists.best.com"
name="pilot-unix-request@lists.best.com">.
宛てに送ってください。Subject 行は無視されますので注意してください。
<!--
FIXME &#045;&#045; 日本の pilot-tech-ml の情報
-->

<!--
<sect1>Mailing List Archives<label id="pilot-unix-archives">
<p>
An archive of the pilot-unix mailing list can be found at
<htmlurl url="http://www.acm.rpi.edu/~albert/pilot/"
name="http://www.acm.rpi.edu/~albert/pilot/">.
<htmlurl url="http://www.acm.rpi.edu/&tilde;albert/pilot/"
name="http://www.acm.rpi.edu/&tilde;albert/pilot/">.
It is maintained by
<url url="mailto:albert@acm.rpi.edu" name="Chris Stevens">.

<sect1>FTP Sites<label id="pilot-unix-ftp-site">
<p>
An FTP site containing an archive of Pilot tools for use on unix systems
is located at 
<htmlurl url="ftp://ryeham.ee.ryerson.ca/pub/PalmOS/" 
name="ftp://ryeham.ee.ryerson.ca/pub/PalmOS/">.
It is maintained by
<url name="Jeff Dionne" url="mailto:jeff@ryeham.ee.ryerson.ca">.

The Free Software Foundation (FSF) provides many free development tools 
(including gcc, gdb and the binutils tools collection) at
<htmlurl url="ftp://prep.ai.mit.edu/pub/gnu/"
name="ftp://prep.ai.mit.edu/pub/gnu/">.
-->

<sect1>メイリングリストのアーカイブ<label id="pilot-unix-archives">
<p>
  pilot-unix メイリングリストのアーカイブ(過去の記録)は、
<htmlurl url="http://www.acm.rpi.edu/~albert/pilot/"
name="http://www.acm.rpi.edu/~albert/pilot/">.
<htmlurl url="http://www.acm.rpi.edu/&tilde;albert/pilot/"
name="http://www.acm.rpi.edu/&tilde;albert/pilot/">
にあります。このアーカイブは、
<url url="mailto:albert@acm.rpi.edu" name="Chris Stevens">
によって運営されています。
<!--
FIXME &#045;&#045; 日本の pilot-tech-ml の情報
-->

<sect1>FTP サイト<label id="pilot-unix-ftp-site">
<p>
Unix 上で使う Pilot 用のツール類のアーカイブは
<htmlurl url="ftp://ryeham.ee.ryerson.ca/pub/PalmOS/" 
name="ftp://ryeham.ee.ryerson.ca/pub/PalmOS/">
にあります。
<url name="Jeff Dionne" url="mailto:jeff@ryeham.ee.ryerson.ca">
によって運営されています。

Free Software Foundation (FSF) は、gcc や gdb や binutils などなどの
たくさんのフリーな開発ツールを提供してくれています。
URL は、
<htmlurl url="ftp://prep.ai.mit.edu/pub/gnu/"
name="ftp://prep.ai.mit.edu/pub/gnu/">.
です。

<!--
<sect>Tools
<p>
You will need the pilot-link, prc-tools, gcc, binutils, and gdb software
distributions.
In order to install these tools, you should have make, gcc, patch and
the ncurses libraries already installed on your Linux system.

References to files from the tools packages will be relative to
their installation <it/prefix/ directory.

<sect1>pilot-link
<p>
If you have not done so already, you should install the <it/pilot-link/
software, as described in
<htmlurl url="http://www.orbits.com/Palm/PalmOS-HOWTO.html"
name="http://www.orbits.com/Palm/PalmOS-HOWTO.html">.
Included in the <it/pilot-link/ suite of tools is <it/pilot-xfer/,
which will be used to install PalmOS applications.
-->

<sect>ツール
<p>
まずは、 pilot-link, prc-tools, gcc, binutils と gdb の配布パッケージが
必要です。これらのツールをインストールするためには、Linux 上にすでに
make, gcc, patch, ncurses ライブラリが既にインストールされていなければ
なりません。
ツールパッケージからファイルが参照される時は、それらをインストールした
<it>プレフィックス</it>ディレクトリからの相対参照でおこなわれるはずです。

<sect1>pilot-link
<p>
まだインストールしていなければ、 <it>pilot-link</it>をインストール
してください。
インストールの方法については、
<htmlurl url="http://www.orbits.com/Palm/PalmOS-HOWTO.html"
name="http://www.orbits.com/Palm/PalmOS-HOWTO.html">.
を参照してください。
<it>pilot-link</it>に含まれている <it>pilot-xfer</it>は、PalmOS アプリケーションを
(訳注: Palm に)インストールするためのツールです。

<!--
<sect1>prc-tools
<p>
The prc-tools package is a complete set of development tools built from
the FSF GNU utilities, compiler and debugger, with the addition of a
few special tools.
This is the software that allows us to develop Palm OS software on a
Linux system.


There is not much in the way of documentation, but you might want to
look at the 
<it>Pilot Software Development</it> web page at
<htmlurl url="http://www.massena.com/darrin/pilot/"
name="http://www.massena.com/darrin/pilot/">.
-->

<sect1>prc-tools
<p>
Prc-tools パッケージは、FSF の GNU ユーティリティ、コンパイラ、
デバッガをベースとして、いくつか特殊なツールを付加した開発ツール
キットです。
これらを使うことで、Linux 上で Palm OS ソフトウエアを開発することが
できるようになります。

開発方法に関する文書はあまり多くありませんが、以下が役に立つでしょう
<it>Pilot Software Development</it> web page at
<htmlurl url="http://www.massena.com/darrin/pilot/"
name="http://www.massena.com/darrin/pilot/">.

<!--
<sect2>Installing prc-tools
<p>
Download the most recent version of prc-tools from 
<htmlurl url="ftp://ryeham.ee.ryerson.ca/pub/PalmOS"
name="ftp://ryeham.ee.ryerson.ca/pub/PalmOS">.
The GNU tools can be retrieved from 
<htmlurl url="ftp://prep.ai.mit.edu/pub/gnu" 
name="ftp://prep.ai.mit.edu/pub/gnu">.
Get <tt>binutils-2.7.tar.gz</tt>, <tt>gcc-2.7.2.2.tar.gz</tt> and
<tt>gdb-4.16.tar.gz</tt>.
The version numbers specified for the GNU tools are correct as of
prc-tools release 0.5.0.
Later releases of <it>prc-tools</it> may require newer versions of
the GNU tools.

Put all of the distribution packages in one directory.
Unpack only the prc-tools distribution.
The prc-tools <tt>Makefile</tt> will take care of the other packages.
By default, prc-tools will be installed in <tt>/usr/local/gnu</tt>.
If you want them installed somewhere else, you need to change the
value of <tt>INSTALLDIR</tt> in <tt>Makefile</tt>.
Change the value of <tt>GNUARCH</tt> to the directory in which you have
placed the distribution files for the GNU tools.
(There is no need to unpack them, the make process will take care of
that.)
-->

<sect2>Prc-tools のインストール
<p>
Prc-tools の最新バージョンは以下からダウンロードできます:
<htmlurl url="ftp://ryeham.ee.ryerson.ca/pub/PalmOS"
name="ftp://ryeham.ee.ryerson.ca/pub/PalmOS">.
GNU ツールは以下から:
<htmlurl url="ftp://prep.ai.mit.edu/pub/gnu" 
name="ftp://prep.ai.mit.edu/pub/gnu">.
<tt>binutils-2.7.tar.gz</tt>, <tt>gcc-2.7.2.2.tar.gz</tt> と
<tt>gdb-4.16.tar.gz</tt>
をダウンロードしてください。
上に書いた GNU ツールのバージョンは、prc-tools のリリース 0.5.0
が必要としているバージョンです。より新しい <it>prc-tools</it> リリース
では、GNU ツールのもっと新しいバージョンが必要かもしれません。

上で述べた配布パッケージを全部同じディレクトリに置きます。
まず、prc-tools だけを展開(unpack)します。その他のパッケージに関しては、
prc-tools の <tt>Makefile</tt> が展開などをおこなってくれます。
デフォルトでは、prc-tools は <tt>/usr/local/gnu</tt> にインストール
されます。
他のディレクトリにインストールしたい場合には、<tt>Makefile</tt> の中の
<tt>INSTALLDIR</tt> を変更する必要があります。また、<tt>GNUARCH</tt>を、
GNU ツールを置いたディレクトリに変更してください
(展開(unpack)する必要はありません。make プログラムがやってくれますから)。

<!--
The steps are:
<tscreen><verb>
tar -xvzf prc-tools.0.5.0.tar.gz
cd prc-tools-0.5.0
  (Edit Makefile, if necessary.)
make gnuuntar                                                              
make patch                                                                 
  (I found, on a Debian Linux system, that I needed to replace the termcap
  references in gbd-4.16/gdb/Makefile.in and gbd-4.16/readline/Makefile.in
  with references to the ncurses library.)
make gnutools
  (Now, as root:)
make
make install
</verb></tscreen>

<sect2>Using prc-tools
<p>
One good reference for general use of <tt>prc-tools</tt> is the
<tt>example</tt> directory, particularly the <tt>Makefile</tt>.
The tutorial will lead you through compiling a Palm OS application.
-->

つまり、次のような手順になります:
<tscreen><verb>
tar -xvzf prc-tools.0.5.0.tar.gz
cd prc-tools-0.5.0
  (必要なら Makefile を編集する)
make gnuuntar                                                              
make patch                                                                 
  (Debian Linux の場合には、gbd-4.16/gdb/Makefile.in と gbd-4.16/readline/Makefile.in
  の中で参照されている termcap を、ncurses ライブラリを参照するように変更する
  必要があります。)
make gnutools
  (ここで root ユーザになります。)
make
make install
</verb></tscreen>

<sect2>Prc-tools を使う
<p>
<tt>Prc-tools</tt>の一般的な使い方を知るためには、<tt>example</tt>
ディレクトリの中身、特に<tt>Makefile</tt>を参照するのが良いと思います。
この文章のチュートリアルの章でも、Palm OS アプリケーションをコンパイル
する方法について述べています。

<!--
<sect>Hello, World &#045;&#045; An Introduction To Palm OS Programming
<p>
It seems almost required that the first example in any programming
tutorial be the infamous ``Hello, world.'' program.
Once you have this program working, you know that you have at least a
basic grasp of how to create, compile and install a Palm OS program.

One thing to take note of is that Palm OS programs are event-driven.
Basicly, this means that unlike linear programs, (such as make, more,
or pilot-xfer) Palm OS applications mostly wait for <it/events/, then process
them in turn.
In case you are not familiar with them, events can be any occurrence.
Pen down & up, graffiti input, and alarms are all different events.
-->

<sect>Hello, World &#045;&#045; Palm OS プログラミングへの招待
<p>
どんなプログラムのチュートリアルでもまず最初に要求されるのは、
どうやら例の``Hello world'' プログラムみたいですね。
このプログラムを動作させることで、少なくとも、Palm OS プログラムの
作成方法、コンパイル方法とインストールの仕方を把握できるはずです。

ひとつ注意しておくべきなのは、Palm OS プログラムはイベントドリブン
だということです。
基本的には、他の(make や more や pilot-xfer などのような)直線的な
プログラムとはちょっと違って、Palm OS アプリケーションはおおむね、
<it>イベント</it>を待ち、それを処理するというような構造をしています。
イベントというのは、ペンダウン・アップ、グラフィティ入力、アラーム
などの、それぞれ異なるイベントが発生したことを指します。

<!--
<sect1>Getting Started
<p>

<sect2>Program Source
<p>
This is the source for our ``Hello, world.'' program:
<tscreen><verb>
#include <System/SysAll.h>
#include <UI/UIAll.h>

// ---------------------------------------------------------------------
// PilotMain is called by the startup code and implements a simple event
// handling loop.
// ---------------------------------------------------------------------
DWord PilotMain( Word cmd, Ptr cmdPBP, Word launchFlags )
{
    EventType event;


    if (cmd == sysAppLaunchCmdNormalLaunch) {

        //  Display a string.
        WinDrawChars( "Hello, world!", 13, 55, 60 );

	//  Main event loop:
        do {
            //  Doze until an event arrives.
            EvtGetEvent( &amp;event, evtWaitForever );

            //  System gets first chance to handle the event.
            SysHandleEvent( &amp;event );

            //  Normally, we would do other event processing here.

        // Return from PilotMain when an appStopEvent is received.
        } while (event.eType != appStopEvent);
    }
    return;
}
</verb></tscreen>
Put it into a text file as you normally would, and save it to a file
called ``hello.c''.
(The name doesn't really matter, so long as it ends with a ``.c'', but
I will be using this filename for my examples.)
-->

<sect1>まずはやってみよう
<p>

<sect2>プログラムのソースコード
<p>
これは、``Hello World'' プログラムのソースコードです:
(訳注: 以下では参考のために、ソースコードのコメント部分も日本語に訳出して
いますが、実際に gcc で日本語のコメントが通るかどうかは確認していません)
<tscreen><verb>
#include <System/SysAll.h>
#include <UI/UIAll.h>

// ---------------------------------------------------------------------
// PilotMain は、初期化コード(startup)から呼び出され、単純なイベントを
// 処理するループから成ります。
// ---------------------------------------------------------------------
DWord PilotMain( Word cmd, Ptr cmdPBP, Word launchFlags )
{
    EventType event;


    if (cmd == sysAppLaunchCmdNormalLaunch) {

        //  文字列を表示する
        WinDrawChars( "Hello, world!", 13, 55, 60 );

	//  メインのイベントループ:
        do {
            //  イベントが到着するまで眠る
            EvtGetEvent( &amp;event, evtWaitForever );

	    // まずはシステムにイベントを処理する機会を与える
            SysHandleEvent( &amp;event );

	    // 通常はここでその他のイベントの処理をおこなう。

	// appStopEvent を受け取ったら PilotMain からリターンする
        } while (event.eType != appStopEvent);
    }
    return;
}
</verb></tscreen>
以上のコードをお好きな方法で、``hello.c'' というファイル名のテキストファイル
として保存してください
(実際にはファイルの名前は最後が ``.c'' でありさえすればなんでもよいのですが、
ここではこういう名前を使います)。

<!--
<sect2>Compilation
<p>
Assuming that the bin directory used by the prc-tools is in your default
path, you have only to enter the following:
<tscreen><verb>
m68k-palmos-coff-gcc -O2 -g hello.c -o hello 
m68k-palmos-coff-obj-res hello
build-prc hello.prc "Hello, World" WRLD *.hello.grc
</verb></tscreen>

<tt/m68k-palmos-coff-gcc/ is the GCC cross-compiler built by prc-tools.
<tt/m68k-palmos-coff-obj-res/ takes the program generated by
<tt/m68k-palmos-coff-gcc/ and splits it up into the various sections that
Palm OS expects an application to have.
<tt/build-prc/ assembles the program sections, plus the information
provided on its command-line to build the final Palm OS program.
-->

<sect2>コンパイル
<p>
Prc-tools で使われている bin ディレクトリがちゃんとデフォールトパスに
含まれている(パスが通っている)ことを確認して、以下のコマンドを入力して
ください:
<tscreen><verb>
m68k-palmos-coff-gcc -O2 -g hello.c -o hello 
m68k-palmos-coff-obj-res hello
build-prc hello.prc "Hello, World" WRLD *.hello.grc
</verb></tscreen>

<tt>m68k-palmos-coff-gcc</tt>は、prc-tools によって生成された GCC クロスコンパイラ。
<tt>m68k-palmos-coff-obj-res</tt>は、<tt>m68k-palmos-coff-gcc</tt>によって生成された
プログラムを、Palm OS アプリケーションに必要ないくつものセクションに
分割してくれます。
<tt>build-prc</tt>はプログラムセクションを組み立て、コマンドラインで指定された
情報を付加して最終的な Palm OS プログラムを生成します。

<!--
<sect2>Installation
<p>
Now, presuming that you have backed up your Palm OS device, you are ready
to install <tt/hello.prc/ as follows:
<tscreen><verb>
pilot-xfer &#045;&#045;port /dev/ttyS1 &#045;&#045;install hello.prc
</verb></tscreen>
(Replace the specified serial device, as appropriate to your setup.)

Now, press the HotSync button on your cradle.
-->

<sect2>インストール
<p>
さて、Palm OS デバイスのメモリ内容のバックアップは既に済んでいますよね。
いよいよ<tt>hello.prc</tt>をインストールしてみましょう。
インストール方法は以下の通りです:
<tscreen><verb>
pilot-xfer &#045;&#045;port /dev/ttyS1 &#045;&#045;install hello.prc
</verb></tscreen>
(ここで指定したシリアルデバイスは、あなたの環境にあわせて変更してください)

さあ、クレードルの HotSync ボタンを押しましょう。

<!--
<sect2>Invoking the Program
<p>
When the HotSync is complete, you should find a program named
``Hello, World'' in the Applications Launcher with your other programs.
When you select it, you should see ``Hello, World!'' in the middle of
the Palm OS device's screen.
-->

<sect2>プログラムを起動する
<p>
HotSync が完了したら、アプリケーションランチャーから ``Hello, World'' という
名前のアプリケーションが見えるはずです。これをダブルタップすれば、
画面の真ん中あたりに、``Hello, World!'' という文字が現れるはずです。

<!--
<sect1>Dissection of A (Trivial) Program
<p>
Here, I want to explain the various parts of the ``Hello, World'' program.

<sect2>SysAll.h &#045;&#045; Master System Include File
<p>
<tt>System/SysAll.h</tt> brings in many of the separate system include files.
You may wish to look through some of these files.
Pay particular attention to
<tt>m68k-palmos-coff/include/PalmOS2/Common.h</tt>, as it contains the
typedefs used throughout the Palm OS libraries.

<sect2>UIAll.h &#045;&#045; Master User Interface Include File
<p>
<tt>UI/UIAll.h</tt> brings in many of the User Interface include files.

<sect2>PilotMain() &#045;&#045; Application Main Function
<p>
Every Palm OS applications program contains a <tt/PilotMain()/ function.
This takes the place of the <tt/main()/ function in a normal C program.
<tscreen><verb>
DWord PilotMain( Word cmd, Ptr cmdPBP, Word launchFlags )
</verb></tscreen>
When the program is started, <tt/cmd/ will contain an <it/Launch Code/
which may instruct the application to perform some action other than
its standard mode of operation.
-->

<sect1> この(簡単な)プログラムの解説
<p>
さて、この``Hello, World''プログラムの構成要素を説明したいと思います。

<sect2>SysAll.h &#045;&#045; おおもとのシステムインクルードファイル
<p>
<tt>System/SysAll.h</tt> をインクルードすることで、実はたくさんのシステム
インクルードファイルを一度にインクルードすることになります。
この中でいくつか見ておきたいファイルがあるかもしれませんね。
たとえば、<tt>m68k-palmos-coff/include/PalmOS2/Common.h</tt> では
Palm OS ライブラリ全体で使われるような typedef 宣言が含まれているので
目を通しておいて損はないと思います。

<sect2>UIAll.h &#045;&#045; おおもとのユーザインタフェースインクルードファイル
<p>
<tt>UI/UIAll.h</tt> は、ユーザインターフェースに関するたくさんのインクルード
ファイルをインクルードしています。

<sect2>PilotMain() &#045;&#045; アプリケーションのメイン関数
<p>
すべての Palm OS アプリケーションには(訳注: Hack や DA は除く)、
この <tt>PilotMain()</tt>関数が存在しなければなりません。
これは通常の C 言語における、<tt>main()</tt>関数と同じ役割を果たすものです。
<tscreen><verb>
DWord PilotMain( Word cmd, Ptr cmdPBP, Word launchFlags )
</verb></tscreen>
プログラムが起動された時に、<tt>cmd</tt>には <it>Launch Code</it>が渡されます。
この<it>Launch Code</it> によって、アプリケーションに対して通常とは異なる
動作を要求することも可能です。

<!--
<sect2>Testing the Launch Code
<p>
The Launch Code is passed in via the <tt/cmd/ argument and tested against
any Launch Code which the program is prepared to deal with.
In ``Hello, World'', any action other than a normal program launch is
ignored.
<tscreen><verb>
if (cmd == sysAppLaunchCmdNormalLaunch) {
</verb></tscreen>
There are many launch codes, covering a variety of situations.
See <tt>m68k-palmos-coff/include/PalmOS2/System/SystemMgr.h</tt>
for a complete list.

<sect2>Output
<p>
The <tt>WinDrawChars()</tt> function displays a text string at the specified
screen coordinates.
<tscreen><verb>
WinDrawChars( "Hello, world!", 13, 55, 60 );
</verb></tscreen>
-->

<sect2>Launch Code をチェックする
<p>
Launch Code は、<tt>cmd</tt>引数で渡されます。
それぞれのプログラムはこの Launch Code の値をチェックして、自分がそれに応答
できるかどうかを調べます。
``Hello, World'' プログラムでは、「normal program launch」以外のコードは
無視するようになっています。
<tscreen><verb>
if (cmd == sysAppLaunchCmdNormalLaunch) {
</verb></tscreen>
Launch codeには、いろいろな状況に対処するためにたくさんの種類があります。
どんなコードが存在するのかを全部知るためには、
<tt>m68k-palmos-coff/include/PalmOS2/System/SystemMgr.h</tt>
を読んでください。

<sect2>出力
<p>
<tt>WinDrawChars()</tt>関数は、指定された画面上の座標に文字列を表示します。
<tscreen><verb>
WinDrawChars( "Hello, world!", 13, 55, 60 );
</verb></tscreen>

<!--
<sect2>Main Event Loop
<p>
The application will continue to run until it receives an <tt/appStopEvent/,
which is exactly what it sounds like.
<tscreen><verb>
//  Main event loop:
do {
	.
	.
	.
// Return from PilotMain when an appStopEvent is received.
} while (event.eType != appStopEvent);
</verb></tscreen>
When an application receives this event, it needs to perform any
special clean-up that it requires and return from <tt/PilotMain/.

<sect2>Acquiring Events
<p>
The function <tt/EvtGetEvent/ changes its first argument as a side-effect.
When it returns, that means that some event has occurred, which the
operation system is reporting to the application.
<tscreen><verb>
EvtGetEvent( &amp;event, evtWaitForever );
</verb></tscreen>
-->

<sect2>メイン・イベントループ
<p>
アプリケーションは、<tt>appStopEvent</tt>を受け取るまで(その意味の通り)
走り続けます。
<tscreen><verb>
//  メイン・イベントループ
do {
	.
	.
	.
// appStopEvent を受け取ったら PilotMain からリターンする
} while (event.eType != appStopEvent);
</verb></tscreen>
アプリケーションがこのイベントを受け取った場合には、必要な後始末をした後に、
<tt>PilotMain</tt>からリターンするようにします。

<sect2>イベントを獲得する
<p>
<tt>EvtGetEvent</tt>関数は最初の引数を変更するので副作用があります。
この関数から帰ってくるときには、すなわちいくつかのイベントが
発生して、OS がアプリケーションに対してそれを通知しているという状態です。
<tscreen><verb>
EvtGetEvent( &amp;event, evtWaitForever );
</verb></tscreen>

<!--
<sect2>Processing Events
<p>
The application has full control over events that are passed along to
it.
However, most applications will want Palm OS to process most events.
This is accomplished by passing the events back to system-provided
event-processing functions.

<tt/SysHandleEvent()/ will process system events related to the buttons
and Graffiti.
Without this function call, Palm OS will never be able to process any
button press event to figure out that another application needs to start,
which means that <tt/appStopEvent/ will never appear on the even queue,
which means that you will never be able to get out of the ``Hello, World''
program.
In fact, the power button won't even function!

Go ahead and try this.
Comment out the call to <tt/SysHandleEvent()/, recompile and reinstall
the program, and see what happens.
Just make sure that you have a paper clip handy!
-->

<sect2>イベントを処理する
<p>
実は、アプリケーションは自分に渡されるすべての制御権を握っています。
しかし、通常のアプリケーションではほとんどのイベントを Palm OS に
処理して欲しい場合が多いでしょう。このために、システムが提供している
イベント処理ルーチン関数が提供されています。
<tt>SysHandleEvent()</tt>を呼び出すことで、ボタンや Graffiti 関連の
イベントをシステムに処理させることができます。
この関数を呼び出さないと Palm OS は、別のアプリケーションを起動するために
ボタンが押されたというイベントを処理することができません。
これはすなわち現在のアプリケーションに対して <tt>appStopEvent</tt>が
送られないことを意味します。その結果、``Hello, World''プログラムは
どうやっても終了できなくなってしまうことになります。
実際、電源オフのボタンもきかなくなってしまうんです!

さあ、試してみましょう。
<tt>SysHandleEvent()</tt>を呼び出しているところをコメントアウトして、
再コンパイル、再インストールしてなにが起こるか試してみてください。
ソフトリセットするためのゼムクリップを用意しておいてくださいね!

<!--
<sect2>Hello, World Notes
<p>
You have probably noticed that this program does nothing with its events,
other than passing them back to the operating system for processing.
Later examples will be more exciting, I promise!

<sect>Conclusion
<p>
There are a lot more issues to cover, including the use of forms, menus
 and other resources, which is fairly important to any non-trivial
program.

Regardless, I'm going to release this as
it stands, so that people can start using what I have written so far.

You may wish to bookmark 
<htmlurl url="http://www.orbits.com/Palm/"
name="http://www.orbits.com/Palm/">
and check back occasionally to see if I have released an updated version
of this document.

Constructive comments sent to
<htmlurl url="mailto:palm@orbits.com" name="palm@orbits.com">
are appreciated.
-->

<sect2>Hello, World プログラムに関する注記
<p>
恐らく気がついたと思いますが、このプログラムはイベントに関しては、
オペレーティングシステムに処理させるためにそのイベントを渡し直すこと
以外にはなにもおこなっていません。
次の機会にはもっとエキサイティングな例を書くことを約束します!

<sect>結論
<p>
もっといろいろとカバーすべき点があることはわかっています。
例えば、フォームの使い方とかメニューやそのほかのリソースに関してです。
おもちゃのプログラムでない限り、こういう機能はとても重要なものですからね。
まあとにかく、このままの状態でリリースしたいと思います。
ここで書いた事柄が、みなさんがプログラムを始めるきっかけになれば幸いです。

この文書の新しい版を見逃さないためには、
<htmlurl url="http://www.orbits.com/Palm/"
name="http://www.orbits.com/Palm/">
をブックマークに入れておいてください。

建設的な意見は大歓迎です。こちらにお願いします:
<htmlurl url="mailto:palm@orbits.com" name="palm@orbits.com">

<!--
<appendix>

<sect>People<label id="People">
<p>
<label id="Albanowski">
<url name="Kenneth Albanowski" url="mailto:kjahds@kjahds.com">
Maintains the pilot-link suite of tools.

<url name="Wes Cherry" url="mailto:wesc@ricochet.net">
Author of pilrc.

<url name="Matthew Cravit" url="mailto:pilot-unix-owner@lists.best.com">
List owner for the <it>
pilot-unix
</it> mailing list.

<url name="Jeff Dionne" url="mailto:jeff@ryeham.ee.ryerson.ca">
Original author of the pilot-link suite of tools.
Author of prc-tools.
Manages the
FTP area for the UNIX Palm OS/Pilot development project.

<url name="David H. Silber" url="mailto:palm@orbits.com">
Author of this document.

<url name="Chris Stevens" url="mailto:albert@acm.rpi.edu">
Maintains the
pilot-unix mailing list archives.
-->

<appendix>

<sect>協力してくれた人々<label id="People">
<p>
<label id="Albanowski">
<url name="Kenneth Albanowski" url="mailto:kjahds@kjahds.com">
は pilot-link 関連のツールを保守してくれています。

<url name="Wes Cherry" url="mailto:wesc@ricochet.net">
Pilrc の作者です。

<url name="Matthew Cravit" url="mailto:pilot-unix-owner@lists.best.com">
<it>Pilot-unix</it>メイリングリストの運営者です。

<url name="Jeff Dionne" url="mailto:jeff@ryeham.ee.ryerson.ca">
Pilot-link 関連ソフトウエアの原作者であり、prc-tools の作者でもあります。
また、UNIX Palm OS/Pilot 開発プロジェクトのFTP関連の管理者でもあります。

<url name="David H. Silber" url="mailto:palm@orbits.com">
この文書の著者です。

<url name="Chris Stevens" url="mailto:albert@acm.rpi.edu">
Pilot-unix メイリングリストのアーカイブを管理してくれています。

<!--
<sect>Credits
<p>
<em>linux</em> &#045;&#045; by Linus Torvalds and a cast of thousands.

<em>gcc</em> &#045;&#045; by the Free Software Foundation.

<em>binutils</em> &#045;&#045; by the Free Software Foundation.

<em>gdb</em> &#045;&#045; by the Free Software Foundation.

<em>pilot-link</em> &#045;&#045; by Jeff Dionne & Kenneth Albanowski.

<em>pilrc</em> &#045;&#045; by Wes Cherry.

<em>prc-tools</em> &#045;&#045; by Jeff Dionne.

<em>GPL</em> &#045;&#045; by the Free Software Foundation.

<sect>Glossary
<p>
<em>API</em> &#045;&#045; Application Programming Interface.
The specification for a library of functions that allow a program to
request certain services from whatever it is that the API applies to.
In this document, refers to the Palm OS API, which allows an application
to work with the operating system and thus the Palm OS device.

<em>application name</em> &#045;&#045; the name of the program.
Shows up under the icon and in the selection lists in the Applications
Launcher.

<em>application identification</em> &#045;&#045; a four-character string that
uniquely identifies a Palm OS application.

<em>conduit</em> &#045;&#045; a program, run on the desktop system, that moves data     
between applications on the desktop and the Palm OS device.

<em>event</em> &#045;&#045; an occurrence outside of the application of which it
is notified.

<em>event-driven</em> &#045;&#045; a form of program structure, in which the
program responds to events as they happen, instead of simply processing
data in a pre-defined order.

<em>form</em> &#045;&#045; a section of the Palm device's screen.

<em>GPL</em> &#045;&#045; the GNU General Public License.

<em>launch code</em> &#045;&#045; specifies which of many potential reasons a
Palm OS application has been invoked for.

<em>linux</em> &#045;&#045; a unix-like POSIX-compatible operating system
distributed under the terms of the GPL.
-->

<sect>謝辞
<p>
<em>linux</em> &#045;&#045; Linus Torvalds と何千人もの人々に対して。

<em>gcc</em> &#045;&#045; Free Software Foundation に対して。

<em>binutils</em> &#045;&#045; Free Software Foundation に対して。

<em>gdb</em> &#045;&#045; Free Software Foundation に対して。

<em>pilot-link</em> &#045;&#045; Jeff Dionne & Kenneth Albanowski に対して。

<em>pilrc</em> &#045;&#045; Wes Cherry に対して。

<em>prc-tools</em> &#045;&#045; Jeff Dionne に対して。

<em>GPL</em> &#045;&#045; Free Software Foundation に対して。



<sect>用語
<p>
<em>API</em> &#045;&#045; Application Programming Interface.
プログラムが特定のサービスを要求するための関数ライブラリの仕様です。
この文書では、Palm OS API を指し、アプリケーションがオペレーティングシステム
や Palm OS デバイスとうまくインターフェースすることを可能にします。

<em>アプリケーション名</em> &#045;&#045; プログラムの名前
アイコンの下や、アプリケーションランチャーのリストに表示されます。

<em>アプリケーション識別子</em> &#045;&#045; 4文字の文字列で、Palm OS の
アプリケーションをユニークに識別するための識別子です。

<em>コンジット</em> &#045;&#045; デスクトップで動作するプログラムで、
デスクトップアプリケーションと Palm OS デバイスの間でデータの
移動を行うものです。

<em>イベント</em> &#045;&#045; アプリケーションの外側で発生した事象で、アプリケーション
に通知されるものです。

<em>イベントドリブン</em> &#045;&#045; プログラム構造の一種で、あらかじめ記述された
順序でデータを処理するかわりに、イベントが発生した時にそれに反応するような
構造のものを指します。

<em>フォーム</em> &#045;&#045; Palm デバイスの画面の領域を指します。

<em>GPL</em> &#045;&#045; GNU General Public License です。

<em>ランチコード</em> &#045;&#045; Palm OS アプリケーションが起動されたさまざまな
理由を指定します。

<em>linux</em> &#045;&#045; Unix ライクな、POSIX コンパチブルなオペレーティング
システムで、GPL のもとに配布されています。


</article>
