OnEvent

GUIウィンドウやコントロールからイベントが発生したときに呼び出される関数やメソッドを登録します。

Gui.OnEvent(EventName, Callback , AddRemove)
GuiCtrl.OnEvent(EventName, Callback , AddRemove)

パラメータ

EventName

型:文字列

イベントの名前です。下記「イベント」をご覧ください。

Callback

型:文字列または関数オブジェクト

イベントが発生したときに呼び出す関数、メソッド、またはオブジェクトを指定します。

GUIにイベントシンクがある場合(つまりGui()EventObjパラメータが指定されている場合)、このパラメータはイベントシンクに属するメソッドの名前であってもよい。それ以外の場合は、このパラメータは関数オブジェクトでなければならない。

For details about the parameters, return value, naming, and more, see the following sections.

AddRemove

型:整数

省略されたときは、初期値は 1 です。それ以外の場合は、次のいずれかの番号を指定してください:

コールバックパラメータ

コールバックが名前で登録されたメソッドである場合、その隠されたこのパラメータはシームレスにイベントシンクオブジェクト(つまり、そのメソッドが属するオブジェクト)を受け取ります。このパラメータは、本書のパラメータ一覧には表示されていません。

Callbackはオブジェクトにできるので、パラメータリストの先頭に追加のパラメータを挿入して、別の関数を呼び出すBoundFuncオブジェクトにすることができます。これはOnEventに特化したものではなく、一般的なテクニックなので、このドキュメントの他の部分では通常無視されます。

コールバックの最初の明示的なパラメータは、イベントを発生させたGuiまたはGuiControlオブジェクトです。唯一の例外は、Guiがそれ自身のイベントを処理するとき、このパラメータは省略されることです。なぜなら、thisはすでにGuiへの参照を含んでいるからです。

多くのイベントは、各イベントで説明されているように、イベントに関する追加のパラメータを渡します。

As with all methods or functions called dynamically, the callback is not required to declare parameters which the callback itself does not need, but in this case an asterisk must be specified as the final parameter, e.g. MyCallback(Param1, *). イベントにコールバックが宣言した以上のパラメータがある場合、それらは単に無視されます(コールバックがvariadicでない限り)。

コールバックは、追加のパラメータがオプションとして宣言されている場合(そしてその場合のみ)、イベントが提供するよりも多くのパラメータを宣言することができます。しかし、オプションのパラメータを使用することは推奨されません。プログラムの将来のバージョンでは、追加のパラメータでイベントを拡張する可能性があり、その場合、オプションのパラメータはデフォルト値を受け取らなくなります。

コールバックの戻り値

イベントに対して複数のコールバックが登録されている場合、コールバックは空でない値を返し、残りのコールバックが呼ばれないようにすることができます。

戻り値は、特定のイベントに対して追加の意味を持つ場合があります。例えば、Closeコールバックは、GUIウィンドウが閉じないように、0以外の数値(trueなど)を返すことができます。

Callback Name

慣例により、以下の各イベントの構文は、わかりやすくするために、ObjectType_EventNameという形の関数名で示されています。スクリプトはこの規約に従う必要はなく、任意の有効な関数名を使用することができます。

スレッド

各イベントコールバックは新しいスレッドで呼び出されるため、SendModeなどの設定のデフォルト値で新たにスタートします。これらのデフォルトは、スクリプト起動時に変更することができます。

GUIスレッドが起動すると、そのスレッドの最後に見つかったウィンドウがGUIウィンドウそのものとしてスタートします。これにより、WinGetStyleWinSetTransparentControlGetFocusなどのウィンドウやコントロールに関する関数が、GUIウィンドウ自体を操作する際に(たとえそれが隠されていても)WinTitleWinTextを省略することができます。

注意書きがある場合を除き、各イベントは1つのオブジェクトにつき1スレッドずつに制限されています。そのイベントによって開始された前のスレッドが終了する前にイベントが発生した場合、通常、そのイベントは破棄されます。これを防ぐには、コールバックの最初の行にCriticalを使用します(ただし、この場合、ホットキーの押下など他のスレッドもバッファリング/ディファーされます)。

GUIを破壊する

GUIが破壊されると、すべてのイベントコールバックが解放されます。したがって、イベントのディスパッチ中にGUIが破壊された場合、その後のイベントコールバックは呼び出されません。わかりやすくするために、コールバックはGUIを破壊した後、空でない値を返すようにします。

イベント

Guiオブジェクトがサポートしているイベントは次のとおりです:

イベント育てたのは...
Close窓が閉まっています。
ContextMenuユーザーはウィンドウ内で右クリックするか、MenuまたはShift+F10を押してください。
DropFilesファイル/フォルダーをウィンドウにドラッグ&ドロップします。
EscapeGUIウィンドウがアクティブな状態で、ユーザーがEscを押した場合。
Sizeウィンドウのサイズ変更、最小化、最大化、復元を行います。

GuiControlオブジェクトは、コントロールの種類に応じて、以下のイベントをサポートしています:

イベント育てたのは...
Changeコントロールの値が変化します。
Clickコントロールがクリックされます。
DoubleClickコントロールがダブルクリックされます。
ColClickListViewのカラムヘッダーの1つがクリックされました。
ContextMenuコントロールにキーボードフォーカスがある状態で、ユーザーがコントロールを右クリックするか、MenuまたはShift+F10を押した場合。
Focusコントロールがキーボードフォーカスを獲得します。
LoseFocusコントロールはキーボードフォーカスを失います。
ItemCheckListViewやTreeViewの項目がチェックされているか、チェックされていないか。
ItemEditListViewやTreeViewのアイテムのラベルは、ユーザーが編集することができます。
ItemExpandTreeViewの項目が展開または折りたたまれている。
ItemFocusListViewでフォーカスされた項目が変化します。
ItemSelectListViewまたはTreeViewの項目が選択された場合、またはListViewの項目が非選択の場合。

Window Events

Close

ユーザーまたは他のプログラムが、タイトルバーのXボタンを押す、システムメニューから「閉じる」を選択する、またはWinCloseを呼び出すなどして、ウィンドウを閉じようとしたときに起動されるものです。

Gui_Close(GuiObj)

デフォルトでは、コールバックが戻った後、またはコールバックが登録されていない場合、ウィンドウは自動的に非表示になります。コールバックは1(またはtrue)を返すことでこれを防ぐことができ、残りのコールバックが呼ばれるのを防ぐこともできます。コールバックは、GuiObj.Hideを呼び出すことでウィンドウをすぐに隠すことができ、GuiObj.Destroyを呼び出すことでウィンドウを破壊することができます。

例えば、このGUIでは、閉じる前に確認のプロンプトが表示されます:

MyGui := Gui()
MyGui.AddText("", "Press Alt+F4 or the X button in the title bar.")
MyGui.OnEvent("Close", MyGui_Close)
MyGui_Close(thisGui) {  ; このパラメータの宣言は任意です。
    if MsgBox("Are you sure you want to close the GUI?",, "y/n") = "No"
        return true  ; true = 1
}
MyGui.Show

ContextMenu

タイトルバーとメニューバーを除くウィンドウ内の任意の場所を右クリックしたときに起動します。また、MenuShift+F10を押したときにも反応し、起動します。

Gui_ContextMenu(GuiObj, GuiCtrlObj, Item, IsRightClick, X, Y)
GuiCtrlObj

型:オブジェクトまたは文字列(空)

The GuiControl object of the control that received the event (blank if none).

Item

型:整数

ListBox、ListView、TreeViewがコンテキストメニューのターゲットである場合(GuiCtrlObjで決定)、Itemはコントロールのどのアイテムをターゲットとするかを指定します。

ListBox: The position number of the currently focused item. 標準的なリストボックスでは、右クリックされたときに項目にフォーカスが当たらないので、クリックされた項目でない可能性があることに注意してください。

ListView and TreeView: For right-clicks, Item contains the clicked item's row number or ID (or 0 if the user clicked somewhere other than an item). For Menu and Shift+F10, Item contains the selected item's row number or ID.

IsRightClick

型:整数(ブーリアン)

以下のいずれかの値:

X, Y

型:整数

スクリプトがメニューを表示する位置のX、Y座標(例:MyContextMenu.Show X, Y)です。座標は、ウィンドウのクライアント領域の左上隅からの相対座標です。

他の多くのGUIイベントとは異なり、ContextMenuイベントは複数のスレッドを同時に持つことができます。

各コントロールは独自のContextMenuイベントコールバックを持つことができ、Guiオブジェクトに登録されたどのコールバックよりも先に呼び出されます。コントロール固有のコールバックでは、GuiObjパラメータは省略されますが、その他のパラメータはすべて同じです。

注:EditMonthCalコントロールはそれぞれ独自のコンテキストメニューを持っているため、そのうちの1つを右クリックしてもContextMenuイベントは起動しません。

DropFiles

ドラッグ&ドロップ操作でファイルやフォルダがウィンドウにドロップされるたびに起動します(ただし、このコールバックがすでに実行されている場合、ドロップイベントは無視されます)。

Gui_DropFiles(GuiObj, GuiCtrlObj, FileArray, X, Y)
GuiCtrlObj

型:オブジェクトまたは文字列(空)

The GuiControl object of the control upon which the files were dropped (blank if none).

FileArray

型:配列

ファイル名の配列。FileArray[1]は最初のファイル、FileArray.Lengthはファイル数を返す。forループを使用して、ファイルを繰り返し処理することができます:

Gui_DropFiles(GuiObj, GuiCtrlObj, FileArray, X, Y) {
    for i, DroppedFile in FileArray
        MsgBox "File " i " is:`n" DroppedFile
}
X, Y

型:整数

ファイルがドロップされた場所のX、Y座標(ウィンドウのクライアント領域の左上隅からの相対座標)。

Escape

GUIウィンドウがアクティブな状態で、ユーザーがEscを押したときに起動されます。

Gui_Escape(GuiObj)

デフォルトでは、Escを押しても何の効果もありません。既知の制限:ウィンドウの最初のコントロールが無効になっている場合(コントロールの種類によって異なる可能性があります)、Escapeイベントは起動されません。この効果を生み出す他の状況もあるかもしれません。

Size

ウィンドウのサイズ変更、最小化、最大化、復元時に起動されます。

Gui_Size(GuiObj, MinMax, Width, Height)
MinMax

型:整数

以下のいずれかの値:

最大化されたウィンドウは、復元/最大化解除せずにサイズを変更することができるため、値が1の場合、必ずしもユーザーがウィンドウを最大化したことに応じてこのイベントが発生したことを意味しないことに注意します。

Width, Height

型:整数

ウィンドウのクライアント領域(タイトルバー、メニューバー、ボーダーを除く領域)の新しい幅と高さを指定します。

スクリプトは、Size イベントを使用して、ユーザーによるウィンドウのサイズ変更に対応してコントロールの位置を変更したり、サイズを変更したりすることができます。

ウィンドウのサイズが変更された場合(スクリプトでも)、Sizeイベントがすぐに発生しない場合があります。他のウィンドウイベントと同様に、現在のスレッドが割り込み不可能な場合、スレッドが割り込み可能になるまで、Sizeイベントは発生しません。スクリプトがウィンドウのサイズを変更したばかりの場合は、この例に従ってSizeイベントを直ちに発生させるようにしてください:

Critical"Off"  ; Critical "On"が一度も使われなかったとしても。
Sleep -1

Gui.Showは、自動的にSleep -1を行うので、その場合は一般にSleepを呼び出す必要はない。

Control Events

Change

コントロールの値が変化したときに発生します。

Ctrl_Change(GuiCtrlObj, Info)
Info

型:整数

Slider: A numeric value indicating how the slider moved. For details, see Detecting Changes.

それ以外のコントロールについては、現在、Infoは意味を持ちません。

コントロールの新しい値を取得するには、GuiCtrlObj.Valueを使用します。

適用:DDLComboBoxListBoxEditDateTimeMonthCalHotkeyUpDownSliderTab

Click

コントロールがクリックされたときに発生します。

Ctrl_Click(GuiCtrlObj, Info)
Link_Click(GuiCtrlObj, Info, Href)
Info

型:整数

ListView:クリックされた項目の行番号、またはマウスが項目上にない場合は0を指定します。

TreeView:クリックされた項目のID、またはマウスが項目上にない場合は0を指定します。

Link:リンクにID属性がある場合は文字列、ない場合はリンクのインデックス(整数値)です。

StatusBar:クリックした部分の品番(ただし、バー右側のサイズグリップ付近をクリックした場合、品番は非常に大きな整数になる可能性があります)。

それ以外のコントロールについては、現在、Infoは意味を持ちません。

Href

型:文字列

Link:リンクのHREF属性です。なお、クリックイベントコールバックが登録されている場合、HREF属性は自動的に実行されません。

適用:TextPicButtonCheckBoxRadioListViewTreeViewLinkStatusBar

DoubleClick

コントロールがダブルクリックされたときに発生します。

Ctrl_DoubleClick(GuiCtrlObj, Info)
Info

型:整数

ListViewTreeViewStatusBarClickイベントと同じです。

ListBox: The position number of the currently focused item. 最後の項目の下の空白をダブルクリックすると、通常、最後の項目がフォーカスされ、選択範囲がそのままになります。

適用:TextPicButtonCheckBoxRadioComboBoxListBoxListViewTreeViewStatusBar

ColClick

ListViewのカラムヘッダーの1つがクリックされたときに発生します。

Ctrl_ColClick(GuiCtrlObj, Info)
Info

型:整数

クリックされた1ベースの列番号です。これは、カラムが作成されたときに割り当てられたオリジナルの番号です。つまり、ユーザーによるカラムのドラッグ&ドロップは反映されません。

適用:ListView

ContextMenu

コントロールにキーボードフォーカスがある状態で、ユーザーがコントロールを右クリックするか、MenuまたはShift+F10を押したときに発生します。

Ctrl_ContextMenu(GuiCtrlObj, Item, IsRightClick, X, Y)

詳しくは、「ContextMenu」をご覧ください。

適用:EditMonthCal(およびComboBox内のEditコントロール)以外のすべてのコントロールは、独自の標準コンテキストメニューを持っています。

Focus / LoseFocus

コントロールがキーボードフォーカスを獲得したとき、または失ったときに発生します。

Ctrl_Focus(GuiCtrlObj, Info)
Ctrl_LoseFocus(GuiCtrlObj, Info)
Info

Reserved.

適用:ButtonCheckBoxRadioDDLComboBoxListBoxListViewTreeViewEditDateTime

非対応:HotkeySliderTab および Link。なお、TextPicMonthCalUpDownStatusBarコントロールは、キーボードフォーカスを受け付けません。

ItemCheck

ListViewまたはTreeViewのアイテムがチェックされたとき、またはチェックされていないときに発生します。

Ctrl_ItemCheck(GuiCtrlObj, Item, Checked)

適用:ListViewTreeView

ItemEdit

ListView または TreeView のアイテムのラベルがユーザーによって編集されたときに発生します。

Ctrl_ItemEdit(GuiCtrlObj, Item)

項目のラベルは、コントロールのオプションで-ReadOnlyが使用されている場合のみ編集可能です。

適用:ListViewTreeView

ItemExpand

TreeView のアイテムが展開または折りたたまれたときに発生します。

Ctrl_ItemExpand(GuiCtrlObj, Item, Expanded)

適用:TreeView

ItemFocus

ListView でフォーカスされている項目が変更されたときに発生します。

Ctrl_ItemFocus(GuiCtrlObj, Item)

適用:ListView

ItemSelect

ListViewまたはTreeViewのアイテムが選択されたとき、またはListViewのアイテムが選択解除されたときに発生します。

ListView_ItemSelect(GuiCtrlObj, Item, Selected)
TreeView_ItemSelect(GuiCtrlObj, Item)

適用:ListViewTreeView

ListView:このイベントは、選択解除や選択された項目ごとに1回発生するので、ユーザーの1回の操作に対して複数回発生させることができる。

その他のイベント

その他のタイプのGUIイベントは、OnNotifyOnCommandOnMessageで検出し、対応することができます。例えば、ユーザーがウィンドウ内の特定のコントロールにマウスを移動すると、スクリプトはToolTipを介してコンテキストセンシティブヘルプを表示することができます。これは、GUI ToolTipの例で実証されています。