PopupMenu

public PopupMenu();

Creates an empty hidden menu. HideOnItemSelection/HideOnCheckableItemSelection enabled, HideOnStateItemSelection disabled. Adding records does not activate them.

public bool AllowSearch { get; set; }

Enables navigation by the initial letters of original item labels, default true. This navigates rather than executing commands or providing a filter field. This letter-navigation mode is unused while the menu search bar is visible.

public bool HideOnCheckableItemSelection { get; set; }

Hide on check/radio activation, default true. Does not toggle checked itself.

public bool HideOnItemSelection { get; set; }

Hide on ordinary command activation, default true. Does not enable/disable handler execution.

public bool HideOnStateItemSelection { get; set; }

Hide on multistate activation, default false. Does not modify state.

public int ItemCount { get; set; }

Record count including separators. Setter requires ≥ 0; growth adds empty records with index-based IDs, shrinking discards the tail. Does not manage the lifetime of every child submenu.

public bool PreferNativeMenu { get; set; }

If true, MenuBar will use native menu when supported. Note: If PopupMenu is linked to StatusIndicator, MenuBar, or another PopupMenu item it can use native menu regardless of this property, use PopupMenu.IsNativeMenu to check it.

public bool SearchBarEnabled { get; set; }

Enables the menu filter field, default false. It appears at SearchBarMinItemCount; separators do not count toward the threshold. While the field is visible, AllowSearch letter navigation is unused. This configures the local menu rather than guaranteeing an equivalent OS-native field.

public bool SearchBarFuzzySearchEnabled { get; set; }

Enables fuzzy matching in the search field, default true. false uses the matcher’s exact-token mode rather than promising byte-for-byte equality of the entire label. Search uses original item and submenu labels.

public int SearchBarFuzzySearchMaxMisses { get; set; }

Fuzzy matcher miss allowance: integer 0 or greater, default 2. This configures matching rather than result count or a guaranteed Levenshtein distance.

public int SearchBarMinItemCount { get; set; }

Minimum number of non-separator items needed to show the enabled search field. Must be 0 or greater; default 0. Does not remove records or change IDs.

public bool ShrinkHeight { get; set; }

Fit the local popup height to its computed content minimum when preparing it, default true. false retains the requested height subject to window constraints. The setter does not itself open or resize an already displayed window.

public bool ShrinkWidth { get; set; }

Fit the local popup width to its computed content minimum when preparing it, default true. false retains the requested width subject to window constraints. The setter does not itself open the menu.

public float SubmenuPopupDelay { get; set; }

Hover submenu opening delay in seconds; default 0.2. A value ≤ 0 becomes 0.01; positive values below 0.01 are retained. Does not provide zero delay or trigger opening by itself.

public NativeMenu.SystemMenus SystemMenuId { get; set; }

If set to one of the values of NativeMenu.SystemMenus, this PopupMenu is bound to the special system menu. Only one PopupMenu can be bound to each special menu at a time.

public bool ActivateItemByEvent(InputEvent @event, bool forGlobalOnly = false);

Directly matches a Shortcut/accelerator and activates the first eligible item. Caller must filter press/echo; a matching release can also activate an accelerator. Respects Disabled and ShortcutDisabled. forGlobalOnly restricts Shortcuts rather than ordinary accelerators.

public void AddCheckItem(string label, int id = -1, Key accel = Key.None);

Adds an initially unchecked checkbox item. Activation does not toggle checked; update the model and SetItemChecked in your handler.

public void AddCheckShortcut(Shortcut shortcut, int id = -1, bool global = false);

Adds a checkbox command with a shared Shortcut and a label from ResourceName. Initially unchecked; activation does not toggle checked. Update your model and call SetItemChecked in IdPressed. Echo repeats are disabled.

public void AddIconCheckItem(Texture2D texture, string label, int id = -1, Key accel = Key.None);

Adds a checkbox command with the original label, shared icon and optional accelerator. Initially unchecked; activation does not toggle it. Use SetItemChecked in IdPressed. id = -1 assigns the current index.

public void AddIconCheckShortcut(Texture2D texture, Shortcut shortcut, int id = -1, bool global = false);

Adds a checkbox command with a shared icon and Shortcut; label is copied from ResourceName. Activation does not change checked; echo repeats are disabled. Set the state explicitly in IdPressed.

public void AddIconItem(Texture2D texture, string label, int id = -1, Key accel = Key.None);

Adds an ordinary command with the original label and a shared Texture2D. accel sets a separate keyboard accelerator; Key.None disables it. id = -1 assigns the current index. This does not create a Shortcut resource or a checkable item.

public void AddIconRadioCheckItem(Texture2D texture, string label, int id = -1, Key accel = Key.None);

Adds a radio command with the original label, shared icon and optional accelerator. Initially unchecked; the application implements toggling and mutual exclusion. id = -1 assigns the current index.

public void AddIconRadioCheckShortcut(Texture2D texture, Shortcut shortcut, int id = -1, bool global = false);

Adds a radio command with a shared icon and Shortcut; label is copied from ResourceName. Activation neither changes checked nor clears neighboring radio flags; echo repeats are disabled.

public void AddIconShortcut(Texture2D texture, Shortcut shortcut, int id, bool global);

Short overload adds a command with allowEcho = false. Use the overload with allowEcho for an explicit repeat policy. Label is copied from ResourceName; global does not mean an OS-wide hotkey.

public void AddIconShortcut(Texture2D texture, Shortcut shortcut, int id = -1, bool global = false, bool allowEcho = false);

Adds an ordinary command with an icon and a shared Shortcut. Label is copied from ResourceName; this is not a checkbox. global does not register an OS-wide hotkey. Repeats require allowEcho = true; default false. Icon and Shortcut resources are not copied.

public void AddItem(string label, int id = -1, Key accel = Key.None);

Adds a command with text, ID and optional accelerator. id = -1 assigns the current index; use a unique nonnegative ID for a stable command.

public void AddMultistateItem(string label, int maxStates, int defaultState = 0, int id = -1, Key accel = Key.None);

Adds an item with state count and initial state index. Validate maxStates > 0 and defaultState range. Activation does not automatically advance state.

public void AddRadioCheckItem(string label, int id = -1, Key accel = Key.None);

Adds an initially unchecked radio item. Does not create an exclusive group; clear other options yourself.

public void AddRadioCheckShortcut(Shortcut shortcut, int id = -1, bool global = false);

Adds a radio command with a shared Shortcut and a label from ResourceName. Initially unchecked; neither automatic toggling nor mutual exclusion with neighboring radio items is provided. Set the required states in IdPressed. Echo repeats are disabled.

public void AddSeparator(string label = "", int id = -1);

Adds a separator that occupies an index but is not an activation command. Stores id directly: -1 is not replaced with an index. Label is optional.

public void AddShortcut(Shortcut shortcut, int id, bool global);

Short overload adds a command with allowEcho = false. Use the overload with allowEcho for an explicit repeat policy. Label is copied from ResourceName; global does not mean an OS-wide hotkey.

public void AddShortcut(Shortcut shortcut, int id = -1, bool global = false, bool allowEcho = false);

Adds an ordinary command with a shared Shortcut resource; initial label is copied from ResourceName. id = -1 assigns the current index; use a stable nonnegative ID for routing. global concerns menu shortcut handling rather than OS-wide registration outside the application. allowEcho permits repeats; default false. Handle the action in IdPressed.

public void AddSubmenuEntityItem(string label, PopupMenu submenu, int id = -1);

Adds an item referencing a PopupMenu. Submenu must be parentless or already a child of this menu; a parentless object is adopted. Keep a clear owner/item relationship.

public void AddSubmenuItem(string label, string submenu, int id = -1);

Adds an existing submenu by relative path. Prefer typed AddSubmenuEntityItem in the installed SDK; do not supply an arbitrary nonexistent menu name.

public void Clear();

Removes records and resets focus. No argument or false retains child submenus. true detaches and schedules freeing only submenus referenced by current items; does not free previously retained unreferenced children.

public void Clear(bool freeSubmenus = false);

Removes records and resets focus. No argument or false retains child submenus. true detaches and schedules freeing only submenus referenced by current items; does not free previously retained unreferenced children.

public bool GetAllowSearch();

Enables navigation by the initial letters of original item labels, default true. This navigates rather than executing commands or providing a filter field. This letter-navigation mode is unused while the menu search bar is visible.

public int GetFocusedItem();

Returns the current highlight index, or -1. This is an index rather than a command ID or execution result.

public Key GetItemAccelerator(int index);

Returns the stored accelerator Key rather than a Shortcut object.

public Entity.AutoTranslateModeEnum GetItemAutoTranslateMode(int index);

Returns the stored translation policy, default Inherit, rather than whether a translation exists for this label.

public int GetItemCount();

Record count including separators. Setter requires ≥ 0; growth adds empty records with index-based IDs, shrinking discards the tail. Does not manage the lifetime of every child submenu.

public Texture2D GetItemIcon(int index);

Returns the shared Texture2D, or null. This is the original resource rather than a menu-sized copy. Requires an ordinary valid index.

public int GetItemIconMaxWidth(int index);

Returns the stored item limit rather than drawn width or the effective theme limit. Default 0.

public Color GetItemIconModulate(int index);

Returns the stored icon RGBA multiplier, white by default.

public int GetItemId(int index);

Returns the stored ID at an existing index. Activation can substitute the index for negative IDs. Validate the index first: an invalid getter is not a command lookup.

public int GetItemIndent(int index);

Returns the stored indentation level, default 0, rather than the resulting offset.

public int GetItemIndex(int id);

Returns the first current index with the ID, or -1. Duplicates are not prevented; resolve again after reorder/removal.

public string GetItemLanguage(int index);

Returns the stored item language code, empty by default. Not necessarily the application’s current locale.

public Variant GetItemMetadata(int index);

Returns metadata Variant, Nil when unassigned. Validate the expected type before conversion.

public int GetItemMultistate(int index);

Returns stored state index rather than state count.

public int GetItemMultistateMax(int index);

Returns state count; nonpositive values disable ToggleItemMultistate advancement.

public Shortcut GetItemShortcut(int index);

Returns the shared Shortcut resource, or null. This is not a copy: changing its Events affects items using it. Changing ResourceName does not itself replace item text; call SetItemText explicitly. Requires an ordinary valid index.

public string GetItemSubmenu(int index);

Returns stored submenu name/path. Prefer GetItemSubmenuEntity in the installed SDK when you need the object.

public PopupMenu GetItemSubmenuEntity(int index);

Shared submenu object, or null. Does not change tree ownership/lifetime.

public string GetItemText(int index);

Returns original item text rather than displayed translation or command ID.

public Control.TextDirection GetItemTextDirection(int index);

Returns the stored text-direction policy, default Auto, rather than the resolved direction of each line.

public string GetItemTooltip(int index);

Returns the stored tooltip string regardless of whether it is currently displayed.

public int GetSearchBarFuzzySearchMaxMisses();

Fuzzy matcher miss allowance: integer 0 or greater, default 2. This configures matching rather than result count or a guaranteed Levenshtein distance.

public int GetSearchBarMinItemCount();

Minimum number of non-separator items needed to show the enabled search field. Must be 0 or greater; default 0. Does not remove records or change IDs.

public bool GetShrinkHeight();

Fit the local popup height to its computed content minimum when preparing it, default true. false retains the requested height subject to window constraints. The setter does not itself open or resize an already displayed window.

public bool GetShrinkWidth();

Fit the local popup width to its computed content minimum when preparing it, default true. false retains the requested width subject to window constraints. The setter does not itself open the menu.

public float GetSubmenuPopupDelay();

Hover submenu opening delay in seconds; default 0.2. A value ≤ 0 becomes 0.01; positive values below 0.01 are retained. Does not provide zero delay or trigger opening by itself.

public bool IsHideOnCheckableItemSelection();

Hide on check/radio activation, default true. Does not toggle checked itself.

public bool IsHideOnItemSelection();

Hide on ordinary command activation, default true. Does not enable/disable handler execution.

public bool IsHideOnStateItemSelection();

Hide on multistate activation, default false. Does not modify state.

public bool IsItemCheckable(int index);

true for checkbox or radio type. Does not mean the item is checked.

public bool IsItemChecked(int index);

Stored checked flag independently of checkable type.

public bool IsItemDisabled(int index);

Item disabled flag rather than checkbox state.

public bool IsItemIndeterminate(int index);

Stored indeterminate flag.

public bool IsItemRadioCheckable(int index);

true only for radio type. Does not imply an exclusive group.

public bool IsItemSeparator(int index);

Separator flag; separators cannot be used as ordinary activation commands.

public bool IsItemShortcutDisabled(int index);

Shortcut-event handling disable flag, separate from Disabled.

public bool IsNativeMenu();

Returns true if the system native menu is supported and currently used by this PopupMenu.

public bool IsSearchBarEnabled();

Enables the menu filter field, default false. It appears at SearchBarMinItemCount; separators do not count toward the threshold. While the field is visible, AllowSearch letter navigation is unused. This configures the local menu rather than guaranteeing an equivalent OS-native field.

public bool IsSearchBarFuzzySearchEnabled();

Enables fuzzy matching in the search field, default true. false uses the matcher’s exact-token mode rather than promising byte-for-byte equality of the entire label. Search uses original item and submenu labels.

public bool IsSystemMenu();

Returns true if the menu is bound to the special system menu.

public void RemoveItem(int index);

Removes a record and shifts later indices without renumbering IDs. Does not automatically free a submenu object; resolve command indices again after mutation.

public void ScrollToItem(int index);

Scrolls the local list toward the row at an ordinary valid index. Uses cached geometry; call after layout is established. Does not select, highlight or execute the item.

public void SetAllowSearch(bool allow);

Enables navigation by the initial letters of original item labels, default true. This navigates rather than executing commands or providing a filter field. This letter-navigation mode is unused while the menu search bar is visible.

public void SetFocusedItem(int index);

Sets the highlighted item index; -1 clears it. Does not grab window focus or execute a command. Does not reject disabled items or separators; choose an eligible item yourself. Emits neither IdFocused nor IdPressed.

public void SetHideOnCheckableItemSelection(bool enable);

Hide on check/radio activation, default true. Does not toggle checked itself.

public void SetHideOnItemSelection(bool enable);

Hide on ordinary command activation, default true. Does not enable/disable handler execution.

public void SetHideOnStateItemSelection(bool enable);

Hide on multistate activation, default false. Does not modify state.

public void SetItemAccelerator(int index, Key accel);

Sets an item Key accelerator. Key.None disables it; does not replace Shortcut or execute the command. Supports negative indices.

public void SetItemAsCheckable(int index, bool enable);

true selects checkbox type, replacing radio; false clears checkable type. Does not normalize other items’ checked flags. Supports negative indices.

public void SetItemAsRadioCheckable(int index, bool enable);

true selects radio type; false clears checkable type without creating a group. Implement exclusivity in your model/handler. Supports negative indices.

public void SetItemAsSeparator(int index, bool enable);

Changes separator type without removing the record or changing ID. This setter does not emit MenuChanged in the current implementation. Supports negative indices.

public void SetItemAutoTranslateMode(int index, Entity.AutoTranslateModeEnum mode);

Sets label translation policy: Inherit follows the menu setting, Always requests translation, Disabled retains the original string. Requires loaded translations and a suitable locale; does not generate translations. GetItemText is unchanged. Accepts negative indices.

public void SetItemChecked(int index, bool @checked);

Sets checked without activation. A changed value clears indeterminate; reassigning the same checked value is a no-op and can retain indeterminate. Supports negative indices.

public void SetItemCount(int count);

Record count including separators. Setter requires ≥ 0; growth adds empty records with index-based IDs, shrinking discards the tail. Does not manage the lifetime of every child submenu.

public void SetItemDisabled(int index, bool disabled);

Disables an item for ordinary input and ActivateItemByEvent without removing it. Programmatic state setters remain available. Supports negative indices.

public void SetItemIcon(int index, Texture2D icon);

Sets a shared Texture2D icon; does not copy the resource. null removes the icon. Accepts a negative index from the end. A change emits MenuChanged.

public void SetItemIconMaxWidth(int index, int width);

Sets an icon width limit in local UI units. Positive item and theme limits combine using the smaller value. A wider icon scales down with its aspect ratio preserved; smaller icons are not enlarged. A nonpositive value disables only the item limit. Accepts negative indices.

public void SetItemIconModulate(int index, Color modulate);

Sets the icon RGBA multiplier; white retains its color. Does not tint text or modify the source Texture2D. Accepts negative indices. Requests redraw without MenuChanged.

public void SetItemId(int index, int id);

Changes a record ID without moving it. Does not enforce uniqueness; use a nonnegative value for stable IdPressed. Supports a negative record index from the end.

public void SetItemIndent(int index, int indent);

Sets an indentation level: local offset is indent × the theme indent constant. This is neither a pixel count nor submenu creation. Normally use a nonnegative level. Accepts a negative item index.

public void SetItemIndeterminate(int index, bool indeterminate);

Changes the indeterminate flag; an actual change resets checked to false. Reassigning the same value does nothing. Supports negative indices.

public void SetItemIndex(int index, int targetIndex);

Moves the complete record, including ID/metadata/state, to final targetIndex. Both parameters accept indices from the end. Use ItemCount - 1 or -1 for the end rather than ItemCount.

public void SetItemLanguage(int index, string language);

Sets the item text-shaping language hint; an empty string uses the current language. Does not translate the original text, change GetItemText or switch the application locale. Accepts negative indices from the end.

public void SetItemMetadata(int index, Variant metadata);

Stores item Variant data. Moves with the record; Array/Dictionary can retain shared contents. Supports negative indices.

public void SetItemMultistate(int index, int state);

Sets state without activation. Setter does not clamp range: validate 0 ≤ state < maxStates yourself. Supports negative record indices.

public void SetItemMultistateMax(int index, int maxStates);

Sets state count without normalizing current state. Use a positive value for active multistate and update state separately. Supports negative indices.

public void SetItemShortcut(int index, Shortcut shortcut, bool global = false);

Replaces an existing item’s shared Shortcut and global flag; null removes the Shortcut. Does not change its label, icon, checked state or separate accelerator. Does not set allowEcho: the policy established when adding the item is retained. Accepts negative indices from the end. Updated Events on the shared Shortcut are used by subsequent matches.

public void SetItemShortcutDisabled(int index, bool disabled);

Disables item shortcut-event handling; also excludes its accelerator in ActivateItemByEvent. Does not disable the whole item for ordinary clicks. Supports negative indices.

public void SetItemSubmenu(int index, string submenu);

Legacy setter in the installed SDK: resolves an existing PopupMenu by relative path. Prefer SetItemSubmenuEntity. An empty string is not a reliable way to clear a submenu; the typed setter also rejects null.

public void SetItemSubmenuEntity(int index, PopupMenu submenu);

Assigns a non-null PopupMenu to an existing item. A parentless submenu becomes a child of this menu; objects owned by another parent are rejected. Replacement neither frees nor detaches the previous submenu. Do not pass null to clear it: remove/recreate the item, then separately clean up an unused child. Accepts negative indices.

public void SetItemText(int index, string text);

Changes original text and refreshes translation/shaping rather than ID. Supports negative indexing from the end; does not activate the command.

public void SetItemTextDirection(int index, Control.TextDirection direction);

Sets the item’s base text-shaping direction. Auto derives it from text; this neither translates text nor mirrors the entire window layout. GetItemText remains original. Accepts negative indices.

public void SetItemTooltip(int index, string tooltip);

Stores tooltip text; an empty string removes its text. Does not immediately open a tooltip or change the command label. Accepts negative indices; assigning the same value does nothing.

public void SetSearchBarEnabled(bool enabled);

Enables the menu filter field, default false. It appears at SearchBarMinItemCount; separators do not count toward the threshold. While the field is visible, AllowSearch letter navigation is unused. This configures the local menu rather than guaranteeing an equivalent OS-native field.

public void SetSearchBarFuzzySearchEnabled(bool enabled);

Enables fuzzy matching in the search field, default true. false uses the matcher’s exact-token mode rather than promising byte-for-byte equality of the entire label. Search uses original item and submenu labels.

public void SetSearchBarFuzzySearchMaxMisses(int maxMisses);

Fuzzy matcher miss allowance: integer 0 or greater, default 2. This configures matching rather than result count or a guaranteed Levenshtein distance.

public void SetSearchBarMinItemCount(int count);

Minimum number of non-separator items needed to show the enabled search field. Must be 0 or greater; default 0. Does not remove records or change IDs.

public void SetShrinkHeight(bool shrink);

Fit the local popup height to its computed content minimum when preparing it, default true. false retains the requested height subject to window constraints. The setter does not itself open or resize an already displayed window.

public void SetShrinkWidth(bool shrink);

Fit the local popup width to its computed content minimum when preparing it, default true. false retains the requested width subject to window constraints. The setter does not itself open the menu.

public void SetSubmenuPopupDelay(float seconds);

Hover submenu opening delay in seconds; default 0.2. A value ≤ 0 becomes 0.01; positive values below 0.01 are retained. Does not provide zero delay or trigger opening by itself.

public void ToggleItemChecked(int index);

Inverts checked without activation. Does not clear indeterminate or uncheck radio siblings. Requires an ordinary valid index.

public void ToggleItemMultistate(int index);

Increments state, wrapping to 0 at maxStates. Does nothing when maxStates ≤ 0. Does not activate the command; requires an ordinary valid index.

public event PopupMenu.IdFocusedEventHandler IdFocused;

Reports menu navigation highlight changes. Carries the stored ID, including negative values; the negative-ID-to-index fallback of IdPressed does not apply. Direct SetFocusedItem emits no signal. Do not execute commands merely because they become highlighted.

public event PopupMenu.IdPressedEventHandler IdPressed;

Command activation: ID, or index when stored ID is negative. Precedes IndexPressed. Use unique nonnegative IDs for stable routing.

public event PopupMenu.IndexPressedEventHandler IndexPressed;

Activation index captured when activation began, after IdPressed. If the first handler changed the list, the index can now refer to another record. Do not execute one action in both signals.

public event Action MenuChanged;

Notification from many menu mutations rather than activation. Not every setter emits it: SetItemAsSeparator does not. Do not use it as sole observation of all writes.