title: Phi::Form
author: YOSHIDA Kazuhiro
mailto: moriq@moriq.com

1. Phi::Form

標準アプリケーションウィンドウ ( フォーム )

フォームは，アプリケーションのメインウィンドウ，ダイアログボックス，あるいは MDI 子ウィンドウを表すことができる。フォームには， Phi::Button ， Phi::CheckBox ， Phi::ComboBox オブジェクトなど，他のオブジェクトを入れることができる。フォームの例としては， Phi::LoginDialog や Phi::PasswordDialog オブジェクトなどがある。

1.1. class methods

: new([name, caption]) : Phi::Form

1.1. methods

: close : nil
  フォームを閉じる。

  %c:close% はフォームを閉じることができるかどうか判断するため，最初に #on_close_query を呼び出す。

  #on_close_query が %c:false% ならば，クローズ処理はそこで終わる。

  #on_close_query が %c:true% ならば， #on_close が呼ばれる。

  : 注意
    Delphi では，アプリケーションのメインフォームが閉じると，アプリケーションは終了した。 Apollo にはメインフォームの概念はなく，すべてのフォームが隠されるとアプリケーションは終了する。

: show : nil
  フォームを表示する。

  %c:show% は #visible を %c:true% に設定し，フォームを画面の最前面に表示する。

: hide : nil
  フォームを非表示にする。

  %c:hide% は #visible を %c:false% に設定する。

: show_modal : Fixnum
  フォームをモード付きダイアログとして表示する。フォームがモード付きで表示された場合，フォームを閉じなければアプリケーションの実行を続けることはできない。モード付きフォームを閉じるには， #modal_result を 0 以外の値に設定する。 %c:show_modal% はフォームが閉じるときに #modal_result に設定された値を返す。

1.1. properties

: action : Phi::BasicAction
  コントロールに関連付けられているアクション

  %c:action% は，コントロールに関連付けられているアクションオブジェクトである。アクションは，ユーザーコマンドへの応答をアプリケーションが集中管理できるようにする。コントロールがアクションに関連付けられると，アクションによりコントロールの対応するプロパティおよびイベントが決まる ( コントロールが有効かどうか，コントロールがどのように #on_click に応答するか，など ) 。

: active : Boolean
  フォームにフォーカスがあるかどうか

  アクティブなフォームはすべてのキーボード入力を受け取る。フォームがタイトルバーを持つ場合，タイトルバーはコントロールパネルで指定したアクティブカラーで描画される。

: active_control : Phi::Control
: active_control=( control )
: focus_control : Phi::Control
: focus_control=( control )

  フォーム上でフォーカスがあるコントロールを返す／セットする。
  アプリケーション内で一度にフォーカスを持つことができるのは 1 つのコントロールだけである。フォームにフォーカスがない場合は，フォームがフォーカスを受け取ったときにフォーカスを受け取ることになるフォーム上のコントロールを示す。
  %c:active_control=% はフォームが非表示の場合（ #show #show_modal の前）でも使用可能である。その場合には、 #show #show_modal の時点でフォーカスを受け取るべきコントロールを指定することになる。
  : 注意(1)
    フォーカスが別のコントロールに移ると， #on_exit が発生する前に %c:active_control% の値が更新される。
  : 注意(2)
    Delphi では次の名前にわかれていた。
    Apollo では %c:focus_control% を属性形式（「xx=()形式」）に変更し、両者を統合した。
    --code
property ActiveControl: TWinControl;
procedure FocusControl(Control: TWinControl);
--
  Control#set_focus も参照のこと。

: border_icons : Fixnum
  フォームのタイトルバーに表示するアイコン

  : BI_SYSTEMMENU
    コントロールメニュー ( システムメニューともいう ) をフォームに表示する
  : BI_MINIMIZE
    アイコン化ボタンをフォームに表示する
  : BI_MAXIMIZE
    最大表示ボタンをフォームに表示する
  : BI_HELP
    #border_style が %c:BS_DIALOG% の場合，または %c:BI_MINIMIZE% と %c:BI_MAXIMIZE% が除外された場合，フォームのタイトルバーには疑問符が表示され，クリックするとカーソルが %c:CR_HELP% に変更される。そうでない場合は非表示になる

  : 注意
    %c:border_icons% と #border_style と組み合わせの一部は互いに排他的だ。たとえば， %c:border_icons% で %c:BI_MAX% ， %c:BI_MIN% を指定し， #border_style で %c:BS_DIALOG% を指定することはできない。

: border_style : Fixnum (BorderStyle)
  フォーム境界の体裁と動作

  : BS_DIALOG
    サイズ変更不可。標準のダイアログボックス境界
  : BS_SINGLE
    サイズ変更不可。一重境界線
  : BS_NONE
    サイズ変更不可。可視境界線なし
  : BS_SIZEABLE
    標準のサイズ変更可能境界
  : BS_TOOL_WINDOW
    %c:BS_SINGLE% と同じだがキャプションが小さい
  : BS_SIZE_TOOL_WIN
    %c:BS_SIZEABLE% と同じだがキャプションが小さい

  : 注意
    MDI 子フォームの境界スタイルを %c:BS_DIALOG% または %c:BS_NONE% に変更しても無効だ。

: client_rect : Phi::Rect
  フォームのクライアント領域

  クライアント領域とは，フォームの境界・メニュー・ステータスバー・タイトルバー・スクロールバーを除いた領域のことである。

  %c:client_rect% は
--ruby
rect(0, 0, client_width, client_height)
--
  と同等。

: client_width : Fixnum
  フォーム上のクライアント領域の幅

  ウィンドウ全体の大きさに基づいてフォームウィンドウの幅を変更するには， #width を使用する。

: client_height : Fixnum
  フォーム上のクライアント領域の高さ

  ウィンドウ全体の大きさに基づいてフォームウィンドウの高さを変更するには， #height を使用する。

: canvas : Phi::Canvas
  フォームの描画領域

  %c:canvas% を使うと，フォームのクライアント領域を描画できる。 %c:canvas% は #on_paint で使うのが一般的だ。

: drop_target : Boolean
  フォームがドラッグアンドドロップ操作のターゲットであるかどうか

: floating : Boolean
  フォームが別のウィンドウにドッキングされるかどうか

: form_state : Fixnum
  フォームの状態遷移の情報

  : FS_CREATING
    現在，フォームのコンストラクタが実行されている。
  : FS_VISIBLE
    フォームのウィンドウが可視状態である。この状態は， #visible を更新するために使われる
  : FS_SHOWING
    フォームの #window_state の変更が進行中である。この状態は， #window_state の変更が自分自身のを妨げないようにするために定義されている
  : FS_MODAL
    フォームはモード付きウィンドウとして作成された
  : FS_CREATED_MDICHILD
    フォームは MDI 親ウィンドウである。この状態は， MDI クライアントウィンドウが作成された場合にのみ設定される
  : FS_ACTIVATED
    フォームは ( フォーカスを受け取った，あるいは，アプリケーションがアクティブになったために ) %c:CM_ACTIVATE% メッセージを受け取ったが，まだ #activate を呼び出していない ( そして，まだ #on_active を呼んでいない ) 。

: form_style : Fixnum
  フォームのスタイル

  : FS_NORMAL
    フォームは MDI 親ウィンドウでも MDI 子ウィンドウでもない
  : FS_MDICHILD
    フォームは MDI 子ウィンドウである
  : FS_MDIFORM
    フォームは MDI 親ウィンドウである
  : FS_STAY_ON_TOP
    このフォームは，デスクトップの一番上，およびプロジェクトの他のフォーム ( %c:form_style% が %c:FS_STAY_ON_TOP% に設定されているフォームを除いた他のフォーム ) の上にくる。 %c:FS_STAY_ON_TOP% のフォームが他のフォームを起動する場合は，どちらか一方のフォームが一番上にくる

  フォームが MDI アプリケーションのメインフォームの場合， %c:form_style% は %c:FS_MDIFORM% に設定しなければならない。

  : 注意
    実行時に %c:form_style% の値をなるべく変更しないようにすること。 ( そんなこと言われたって .. )

: help_file : String
  アプリケーションがヘルプを表示するのに使うファイルの名前

  %c:help_file% は， Windows ヘルプシステムで使うヘルプファイルを持つフォームで使う。 Windows は %c:help_file% で指定したファイルからヘルプトピックを選択する。

  : 注意
    このプロパティを指定するとフォームに固有のヘルプファイルを定義することができる。アプリケーション全体のヘルプファイルは Phi::Application#help_file で指定する。 Phi::Application#help_file を指定すると，アプリケーション終了時にヘルプウィンドウの後片付けが行われる。

: icon : Phi::Icon
  フォームを最小化したときに表示されるアイコン

  %c:icon% プロパティを設定すると，フォーム用のアイコンを提供できます。 %c:Icon% プロパティが設定されていない場合， Windows は，フォームが最小化されたときにデフォルトのアイコンを提供します。

: key_preview : Boolean
  フォームがアクティブコントロールより前にキーボードイベントを受け取るかどうか

  %c:key_preview% が %c:true% の場合，キーボードイベントはアクティブコントロール ( #active_control で指定 ) で発生する前にフォームで発生する。

  %c:key_preview% が %c:false% の場合，キーボードイベントはアクティブコントロールでのみ発生する。 ( デフォルト )

  Tab ， BackTab ，矢印キーなどの移動キーはキーボードイベントを発生させないので %c:key_preview% は無効だ。

: menu : Phi::MainMenu
  フォームのメインメニュー

  設計時に， menu は，最初にフォームに追加された Phi::MainMenu コンポーネントに設定される。

: modal_result : Fixnum
  モード付きダイアログとして使われているフォームの値

  %c:modal_result% を使うと，モード付きで表示されているフォームを閉じることができます。

  %c:modal_result% のデフォルト値は %c:MR_NONE% である。 %c:modal_result% を 0 以外の値に設定すると，モード付きフォームを閉じることができる。 %c:modal_result% に割り当てた値はモード付きフォームを表示するのに使った #show_modal 関数呼び出しの戻り値になります。

  : 注意
    このプロパティは Phi::Button オブジェクトなど，一部のコンポーネントによって自動的に変更されます。詳細は， Phi::Button#modal_result を参照のこと。

: old_create_order
  #on_create および #on_destroy がいつ発生するか

  %c:old_create_order% が %c:false% ( デフォルト ) ならば， #on_create は，すべてのコンストラクタが終了した後で ( #after_construction の中から ) 発生し， #on_destroy イベントはすべてのデストラクタが呼び出される前に ( #before_destruction の中から ) 発生する。

  このタイミングは， Delphi のバージョン 3 以前の場合と異なる。バージョン 3 以前では， #on_create は %c:CustomForm% コンストラクタが実行されたときに発生し， #on_destroy は %c:CustomForm% デストラクタが実行されたときに発生した。フォームのコンストラクタおよびデストラクタから #on_create および #on_destroy が発生する必要があるアプリケーションは， %c:old_create_order% を %c:true% に設定する。

: parent : Phi::Control
  フォームを含むウィンドウコントロール

  parent は，別のフォームにコントロールを埋め込むときに使われる。 parent を変更すると，新しいコンテナにフォームを移動できる。

  デスクトップに直接表示されるフォームの parent は Phi::Screen である。

: pixels_per_inch : Fixnum
  フォーム設計時に使われたシステムのシステムフォントの比率

  pixels_per_inch は，現在の画面解像度に対するフォームのスケーリングを変更できる。 pixels_per_inch のデフォルト値を変更すると，画面解像度によって比率が変わってしまう。 #scaled を %c:true% に設定しないと pixels_per_inch 値を変更しても効果はない。

: position : Fixnum
  フォームのサイズと配置

  : PO_DESIGNED
    フォームは設計時と同じ画面上の位置，高さ，幅で表示される
  : PO_DEFAULT
    フォームは Windows が決める画面上の位置，高さ，幅で表示される。フォームはアプリケーションを複数起動するたびに少しずつ右下へ移動する。画面の解像度に関係なくフォームの右側は常に画面の右端に近く，フォームの下端は常に画面の下端に近くなる
  : PO_DEFAULT_POS_ONLY
    フォームは設計時にフォームを作成したサイズで表示されるが，画面上の位置は Windows が選択する。フォームはアプリケーションを複数起動するたびに少しずつ右下へ移動する。同じサイズのまま全体が画面上に表示されるようにフォームをそれ以上右下へ移動できなくなると，画面の左上隅にフォームが表示される
  : PO_DEFAULT_SIZE_ONLY
    フォームは設計時の位置に表示されるが，サイズは Windows が選択する。画面の解像度に関係なくフォームの右側は常に画面の右端に近く，フォームの下端は常に画面の下端に近くなる
  : PO_SCREEN_CENTER
    フォームは設計時のサイズで表示されるが，画面の中央に配置される。マルチモニターアプリケーションの場合， #default_monitor で指定されたモニターの中央に表示される
  : PO_DESKTOP_CENTER
    フォームは設計時のサイズのままで，画面の中央に配置される。マルチモニターアプリケーションの場合，調整は行われない
  : PO_MAIN_FORM_CENTER
    Apollo では使えません。 %c:PO_SCREEN_CENTER% と同じ扱いになります。Apollo では Main Form は(GC とのからみで) 常に nil なので，そのようになります。
    Delphi では次のようなものでした：フォームは設計時のサイズのままで，アプリケーションのメインフォームの中央に配置される。マルチモニターアプリケーションの場合，調整は行われない。この位置は，二次フォームでのみ使用する必要がある。メインフォームで設定した場合には， %c:PO_SCREEN_CENTER% と同じ処理が行われる
  : PO_OWNER_FORM_CENTER
    Apollo では使えません。 %c:PO_SCREEN_CENTER% と同じ扱いになります。Apollo では owner は(GC とのからみで) 常に nil なので，そのようになります。
    Delphi では次のようなものでした：フォームは設計時のサイズのままで， %c:owner% プロパティで指定したフォームの中央に配置される。 %c:owner% プロパティがフォームを指定していない場合には， %c:PO_MAIN_FORM_CENTER% と同じ処理が行われる

: print_scale : Fixnum
  フォームの印刷時の比率

  : PO_NONE
    画面に表示されたフォームをプリンタの解像度で印刷する
  : PO_PROPORTIONAL
    フォームは画面上のサイズと同じサイズになるように印刷される (WYSIWYG) 。フォームイメージは，印刷されるイメージが画面上に見えるサイズと同じになるように拡大／縮小される
  : PO_PRINT_TO_FIT
    フォームは同じ画面比率を使うが，印刷ページにちょうど収まるサイズで印刷される

: scaled : Boolean
  フォームサイズを Pixels_Per_Inch# の値に基づいて変更するかどうか

  %c:scaled% が %true% で %pixels_per_inch% の値が現在のシステム設定と異なる場合，フォームは新しいサイズにスケール変更される。

  %c:scaled% が %false% の場合は，スケール変更はされない。

: visible : Boolean
  フォームを画面上に表示するかどうか

  %c:visible% が %c:true% ならば，フォームが表示される。ただし，他のフォームに隠れていると，隠れた部分は隠れたままだ。

  %c:visible% が %c:false% ならば，フォームは表示されない。

  #show および #show_modal は %c:visible% を %c:true% に設定して，開いているすべてのウィンドウの前面にフォームを表示する。

: window_state : Fixnum
  画面へのフォームの表示のしかた

  : WS_NORMAL
    通常の状態で表示する
  : WS_MINIMIZED
    最小化して表示する
  : WS_MAXIMIZED
    最大化して表示する

1.1.1. scroll 関連

: auto_scroll : Boolean
  スクロールウィンドウコントロールが小さくてすべてのコントロールを表示できないときに，スクロールバーを自動的に表示するかどうか

: horz_scroll_bar : ControlScrollBar
  スクロールウィンドウコントロール用の水平スクロールバー

: vert_scroll_bar : ControlScrollBar
  スクロールウィンドウコントロール用の垂直スクロールバー

1.1.1. MDI 関連

: active_mdichild : Form
  フォーカスがある MDI 子フォーム

  フォームが MDI 親フォームでない，つまり，フォームの #form_style が %c:FS_MDIFORM% でない場合， #active_mdichild は %c:nil% を返す。

: client_handle : Fixnum
  フォームの MDI の内部クライアントウィンドウのハンドル

  %c:client_handle% が有効なのは #form_style が %c:FS_MDIFORM% に設定されている MDI 親フォームだけだ。

  : 注意
    フォームウィンドウ自身へのハンドルを取得するには， #handle を使う。

: mdichild_count
  開いている MDI 子フォームの数

  %c:mdichild_count% が有効なのは #form_style が %c:FS_MDIFORM% に設定されている MDI 親フォームだけだ。

: mdichildren(i): Form
  すべての MDI 子フォームへのインデックス付きアクセスを提供する。

  %v:i% にはアクセスする子フォームのインデックスを指定する。

  MDI 子フォームの順序は，別の MDI フォームがアクティブになると変わる。初期状態では，フォームは作成した順序でリストされ，新しいフォームは配列の最後に追加される。しかし， MDI 子フォームはアクティブになると，常にリストの先頭に移動する。そのため， %v:i% を使うと，配列内のすべてのフォームをインデックス化できるが，特定のフォームを参照することはできない。

  %c:mdichildren% が有効なのは #form_style が %c:FS_MDIFORM% に設定されている MDI フレームだけだ。

: window_menu : MenuItem
  MDI 親フォームの［ウィンドウ］メニュー

  ［ウィンドウ］メニューは MDI アプリケーションでの標準メニューである。［ウィンドウ］メニューには，［重ねて表示］，［アイコンの整列］，［並べて表示］など，ユーザーがアプリケーションのウィンドウを管理できるようにするコマンドがある。

  また，［ウィンドウ］メニューの下部にはアプリケーションで現在開いている子ウィンドウが示される。ユーザーがメニューからウィンドウの 1 つを選択すると，選択したウィンドウがアプリケーションでのアクティブウィンドウになる。

  このメニューは一般に［ウィンドウ］メニューと呼ばれますが，どのような名前にもできる。ただし，その名前はメニューバーに表示される既存のメニュー項目のどれかでなくてはならない。開いている子フォームの名前は，実行時に自動的にそのメニューに入る。

  %c:window_menu% が有効なのは #form_style が %c:FS_MDIFORM% に設定されている MDI 親フォームだけだ。

: tile_mode : Fixnum
  #tile が呼び出されたときに MDI 子フォームがどのように配列されるか

  : TB_HORIZONTAL
    各フォームは親フォームの幅の方向に広がる
  : TB_VERTICAL
    各フォームは親フォームの高さの方向に広がる

  #tile_mode が有効なのは #form_style が %c:FS_MDICHILD% に設定されている MDI 子フォームだけだ。

1.1.1. OLE 関連

: object_menu_item : Phi::MenuItem
  OLE オブジェクトの選択に応答する OLE オブジェクトメニュー項目

  %c:object_menu_item% を使うと，フォーム上の OLE オブジェクトを選択または選択解除したときにそれぞれ有効または無効になるメニュー項目を取得または設定できる。

  OLE オブジェクトメニュー項目は， #activate ， #convert などの標準 OLE コマンドのかわりとして使用できる。それらのコマンドは OLE サーバーによって実現される。

: active_ole_control : Phi::Control
  フォーム上のフォーカスの変更に応答する OLE コントロール

  %c:active_ole_control% が nil でない場合，指定した OLE コントロールのユーザーインターフェースは，フォーカスがないときは非アクティブ化される。また，フォームがフォーカスを受け取ったり失ったりすると，指定した OLE コントロールのドキュメントウィンドウがそれぞれアクティブ化，非アクティブ化される。

1.1.1. BiDi 関連

: parent_bi_di_mode : Boolean
  コントロールが親の bi_di_mode を使用するかどうか

  parent が nil で parent_bi_di_mode が true の場合，フォームの bi_di_mode は， Application.bi_di_mode と同じ値に設定される。 parent が nil でなく， parent_bi_di_mode が true の場合，フォームの bi_di_mode は親の bi_di_mode と同じ値に設定される。

  : 注意
    日本語 Windows95/98/NT4 では指定しても意味を持たない。

1.1.1. Monitor 関連

: monitor : Phi::Monitor
  フォームが表示されるモニター

: default_monitor : Fixnum
  フォームが表示されるモニター

  : DM_DESKTOP
    特定のモニターにフォームを位置付ける試みは行われない
  : DM_PRIMARY
    フォームは， Screen#monitors にリストされている最初のモニターに位置付けられる
  : DM_MAIN_FORM
    フォームはアプリケーションのメインフォームと同じモニターに表示される
  : DM_ACTIVE_FORM
    フォームは現在アクティブなフォームと同じモニターに表示される

  : 注意
    DEFAULT_MONITOR は，アプリケーションにメインフォームがない場合は無効だ。

1.1. event handler

: on_activate

: on_close

    on_close イベントは，フォームを閉じたときに発生します。

    on_close イベントの前に on_close_query イベントが発生します。閉じてよいかどうかの判断は on_close_query で行います。

    on_close イベントハンドラを記述すると，フォームを閉じたときに特別な処理が実行されるようにすることができます。on_close イベントはフォームを閉じようとしたときに呼び出されるイベントハンドラを指定します。たとえば，データ入力フォームを閉じる前にフォーム内のすべての項目に有効な内容が入っているかどうかをテストするハンドラを on_close で指定できます。

    フォームは #close メソッドによって，またはユーザーがフォームのシステムメニューで［閉じる］を選択したときに閉じます。

  : action : Fixnum
    action の値はフォームを実際に閉じるどうかを決めます。

    : CA_NONE
      フォームを閉じることができないので何も起きない
    : CA_HIDE
      フォームは閉じないで単に隠される。アプリケーションは隠れたフォームに引き続きアクセスできる
    : CA_FREE
      Apollo では %c:CA_HIDE% と同じ扱いになります。
      フォームは閉じ，そのフォームに割り当てたすべてのメモリが解放される
    : CA_MINIMIZE
      フォームは閉じないでアイコン化される。MDI 子フォームの場合はこれがデフォルトである

    フォームが MDI 子フォームで，BorderIcons プロパティが biMinimize ならば，Action のデフォルト値は caMinimize です。MDI 子フォームにこの設定がない場合は，Action のデフォルト値は，ユーザーがフォームを閉じようとする前に何も起きないことを示す caNone です。
    フォームが SDI 子フォームならば，Action のデフォルト値は caHide です。

: on_close_query

    on_close_query イベントは， #close メソッドが呼び出されたとき，またはユーザーがフォームのシステムメニューで［閉じる］を選択したときに発生します。

    on_close_query イベントハンドラを記述すると，どのような状態のときにフォームを閉じることができるかを指定できます。 on_close_query イベントハンドラはフォームのクローズが可能かどうかを決める論理型の戻り値を返さなければなりません。 false を返すとクローズ処理を中止します。true を返せばクローズ処理が継続し、次に on_close イベントが発生します。

    on_close_query では閉じるか閉じないかの決定だけを行い、実際に閉じるときに必要な処理が必要な場合は on_close で記述します。

  : 例
--ruby
require "phi" ; include Phi
require "dialogs"
form = Form.new :form, "on_close_query .. click [x]"
form.on_close_query = proc{
  ans = message_dlg('Close the form?',
    MT_CONFIRMATION,[MB_OK,MB_CANCEL])
  if ans == MR_CANCEL
    p "remain"
    ret = false
  else 
    p "the end"
    ret = true
  end
  ret
}
form.on_close = proc{
  p "closing.."
}
form.show ; mainloop
--

: on_create
: on_deactivate
: on_destroy
: on_help
: on_hide
: on_paint
: on_short_cut
: on_show
