Menu/MenuBar Object

Provides an interface to create and modify a menu or menu bar, add and modify menu items, and retrieve information about the menu or menu bar.

class Menu extends Object

メニューオブジェクトは、ポップアップメニューの定義、変更、表示に使用します。Menu()MenuFromHandleおよびA_TrayMenuは、この型のオブジェクトを返す。

class MenuBar extends Menu

MenuBarオブジェクトは、Gui.MenuBarで使用するメニューバーの定義や修正に使用します。MenuBar()で作成します。MenuFromHandleは、メニューバーハンドルが与えられた場合、このタイプのオブジェクトを返します。

"Menu"はクラスそのものであるため、以下ではあらゆるMenuオブジェクトのプレースホルダーとして使用します。

メニューオブジェクトは、Objectから継承されるメソッドとプロパティに加えて、以下の定義済みのメソッドとプロパティを持ちます。

目次

静的メソッド

Call

新しい Menu または MenuBar オブジェクトを作成します。

MyMenu := Menu()
MyMenuBar := MenuBar()
MyMenu := Menu.Call()
MyMenuBar := MenuBar.Call()

メソッド

Add

メニュー項目を追加または変更します。

MyMenu.Add(MenuItemName, CallbackOrSubmenu, Options)

パラメータ

MenuItemName

型:文字列

The text to display on the menu item, or the position of an existing item to modify. MenuItemName」を参照。

CallbackOrSubmenu

型:機能オブジェクトまたはメニュー

The function to call as a new thread when the menu item is selected, or a reference to a Menu object to use as a submenu.

This parameter is required when creating a new item, but optional when updating the options of an existing item.

コールバックは3つのパラメーターを受け取り、以下のように定義できる:

MyCallback(ItemName, ItemPos, MyMenu) { ...

パラメータに与える名前は重要ではないが、以下の値が順次割り当てられる:

  1. The name of the menu item.
  2. The position number of the menu item.
  3. The Menu object of the menu to which the menu item was added.

対応する情報が不要な場合、コールバックのパラメータリストの最後から1つ以上のパラメータを省略することができますが、この場合、MyCallback(Param1, *)のように、最後のパラメータとしてアスタリスクを指定する必要があります。

Options

型:文字列

If blank or omitted, it defaults to no options. Otherwise, specify one or more options from the list below (not case-sensitive). 各オプションと次のオプションはスペースまたはタブで区切る。オプションを削除する場合は、オプションの前にマイナス記号を付けます。オプションを追加する場合は、プラス記号を使用することができますが、必須ではありません。

Pn:Specify for n the menu item's thread priority, e.g. P1. メニュー項目を追加する際にこのオプションを省略した場合、優先順位は標準のデフォルトである0になります。メニュー項目を更新する際に省略した場合、その項目の優先順位は変更されません。優先順位として10進数(16進数ではない)を使用します。

Radio: If the item is checked, a bullet point is used instead of a check mark.

Right: The item is right-justified within the menu bar. This only applies to menu bars, not popup menus or submenus.

Break: The item begins a new column in a popup menu.

BarBreak: As above, but with a dividing line between columns.

To change an existing item's options without affecting its callback or submenu, simply omit the CallbackOrSubmenu parameter.

備考

メニューの追加、新しいサブメニューやコールバックによる更新、通常のメニューからサブメニューへの変換(またはその逆)など、多目的に使えるメソッドです。MenuItemNameがまだ存在しない場合、メニューに追加されます。Otherwise, MenuItemName is updated with the newly specified CallbackOrSubmenu and/or Options.

メニューの区切り線を追加する場合は、3つのパラメータをすべて省略します。

This method always adds new menu items at the bottom of the menu, while the Insert method can be used to insert an item before an existing custom menu item.

AddStandard

標準トレイのメニュー項目を追加します。

MyMenu.AddStandard()

この方法は、トレイメニューや他のメニューでも使用できます。

標準項目は、既存の項目の後に挿入されます。すでにある標準的なメニューは重複せず、足りないものは追加されます。空のメニューでAddStandardを呼び出した後の標準アイテムの名前と位置を下表に示します:

&Open10
&Help2
3
&Window Spy4
&Reload Script5
&Edit Script6
7
&Suspend Hotkeys81
&Pause Script92
E&xit103

コンパイルされたスクリプトには、デフォルトで最後の3つだけが含まれています。AddStandardを呼び出したときにA_AllowMainWindowが1の場合のみ、&Openが含まれます(その場合、3列目に示す位置に1を追加します)。トレイメニューに標準項目が含まれている場合、A_AllowMainWindowが変更されるたびに、&Openが挿入または削除されます。その他のメニューでは、A_AllowMainWindowが 0 の場合、&Openの効果はありません。

各標準項目は、その機能に対応する内部メニュー項目IDを持つが、それ以外は他のメニュー項目と同様に変更または削除することができます。AddStandardは、名前ではなくIDで既存アイテムを検出します。Addメソッドを使用して標準メニューに関連するコールバック関数を変更した場合、そのメニューには新しい一意のIDが割り当てられ、もはや標準メニューとはみなされない。

トレイメニューに&Open項目を追加すると、その項目がまだない場合はデフォルトの項目となります。

Check

Adds a visible checkmark in the menu next to a menu item (if there isn't one already).

MyMenu.Check(MenuItemName)を実行します。

パラメータ

MenuItemName

型:文字列

メニュー項目の名称や位置。MenuItemName」を参照。

Delete

Deletes one or all menu items.

MyMenu.Delete(MenuItemName)を実行します。

パラメータ

MenuItemName

型:文字列

If omitted, all menu items are deleted from the menu, leaving the menu empty. Otherwise, specify the name or position of a menu item. MenuItemName」を参照。

備考

空のメニューはまだ存在するので、それをサブメニューとして使用している他のメニューは、それらのサブメニューを保持します。

セパレータラインを削除するには、メニュー内の位置で識別します。例えば、セパレータの前に2つの項目がある場合は、MyMenu.Delete("3&")を使用します。

デフォルトのメニュー項目を削除した場合、MyMenu.Default := ""を設定した場合と同様の効果が得られます。

Disable

Grays out a menu item to indicate that the user cannot select it.

MyMenu.Disable(MenuItemName)

パラメータ

MenuItemName

型:文字列

メニュー項目の名称や位置。MenuItemName」を参照。

Enable

Allows the user to once again select a menu item if it was previously disabled (grayed out).

MyMenu.Enable(MenuItemName)

パラメータ

MenuItemName

型:文字列

メニュー項目の名称や位置。MenuItemName」を参照。

Insert

指定された項目の前に、新しい項目を挿入します。

MyMenu.Insert(MenuItemName, ItemToInsert, CallbackOrSubmenu, Options)

パラメータ

MenuItemName

型:文字列

If blank or omitted, ItemToInsert will be added at the bottom of the menu. Otherwise, specify the name or position of an existing custom menu item before which ItemToInsert should be inserted. See MenuItemName.

ItemToInsert

型:文字列

The name of a new menu item to insert before MenuItemName. Unlike the Add method, a new item is always created, even if ItemToInsert matches the name of an existing item.

CallbackOrSubmenu

See the Add method's CallbackOrSubmenu parameter.

Options

See the Add method's Options parameter.

備考

To insert a menu separator line before an existing custom menu item, omit all parameters except MenuItemName. To add a menu separator line at the bottom of the menu, omit all parameters.

Rename

メニュー項目の名前を変更します。

MyMenu.Rename(MenuItemName , NewName)

パラメータ

MenuItemName

型:文字列

メニュー項目の名称や位置。MenuItemName」を参照。

NewName

型:文字列

If blank or omitted, MenuItemName will be converted into a separator line. Otherwise, specify the new name.

備考

メニューアイテムの現在のコールバックまたはサブメニューは変更されます。

A separator line can be converted to a normal item by specifying the position of the separator such as "1&" for MenuItemName and a non-blank name for NewName, and then using the Add method to give the item a callback or submenu.

SetColor

メニューの背景色を変更します。

MyMenu.SetColor(ColorValue, ApplyToSubmenus)

パラメータ

ColorValue

型:文字列または整数

If blank or omitted, it defaults to the word Default, which restores the default color of the menu. Otherwise, specify one of the 16 primary HTML color names, a hexadecimal RGB color string (the 0x prefix is optional), or a pure numeric RGB color value. 例値:"Silver", "FFFFAA", 0xFFFFAA, "Default".

ApplyToSubmenus

型:論理値

If omitted, it defaults to true.

If true, the color will be applied to all of the menu's submenus.

If false, the color will be applied to the menu only.

SetIcon

メニュー項目の横に表示するアイコンを設定します。

MyMenu.SetIcon(MenuItemName, FileName , IconNumber, IconWidth)

パラメータ

MenuItemName

型:文字列

メニュー項目の名称や位置。MenuItemName」を参照。

FileName

型:文字列

The path to an icon or image file, or a bitmap or icon handle such as "HICON:" handle. For a list of supported formats, see the Picture control.

Specify an empty string or "*" to remove the item's current icon.

IconNumber

型:整数

If omitted, it defaults to 1 (the first icon group). Otherwise, specify the number of the icon group to be used in the file. For example, MyMenu.SetIcon(MenuItemName, "Shell32.dll", 2) would use the default icon from the second icon group. If negative, its absolute value is assumed to be the resource ID of an icon within an executable file.

IconWidth

型:整数

If omitted, it defaults to the width of a small icon recommended by the OS (usually 16 pixels). If 0, the original width is used. Otherwise, specify the desired width of the icon, in pixels. IconNumberで示されるアイコングループに複数のアイコンサイズが含まれる場合、最も近いサイズのアイコンを使用し、指定されたサイズに拡大縮小されます。

備考

Currently it is necessary to specify the "actual size" when setting the icon to preserve transparency, e.g. MyMenu.SetIcon(MenuItemName, "Filename.png",, 0).

Show

メニューを表示します。

MyMenu.Show(X, Y)

パラメータ

X, Y

型:整数

If omitted, the menu will be shown near the mouse cursor. Otherwise, specify the X and Y coordinates at which to display the upper left corner of the menu. The coordinates are relative to the active window's client area unless overridden by using CoordMode or A_CoordModeMenu.

備考

Displaying the menu allows the user to select an item with arrow keys, menu shortcuts (underlined letters), or the mouse.

サブメニューやトレイメニューなど、あらゆるポップアップメニューを表示することが可能です。However, an exception is thrown if MyMenu is a MenuBar object.

ToggleCheck

チェックマークがない場合は追加し、それ以外の場合は削除します。

MyMenu.ToggleCheck(MenuItemName)

パラメータ

MenuItemName

型:文字列

メニュー項目の名称や位置。MenuItemName」を参照。

ToggleEnable

Disables a menu item if it was previously enabled; otherwise, enables it.

MyMenu.ToggleEnable(MenuItemName)

パラメータ

MenuItemName

型:文字列

メニュー項目の名称や位置。MenuItemName」を参照。

Uncheck

メニュー項目からチェックマーク(ある場合)を削除します。

MyMenu.Uncheck(MenuItemName)

パラメータ

MenuItemName

型:文字列

メニュー項目の名称や位置。MenuItemName」を参照。

属性

ClickCount

Retrieves or sets how many times the tray icon must be clicked to select its default menu item.

CurrentCount := MyMenu.ClickCount
MyMenu.ClickCount := NewCount

CurrentCount is NewCount if assigned, otherwise 2 by default.

NewCount can be 1 to allow a single-click to select the tray menu's default menu item, or 2 to return to the default behavior (double-click). Any other value is invalid and throws an exception.

デフォルト

デフォルトのメニュー項目を取得または設定します。

CurrentDefault := MyMenu.Default
MyMenu.Default := MenuItemName

CurrentDefault is the name of the default menu item, or an empty string if there is no default.

MenuItemName is the name or position of a menu item. See MenuItemName. If MenuItemName is an empty string, there will be no default.

デフォルトの項目を設定すると、その項目のフォントが太くなります(トレイメニュー以外のメニューでデフォルトの項目を設定することは、現在のところ純粋な外観上の問題です)。When the user double-clicks the tray icon, its default menu item is selected (even if the item is disabled). デフォルトがない場合、ダブルクリックしても効果はありません。

トレイメニューのデフォルト項目は、存在する場合、最初は&Openです。AddStandardの呼び出しやA_AllowMainWindowの変更によってトレイメニューに&Openを追加すると、すでになかった場合はデフォルトのアイテムになることもあります。

デフォルトの項目が削除された場合、メニューには何もない状態になります。

Handle

Win32メニューのハンドル(HMENU型ハンドル)を、必要に応じて構築して返します。

Handle := MyMenu.Handle

返されたハンドルは、Win32メニューが破棄されるまで有効であり、通常Menuオブジェクトが解放されたときに発生する。メニューが破壊されると、オペレーティングシステムは、スクリプトまたは他のプログラムによってその後に作成されたすべてのメニューにハンドル値を再割り当てすることができます。

メニュー項目の名称や位置。このパラメータを使用するすべてのメソッドで、いくつかの共通のルールが適用されます:

メニュー名の1文字に下線を引くには、その文字の前にアンパサンド(&)を付けます。メニューが表示されているときに、キーボードの対応するキーを押すことで、その項目を選択することができます。文字通りのアンパサンドを表示するには、この例のように連続した2つのアンパサンドを指定します:"Save && Exit"

When referring to an existing menu item, the name is not case-sensitive but any ampersands must be included. 事例:"&Open"

メニュー項目の名称は260文字まで可能です。

既存の項目をメニュー内の位置で識別するには、項目の位置の後にアンパサンドを記述します。例えば、"1&"は最初の項目を示します。

Win32 Menus

Windowsは、標準的な外観と動作を持つメニューを作成、変更、表示するための一連の関数と通知を提供します。これらの関数を用いて作成されたメニューをWin32メニューと呼ぶことにします。

メニューに項目が追加されたり、変更されたりすると、各項目の名前とその他のプロパティがMenuオブジェクトに保存されます。Win32メニューは、メニューまたはその親メニューがGUIに添付されるか、表示される最初の時に構築されます。メニューオブジェクトが削除されたとき(参照カウントがゼロになったとき)に、自動的に破棄されます。

Menu.Handleは、Win32メニューのハンドル(HMENU型ハンドル)を、必要に応じて構築して返します。

Win32の関数で直接メニューに加えられた修正は、スクリプトのMenuオブジェクトには反映されないので、ビルトインメソッドでアイテムが修正されると、失われる可能性があります。

各メニューには、最初にメニューに追加されるときにIDが割り当てられます。スクリプトは、アイテムが特定のIDを受け取ることに依存することはできませんが、例5で示すようにGetMenuItemIDを使用して、アイテムのIDを取得することができます。このIDはMenuオブジェクトでは使用できませんが、Win32の各種機能で使用することができます。

備考

メニューは通常このような形になっています:

Menu

MyMenu.Delete()などでメニューが完全に空になった場合は、表示することができません。If the tray menu becomes empty, right-clicking and double-clicking the tray icon will have no effect (in such cases it is usually better to use #NoTrayIcon).

メニュー項目のコールバックがすでに実行されている状態で、ユーザーが同じメニューを再度選択した場合、その同じコールバックを実行するために新しいスレッドが作成され、前のスレッドを中断させます。このようなイベントを後でバッファリングするには、コールバックの最初の行にCriticalを使用します(ただし、この場合、ホットキーの押下など他のスレッドもバッファリング/ディファーされます)。

メニューから関数を呼び出すと、SendModeなどの設定値は常に初期値でスタートします。これらのデフォルトは、スクリプト起動時に変更することができます。

メニューの内容が常に同じとは限らない場合、そのようなメニューはすべて同じ関数を指定し、その関数のパラメータを参照して動作を決定する方法があります。また、関数オブジェクトクロージャファットアロー関数を使用して、1つ以上の値や変数をメニューアイテムのコールバック関数にバインドすることもできる。

GUI, Threads, Thread, Critical, #NoTrayIcon, Functions, Return, SetTimer

Adds a new menu item to the bottom of the tray icon menu.

A_TrayMenu.Add()  ; セパレータラインを作成します。
A_TrayMenu.Add("Item1", MenuHandler)  ; 新しいメニュー項目を作成する。
Persistent

MenuHandler(ItemName, ItemPos, MyMenu) {
    MsgBox "You selected " ItemName " (position " ItemPos ")"
}

ユーザーがホットキーを押したときに表示されるポップアップメニューを作成します。

; ポップアップメニューにいくつかの項目を追加して作成します。
MyMenu := Menu()
MyMenu.Add("Item 1", MenuHandler)
MyMenu.Add("Item 2", MenuHandler)
MyMenu.Add()  ; Add a separator line.

; 上のメニューのサブメニューとなるような別のメニューを作成する。
Submenu1 := Menu()
Submenu1.Add("Item A", MenuHandler)
Submenu1.Add("Item B", MenuHandler)

; 最初のメニューにサブメニューを作成する(右矢印の表示)。ユーザーが選択すると、2番目のメニューが表示される。
MyMenu.Add("My Submenu", Submenu1)

MyMenu.Add()  ; Add a separator line below the submenu.
MyMenu.Add("Item 3", MenuHandler)  ; Add another menu item beneath the submenu.

MenuHandler(Item, *) {
    MsgBox("You selected " Item)
}

#z::MyMenu.Show()  ; i.e. press the Win-Z hotkey to show the menu.

様々なメニューオブジェクトメンバーの一部を実演しています。

#SingleInstance
Persistent
Tray := A_TrayMenu ; For convenience.
Tray.Delete() ; Delete the standard items.
Tray.Add() ; separator
Tray.Add("TestToggleCheck", TestToggleCheck)
Tray.Add("TestToggleEnable", TestToggleEnable)
Tray.Add("TestDefault", TestDefault)
Tray.Add("TestAddStandard", TestAddStandard)
Tray.Add("TestDelete", TestDelete)
Tray.Add("TestDeleteAll", TestDeleteAll)
Tray.Add("TestRename", TestRename)
Tray.Add("Test", Test)

;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;

TestToggleCheck(*)
{
    Tray.ToggleCheck("TestToggleCheck")
    Tray.Enable("TestToggleEnable") ; Also enables the next test since it can't undo the disabling of itself.
    Tray.Add("TestDelete", TestDelete) ; Similar to above.
}

TestToggleEnable(*)
{
    Tray.ToggleEnable("TestToggleEnable")
}

TestDefault(*)
{
    if Tray.Default = "TestDefault"
        Tray.Default := ""
    else
        Tray.Default := "TestDefault"
}

TestAddStandard(*)
{
    Tray.AddStandard()
}

TestDelete(*)
{
    Tray.Delete("TestDelete")
}

TestDeleteAll(*)
{
    Tray.Delete()
}

TestRename(*)
{
    static OldName := "", NewName := ""
    if NewName != "renamed"
    {
        OldName := "TestRename"
        NewName := "renamed"
    }
    else
    {
        OldName := "renamed"
        NewName := "TestRename"
    }
    Tray.Rename(OldName, NewName)
}

Test(Item, *)
{
    MsgBox("You selected " Item)
}

メニュー項目にアイコンを追加する方法を説明します。

FileMenu := Menu()
FileMenu.Add("Script Icon", MenuHandler)
FileMenu.Add("Suspend Icon", MenuHandler)
FileMenu.Add("Pause Icon", MenuHandler)
FileMenu.SetIcon("Script Icon", A_AhkPath, 2) ; 2nd icon group from the file
FileMenu.SetIcon("Suspend Icon", A_AhkPath, -206) ; icon with resource ID 206
FileMenu.SetIcon("Pause Icon", A_AhkPath, -207) ; icon with resource ID 207
MyMenuBar := MenuBar()
MyMenuBar.Add("&File", FileMenu)
MyGui := Gui()
MyGui.MenuBar := MyMenuBar
MyGui.Add("Button",, "Exit This Example").OnEvent("Click", (*) => WinClose())
MyGui.Show()

MenuHandler(*) {
    ; この例では、メニュー項目は何もしません。
}

メニューの項目数と最後の項目のIDを報告します。

MyMenu := Menu()
MyMenu.Add("Item 1", NoAction)
MyMenu.Add("Item 2", NoAction)
MyMenu.Add("Item B", NoAction)

; メニューの項目数を取得する。
item_count := DllCall("GetMenuItemCount", "ptr", MyMenu.Handle)

; 最後のアイテムのIDを取得します。
last_id := DllCall("GetMenuItemID", "ptr", MyMenu.Handle, "int", item_count-1)

MsgBox("MyMenu has " item_count " items, and its last item has ID " last_id)

NoAction(*) {
    ; Do nothing.
}