Phi::Form

class methods

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

methods

close : nil

フォームを閉じる。

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

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

on_close_query が true ならば， on_close が呼ばれる。

注意

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

show : nil

フォームを表示する。

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

hide : nil

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

hide は visible を false に設定する。

show_modal : Fixnum

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

properties

action : Phi::BasicAction

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

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

active : Boolean

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

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

active_control : Phi::Control

フォーム上でフォーカスがあるコントロール

アプリケーション内で一度にフォーカスを持つことができるのは 1 つのコントロールだけである。フォームにフォーカスがない場合は，フォームがフォーカスを受け取ったときにフォーカスを受け取ることになるフォーム上のコントロールを示す。

注意

フォーカスが別のコントロールに移ると， on_exit が発生する前に active_control の値が更新される。

border_icons : Fixnum

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

BI_SYSTEMMENU

コントロールメニュー ( システムメニューともいう ) をフォームに表示する

BI_MINIMIZE

アイコン化ボタンをフォームに表示する

BI_MAXIMIZE

最大表示ボタンをフォームに表示する

BI_HELP

border_style が BS_DIALOG の場合，または BI_MINIMIZE と BI_MAXIMIZE が除外された場合，フォームのタイトルバーには疑問符が表示され，クリックするとカーソルが CR_HELP に変更される。そうでない場合は非表示になる

注意

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

border_style : Fixnum (BorderStyle)

フォーム境界の体裁と動作

BS_DIALOG

サイズ変更不可。標準のダイアログボックス境界

BS_SINGLE

サイズ変更不可。一重境界線

BS_NONE

サイズ変更不可。可視境界線なし

BS_SIZEABLE

標準のサイズ変更可能境界

BS_TOOL_WINDOW

BS_SINGLE と同じだがキャプションが小さい

BS_SIZE_TOOL_WIN

BS_SIZEABLE と同じだがキャプションが小さい

注意

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

client_rect : Phi::Rect

フォームのクライアント領域

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

client_rect は

rect(0, 0, client_width, client_height)

と同等。

client_width : Fixnum

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

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

client_height : Fixnum

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

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

canvas : Phi::Canvas

フォームの描画領域

canvas を使うと，フォームのクライアント領域を描画できる。 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

フォームは ( フォーカスを受け取った，あるいは，アプリケーションがアクティブになったために ) CM_ACTIVATE メッセージを受け取ったが，まだ activate を呼び出していない ( そして，まだ on_active を呼んでいない ) 。

form_style : Fixnum

フォームのスタイル

FS_NORMAL

フォームは MDI 親ウィンドウでも MDI 子ウィンドウでもない

FS_MDICHILD

フォームは MDI 子ウィンドウである

FS_MDIFORM

フォームは MDI 親ウィンドウである

FS_STAY_ON_TOP

このフォームは，デスクトップの一番上，およびプロジェクトの他のフォーム ( form_style が FS_STAY_ON_TOP に設定されているフォームを除いた他のフォーム ) の上にくる。 FS_STAY_ON_TOP のフォームが他のフォームを起動する場合は，どちらか一方のフォームが一番上にくる

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

注意

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

help_file : String

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

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

注意

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

icon : Phi::Icon

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

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

key_preview : Boolean

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

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

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

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

menu : Phi::MainMenu

フォームのメインメニュー

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

modal_result : Fixnum

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

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

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

注意

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

old_create_order

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

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

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

parent : Phi::Control

フォームを含むウィンドウコントロール

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

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

pixels_per_inch : Fixnum

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

pixels_per_inch は，現在の画面解像度に対するフォームのスケーリングを変更できる。 pixels_per_inch のデフォルト値を変更すると，画面解像度によって比率が変わってしまう。 scaled を 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 では使えません。 PO_SCREEN_CENTER と同じ扱いになります。Apollo では Main Form は(GC とのからみで) 常に nil なので，そのようになります。
Delphi では次のようなものでした：フォームは設計時のサイズのままで，アプリケーションのメインフォームの中央に配置される。マルチモニターアプリケーションの場合，調整は行われない。この位置は，二次フォームでのみ使用する必要がある。メインフォームで設定した場合には， PO_SCREEN_CENTER と同じ処理が行われる

PO_OWNER_FORM_CENTER

Apollo では使えません。 PO_SCREEN_CENTER と同じ扱いになります。Apollo では owner は(GC とのからみで) 常に nil なので，そのようになります。
Delphi では次のようなものでした：フォームは設計時のサイズのままで， owner プロパティで指定したフォームの中央に配置される。 owner プロパティがフォームを指定していない場合には， PO_MAIN_FORM_CENTER と同じ処理が行われる

print_scale : Fixnum

フォームの印刷時の比率

PO_NONE

画面に表示されたフォームをプリンタの解像度で印刷する

PO_PROPORTIONAL

フォームは画面上のサイズと同じサイズになるように印刷される (WYSIWYG) 。フォームイメージは，印刷されるイメージが画面上に見えるサイズと同じになるように拡大／縮小される

PO_PRINT_TO_FIT

フォームは同じ画面比率を使うが，印刷ページにちょうど収まるサイズで印刷される

scaled : Boolean

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

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

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

visible : Boolean

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

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

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

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

window_state : Fixnum

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

WS_NORMAL

通常の状態で表示する

WS_MINIMIZED

最小化して表示する

WS_MAXIMIZED

最大化して表示する

scroll 関連

auto_scroll : Boolean

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

horz_scroll_bar : ControlScrollBar

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

vert_scroll_bar : ControlScrollBar

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

MDI 関連

active_mdichild : Form

フォーカスがある MDI 子フォーム

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

client_handle : Fixnum

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

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

注意

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

mdichild_count

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

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

mdichildren(i): Form

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

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

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

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

window_menu : MenuItem

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

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

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

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

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

tile_mode : Fixnum

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

TB_HORIZONTAL

各フォームは親フォームの幅の方向に広がる

TB_VERTICAL

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

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

OLE 関連

object_menu_item : Phi::MenuItem

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

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

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

active_ole_control : Phi::Control

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

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

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 では指定しても意味を持たない。

Monitor 関連

monitor : Phi::Monitor

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

default_monitor : Fixnum

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

DM_DESKTOP

特定のモニターにフォームを位置付ける試みは行われない

DM_PRIMARY

フォームは， Screen#monitors にリストされている最初のモニターに位置付けられる

DM_MAIN_FORM

フォームはアプリケーションのメインフォームと同じモニターに表示される

DM_ACTIVE_FORM

フォームは現在アクティブなフォームと同じモニターに表示される

注意

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

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 では 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 で記述します。

例

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