Menus, like most WinAPI components, don't work very well in DirectX exclusive fullscreen (
window_set_fullscreen).If your application needs to run in fullscreen, consider borderless fullscreen (
window_set_showborder) instead.Per Windows rules, the game pauses while a menu is open.
It might be possible to implement non-pausing popup menus in the future, but the menu bar / system menu would still pause the game.
This is a "cheat sheet" for the "winMenu" extension by YellowAfterlife.
The extension can be found on itch.io.
Quick display controls: Categories · Sections · Everything ·
The extension works on a handful of GameMaker versions with minor differences:
Menu/bitmap values are mini-structs with a handle inside.
Menu/bitmap values are two-element arrays with a unique array ref at index 0 and handle at index 1.
Menu/bitmap values are two-element ds_grids with a type name in cell (0,0) and handle in cell (1,0).
For lack of undefined, functions return different values on error:
-
-1is returned instead of data structure indexes. -
""(empty string) is returned instead of numbers. -
0is returned instead of strings.
You can use is_real / is_string to check these.
Should be called once per frame, dispatches events.
In GameMaker 8.1, you should call this before using the extension functions.
Newer versions load the extension automatically.
When something doesn't go right, you can use these to get more information about the last cause of trouble:
Returns the error code from the last failed call.
MSDN: GetLastError
Returns the error message from the last failed call.
MSDN: FormatMessageW
Creates and returns a new menu bar.
Don't forget to destroy your menus if they don't stick for the duration of the game!
MSDN: CreateMenu
Creates and returns a new popup menu.
Similarly, you'll want to call winmenu_destroy if the menu isn't expected to stick around until the game exits.
These are used for actual popup menus and sub-menus inside a menu bar.
Using a menu bar instead of a popup menu causes variously buggy behaviour, so make sure to use the right menu type for the task.
MSDN: CreatePopupMenu
Destroys a previously created menu.
MSDN: DestroyMenu
Returns a menu's raw handle (HMENU) as a number.
Creates a menu reference from a handle.
Destroys a menu reference without destroying the referenced menu.
This is handy if you created a menu reference from a handle (or got it from winmenu_get_submenu), checked what you needed, and want to get rid of it without touching the menu.
This only has to be done explicitly in GameMaker 8.1.
Returns whether the given handle points to a valid menu.
MSDN: IsMenu
Returns whether two menu references point to the same underlying HMENU.
Returns the number of items in a menu.
If an error occurs, returns undefined[v].
Default item:
Changes the default item for the menu (that will show in bold font, see notes in winmenu_add).
Returns whether successful.
bypos indicates whether item is a position (true) or a command (false).
MSDN: SetMenuDefaultItem
Returns the default item for the menu.
bypos indicates whether you want a command (false) or a position (true) of the item.
If recursive is true and the default item opens a sub-menu,
it will look for the default item in that menu (if any).
If disabled is true, the function returns the item even if it is disabled.
If an error occurs, returns undefined[v].
MSDN: GetMenuDefaultItem
Height:
Changes the maximum height of a menu.
Value of 0 removes the limit for height.
Returns whether successful.
MSDN: SetMenuInfo (MIM_MAXHEIGHT)
Returns the maximum height of a menu.
If an error occurs, returns undefined[v].
MSDN: GetMenuInfo (MIM_MAXHEIGHT)
Changes the game window's menu bar (shown below the title bar).
The menu should be created with winmenu_create_bar.
Note that this eats into the game area and you may want to account for the added window height (using winmenu_bar_get_height) at various window-sizing/measuring occasions.
Returns the current bar-menu (if any).
Removes the game window's menu bar (if any).
Returns the height of the menu bar.
If an error occurs, returns undefined[v].
This function returns position and information about a menu item at index,
or the menu itself if index is not provided.
The returned value depends on your GameMaker version:
- GMS 2.3 and GM2022+:
A struct withx,y,width,height, andflagsvariables. - GM:S and GMS 2.2:
An array withx,y,width,height, andflagsvalues written in a row. - GM 8.1:
Ads_mapwithx,y,width,height, andflagskey-value pairs.
Don't forget to destroy it afterwards usingds_map_destroy!
flags can contain the following bit flags:
-
1: menu bar has focus -
2: menu item has focus
If an error occurs, returns undefined[v].
MSDN: GetMenuBarInfo
Redraws the menu bar.
You should only have to call this if you have modified the menu bar after assigning it to the window.
Returns whether successful.
If a script is assigned into this global variable, it will be called with the command ID whenever the user picks something from the menu.
Otherwise the extension will show information about the clicked items in the output
(using show_debug_message).
winmenu_bar_set(global.my_menu_bar); winmenu_bar_handler = function(_cmd) { var _cmd_text = winmenu_get_text(global.my_menu_bar, _cmd, false); if (_cmd_text == undefined) _cmd_text = "???"; show_debug_message("Menu bar item " + string(_cmd) + " (\"" + _cmd_text + "\") was clicked."); }
winmenu_bar_set(global.my_menu_bar); winmenu_bar_handler = scr_menu_bar_handler;
and then in scr_menu_bar_handler script:
var _cmd = argument0; var _cmd_text = winmenu_get_text(m_bar, _cmd, false); if (!is_string(_cmd_text)) _cmd_text = "???"; show_debug_message("Menu bar item " + string(_cmd) + ' ("' + _cmd_text + '") was clicked.');
Returns the game window's system menu (a popup menu).
The system menu appears when right-clicking the title bar or shift-right-clicking the game's taskbar button.
If revert is true, this reverts the menu to its original state before returning.
You should not destroy this menu.
Similar to winmenu_bar_get_info, but for the system menu.
Similar to winmenu_bar_handler, but for the system menu.
However: this can also trigger for commands that aren't yours - e.g. if the user has a third-party application that adds new items to the window menus (like Dexpot or WindowFX), the event will dispatch for these as well.
Shows a popup menu at the specified (screen-space) location.
If location is not specified, shows at current mouse location.
Returns the command for the chosen menu item, or 0 if the user cancels the menu or an error occurs.
flags can be zero or more of the following (bit flags):
General:
-
wmpf_can_right_click
Items can also be chosen with the right mouse button.
-
Alignment:
-
wmpf_halign_left
-
wmpf_halign_center
-
wmpf_halign_right
-
wmpf_valign_top
-
wmpf_valign_middle
-
wmpf_valign_bottom
These are identical to how
draw_set_halign/draw_set_valignwork, but for menus.-
Animation:
-
wmpf_anim_to_right
-
wmpf_anim_to_left
-
wmpf_anim_to_bottom
-
wmpf_anim_to_top
-
wmpf_anim_none
These control the direction in which the menu "rolls out" if animation is enabled in system settings.
-
MSDN: TrackPopupMenuEx
Like above, but avoids overlapping the specified rectangle (e.g. the subject of a context menu).
Adding:
Adds a new item to a menu.
Returns whether successful.
command is a unique (across the current menu popup/bar) index
that is then used for telling what item was interacted with,
or accessing/modifying items.
text is an item label.
You can use & to mark a letter for keyboard navigation (e.g. "&File");
You can display a keyboard shortcut for the menu item by separating it using
"\t" (GMS2 and GM2022+) or chr(vk_tab) (any version), such as
"New" + chr(vk_tab) + "Ctrl+N".
flags can be one or a sum of the following:
-
wmf_disabled
The item is disabled and grayed out. -
wmf_enabled
This flag is here for completeness, but you should know that you don't have to pass it in - an item is enabled if it is not disabled. -
wmf_checked
The item is "checked" (a checkmark appears next to it). -
wmf_radiocheck
The checkmark appears as a radiobutton circle instead. -
wmf_hilite
The item is highlighted when the menu opens.
The flag clears after moving the mouse over the item or otherwise selecting it. -
wmf_separator
The item is a separator line -
wmf_default
The item is the "default"/suggested action for the menu and highlighted in bold.
For example, "Open" action in Explorer file context menus is the default one.
A menu can only have one "default" item at a time. -
wmf_right_justify
Aligns this and the subsequent menu bar items to the right side.
If you've seen software have a "?" button on the right edge, that's how it works. -
wmf_right_order
Opens sub-menus to the left rather than to the right of this item.
This is used for right-to-left languages, such as Arabic and Hebrew. -
wmf_break
Moves this and subsequent menu items to a new column (popup menus) or row (menu bars). -
wmf_bar_break
Same as above, but also draws a separator between them.
MSDN: InsertMenuItemW
Adds a menu with a sub-menu.
The sub-menu should be a menu created using winmenu_create_popup.
Returns whether successful.
Flags are explained in winmenu_add.
A convenience function for inserting a separator (with wmf_separator flag).
Returns whether successful.
Flags are explained in winmenu_add.
Inserting:
Inserts an item before another item.
Returns whether successful.
bypos indicates whether item is a position (true) or a command (false).
Flags are explained in winmenu_add.
Like winmenu_add_submenu, but for insertion.
Like winmenu_add_separator, but for insertion.
Removing:
Removes a specified item from a menu.
Returns whether successful.
If the item contains a sub-menu, the sub-menu remains untouched.
bypos indicates whether item is a position (true) or a command (false).
Removes a specified item from a menu.
Returns whether successful.
If the item contains a sub-menu, the sub-menu is destroyed.
bypos indicates whether item is a position (true) or a command (false).
Command:
Returns the command of an item at the specified index.
If an error occurs, returns undefined[v].
Changes the command of an item.
Returns whether successful.
bypos indicates whether item is a position (true) or a command (false).
Text:
Returns the current label of an item.
If an error occurs, returns undefined[v].
bypos indicates whether item is a position (true) or a command (false).
Updates the label of an item.
Returns whether successful.
bypos indicates whether item is a position (true) or a command (false).
Sub-menus:
Returns whether an item has a sub-menu attached.
If an error occurs, returns undefined[v].
bypos indicates whether item is a position (true) or a command (false).
Returns an item's sub-menu.
In GM8.1, you should free the returned menu reference using winmenu_deref once you're done working with it.
If an error occurs, returns undefined[v].
bypos indicates whether item is a position (true) or a command (false).
Updates an item's sub-menu.
Returns whether successful.
bypos indicates whether item is a position (true) or a command (false).
Flags:
Returns flags of an item.
This function is effectively a combination of most other functions in this section for people who know what bit math is.
If an error occurs, returns undefined[v].
bypos indicates whether item is a position (true) or a command (false).
Flags are explained in winmenu_add.
MSDN: GetMenuItemInfoW
Updates flags of an item.
Returns whether successful.
bypos indicates whether item is a position (true) or a command (false).
Flags are explained in winmenu_add.
MSDN: SetMenuItemInfoW
Enable/disable:
Returns whether an item is enabled.
If an error occurs, returns undefined[v].
bypos indicates whether item is a position (true) or a command (false).
Changes whether an item is enabled.
Returns whether successful.
bypos indicates whether item is a position (true) or a command (false).
Highlight:
Returns whether an item will be highlighted when the menu opens (see winmenu_add for explanation).
If an error occurs, returns undefined[v].
bypos indicates whether item is a position (true) or a command (false).
Changes whether an item will be highlighted when the menu opens
Returns whether successful.
bypos indicates whether item is a position (true) or a command (false).
MSDN: HiliteMenuItem
Checkmark:
Returns whether the item is currently checked (for both checkmarks and radiobuttons).
If an error occurs, returns undefined[v].
bypos indicates whether item is a position (true) or a command (false).
Changes whether the item is currently checked.
Returns whether successful.
bypos indicates whether item is a position (true) or a command (false).
Radio buttons:
Returns whether an item is shown as a radio button when checked.
If an error occurs, returns undefined[v].
bypos indicates whether item is a position (true) or a command (false).
Changes whether an item is shown as a radio button when checked.
Returns whether successful.
bypos indicates whether item is a position (true) or a command (false).
This function marks a range of items (inclusive) as radio buttons
and un-checks all of them except for the item indicated with selection.
Returns whether successful.
bypos indicates whether item is a position (true) or a command (false).
MSDN: CheckMenuRadioItem
Returns a rectangle that the item occupies on screen.
Returned value is a struct in GMS2.3+, an array in GM:S and GMS2.2, and a ds_map in GM8.1.
MSDN: GetMenuItemRect
Returns what menu item is under (screen-space) coordinates.
MSDN: MenuItemFromPoint
Menu items (except for items in the menu bar) can have icons.
I'm calling these "bitmaps" because an "icon" in WinAPI terms is a different thing (that can have multiple sizes and other metadata).
Important: Windows expects menu bitmaps to have pre-multiplied alpha.
Loads a bitmap from the specified file.
If an error occurs, returns undefined[v].
Notes:
- The file must be a 32-bit BMP image
- A full path might be necessary if you aren't loading from the working directory
Creates a bitmap from a surface.
If an error occurs, returns undefined[v].
Creates a bitmap from a sprite.
If an error occurs, returns undefined[v].
Creates a bitmap from RGBA/BGRA pixel data in a buffer.
If an error occurs, returns undefined[v].
This function doesn't exist in GM8.1 version (for lack of buffers).
Destroys a previously created bitmap.
Removes a bitmap reference without destroying the underlying bitmap.
This only has to be done explicitly in GM8.1.
Returns whether two bitmaps reference the same underlying WinAPI bitmap.
These appear next to the menu item label (if any).
Changes the bitmap of a menu item.
bitmap is a bitmap, surely enough.
bypos indicates whether item is a position (true) or a command (false).
Returns whether successful.
Changes the bitmap of a menu item to one of the special system bitmaps.
index can be one of the following:
-
wmbm_mbar_close -
wmbm_mbar_close_d -
wmbm_mbar_minimize -
wmbm_mbar_minimize_d -
wmbm_mbar_restore -
wmbm_popup_close -
wmbm_popup_maximize -
wmbm_popup_mimize -
wmbm_popup_restore
These are the bitmap-icons that you see in system menus.
_d suffix means "disabled".
bypos indicates whether item is a position (true) or a command (false).
Returns whether successful.
MSDN: SetMenuItemInfoW (MIIM_BITMAP)
Clears the bitmap from a menu item.
This does not affect the bitmap in question.
bypos indicates whether item is a position (true) or a command (false).
Returns whether successful.
Returns whether an item has a bitmap assigned.
bypos indicates whether item is a position (true) or a command (false).
If an error occurs, returns undefined[v].
Returns the currently used bitmap of an item.
bypos indicates whether item is a position (true) or a command (false).
If an error occurs, returns undefined[v].
Checkmark bitmaps appear instead of the regular checkmarks.
If an item has both a bitmap and a checkmark, these will appear in separate columns.
Much like regular checkmarks, checkmark bitmaps will not appear in menu bars.
Changes the checkmark bitmaps of a menu item.
unchecked and checked are bitmaps.
bypos indicates whether item is a position (true) or a command (false).
Returns whether successful.
MSDN: SetMenuItemBitmaps
Clears checkmark bitmaps from a menu item.
This does not affect the bitmaps in question.
bypos indicates whether item is a position (true) or a command (false).
Returns whether successful.
Returns whether an item has a checkmark bitmap assigned.
Checks for the "checked" bitmap if checked if true and "unchecked" otherwise.
bypos indicates whether item is a position (true) or a command (false).
If an error occurs, returns undefined[v].
Retrieves the current checkmark bitmap for a menu item.
Returns the "checked" bitmap if checked if true and "unchecked" otherwise.
bypos indicates whether item is a position (true) or a command (false).
If an error occurs, returns undefined[v].
MSDN: GetMenuItemInfoW (MIIM_CHECKMARKS)
Returns the width of the default checkmark icon, in pixels.
It's a good idea to keep your icon sizes close to the system icon size, but Windows does not currently enforce this.
MSDN: GetSystemMetrics (SM_CXMENUCHECK, SM_CYMENUCHECK)
Same as above, but for height.
If your application consists of multiple windows (using my "Windows' windows" extension or libMulti), these functions let you apply the extension's functions to a different window.
In Windows' windows, you can get a handle of a window using winwin_get_handle.
libMulti doesn't have a way to get a window handle at the time of writing.
Changes the target window to the specified handle.
Changes the target window back to the main game window (window_handle()).
The extension caches a little information for windows it work with.
If you are creating and destroying windows often, you might want to call this function when destroying a window so that cached information is removed.
You don't have to call this for the main game window.
For example,
winmenu_set_target(winwin_get_handle(extra_window)); var m_bar = winmenu_create_bar(); winmenu_add(m_bar, 1, "Hello!"); winmenu_bar_set(m); winmenu_reset_target();