diff --git a/Terminal.Gui/Core/ContextMenu.cs b/Terminal.Gui/Views/ContextMenu.cs similarity index 62% rename from Terminal.Gui/Core/ContextMenu.cs rename to Terminal.Gui/Views/ContextMenu.cs index 79c1a9cb2..b5dcde5f6 100644 --- a/Terminal.Gui/Core/ContextMenu.cs +++ b/Terminal.Gui/Views/ContextMenu.cs @@ -2,8 +2,24 @@ namespace Terminal.Gui { /// - /// A context menu window derived from containing menu items - /// which can be opened in any position. + /// ContextMenu provides a pop-up menu that can be positioned anywhere within a . + /// ContextMenu is analogous to and, once activated, works like a sub-menu + /// of a (but can be positioned anywhere). + /// + /// By default, a ContextMenu with sub-menus is displayed in a cascading manner, where each sub-menu pops out of the ContextMenu frame + /// (either to the right or left, depending on where the ContextMenu is relative to the edge of the screen). By setting + /// to , this behavior can be changed such that all sub-menus are + /// drawn within the ContextMenu frame. + /// + /// + /// ContextMenus can be activated using the Shift-F10 key (by default; use the to change to another key). + /// + /// + /// Callers can cause the ContextMenu to be activated on a right-mouse click (or other interaction) by calling . + /// + /// + /// ContextMenus are located using screen using screen coordinates and appear above all other Views. + /// /// public sealed class ContextMenu : IDisposable { private static MenuBar menuBar; @@ -12,15 +28,15 @@ namespace Terminal.Gui { private Toplevel container; /// - /// Initialize a context menu with empty menu items. + /// Initializes a context menu with no menu items. /// public ContextMenu () : this (0, 0, new MenuBarItem ()) { } /// - /// Initialize a context menu with menu items from a host . + /// Initializes a context menu, with a specifiying the parent/hose of the menu. /// /// The host view. - /// The menu items. + /// The menu items for the context menu. public ContextMenu (View host, MenuBarItem menuItems) : this (host.Frame.X, host.Frame.Y, menuItems) { @@ -28,10 +44,10 @@ namespace Terminal.Gui { } /// - /// Initialize a context menu with menu items. + /// Initializes a context menu with menu items at a specific screen location. /// - /// The left position. - /// The top position. + /// The left position (screen relative). + /// The top position (screen relative). /// The menu items. public ContextMenu (int x, int y, MenuBarItem menuItems) { @@ -48,7 +64,7 @@ namespace Terminal.Gui { } /// - /// Disposes the all the context menu objects instances. + /// Disposes the context menu object. /// public void Dispose () { @@ -65,7 +81,7 @@ namespace Terminal.Gui { } /// - /// Open the menu items. + /// Shows (opens) the ContextMenu, displaying the s it contains. /// public void Show () { @@ -116,7 +132,7 @@ namespace Terminal.Gui { Y = position.Y, Width = 0, Height = 0, - UseSubMenusSingleFrame = this.UseSubMenusSingleFrame + UseSubMenusSingleFrame = this.UseSubMenusSingleFrame }; menuBar.isContextMenuLoading = true; @@ -138,7 +154,7 @@ namespace Terminal.Gui { } /// - /// Close the menu items. + /// Hides (closes) the ContextMenu. /// public void Hide () { @@ -157,7 +173,7 @@ namespace Terminal.Gui { public event Action MouseFlagsChanged; /// - /// Gets or set the menu position. + /// Gets or sets the menu position. /// public Point Position { get; set; } @@ -167,7 +183,7 @@ namespace Terminal.Gui { public MenuBarItem MenuItems { get; set; } /// - /// The used to activate the context menu by keyboard. + /// specifies they keyboard key that will activate the context menu with the keyboard. /// public Key Key { get => key; @@ -179,7 +195,7 @@ namespace Terminal.Gui { } /// - /// The used to activate the context menu by mouse. + /// specifies the mouse action used to activate the context menu by mouse. /// public MouseFlags MouseFlags { get => mouseFlags; @@ -191,7 +207,7 @@ namespace Terminal.Gui { } /// - /// Gets information whether menu is showing or not. + /// Gets whether the ContextMenu is showing or not. /// public static bool IsShow { get; private set; } @@ -202,8 +218,9 @@ namespace Terminal.Gui { public View Host { get; set; } /// - /// Gets or sets whether forces the minimum position to zero - /// if the left or right position are negative. + /// Sets or gets whether the context menu be forced to the right, ensuring it is not clipped, if the x position + /// is less than zero. The default is which means the context menu will be forced to the right. + /// If set to , the context menu will be clipped on the left if x is less than zero. /// public bool ForceMinimumPosToZero { get; set; } = true; @@ -213,7 +230,9 @@ namespace Terminal.Gui { public MenuBar MenuBar { get => menuBar; } /// - /// Gets or sets if the sub-menus must be displayed in a single or multiple frames. + /// Gets or sets if sub-menus will be displayed using a "single frame" menu style. If , the ContextMenu + /// and any sub-menus that would normally cascade will be displayed within a single frame. If (the default), + /// sub-menus will cascade using separate frames for each level of the menu hierarchy. /// public bool UseSubMenusSingleFrame { get; set; } } diff --git a/Terminal.Gui/Views/Menu.cs b/Terminal.Gui/Views/Menu.cs index 7a7d6e3d3..ed037a10f 100644 --- a/Terminal.Gui/Views/Menu.cs +++ b/Terminal.Gui/Views/Menu.cs @@ -11,7 +11,7 @@ namespace Terminal.Gui { [Flags] public enum MenuItemCheckStyle { /// - /// The menu item will be shown normally, with no check indicator. + /// The menu item will be shown normally, with no check indicator. The default. /// NoCheck = 0b_0000_0000, @@ -69,7 +69,7 @@ namespace Terminal.Gui { } /// - /// The HotKey is used to activate a with they keyboard. HotKeys are defined by prefixing the + /// The HotKey is used to activate a with the keyboard. HotKeys are defined by prefixing the /// of a MenuItem with an underscore ('_'). /// /// Pressing Alt-Hotkey for a (menu items on the menu bar) works even if the menu is not active). @@ -134,7 +134,7 @@ namespace Terminal.Gui { /// /// Gets or sets the action to be invoked to determine if the menu can be triggered. If returns - /// the menu item will be enabled. Otherwise it will be disabled. + /// the menu item will be enabled. Otherwise, it will be disabled. /// /// Function to determine if the action is can be executed or not. public Func CanExecute { get; set; } @@ -154,7 +154,7 @@ namespace Terminal.Gui { // ┌─────────────────┐ // │ ◌ TopLevel Alt+T │ // └─────────────────┘ - // TODO: Repalace the `2` literals with named constants + // TODO: Replace the `2` literals with named constants internal int Width => 1 + // space before Title TitleLength + 2 + // space after Title - BUGBUG: This should be 1 @@ -230,8 +230,8 @@ namespace Terminal.Gui { } /// - /// is a menu item on an app's . MenuBarItems do not support - /// . + /// is a menu item on an app's . + /// MenuBarItems do not support . /// public class MenuBarItem : MenuItem { /// @@ -834,30 +834,35 @@ namespace Terminal.Gui { } } - - /// /// - /// Provides a menu bar with drop-down and cascading menus. - /// - /// - /// + /// Provides a menu bar that spans the top of a View with drop-down and cascading menus. /// + /// + /// By default, any sub-sub-menus (sub-menus of the s added to s) + /// are displayed in a cascading manner, where each sub-sub-menu pops out of the sub-menu frame + /// (either to the right or left, depending on where the sub-menu is relative to the edge of the screen). By setting + /// to , this behavior can be changed such that all sub-sub-menus are + /// drawn within a single frame below the MenuBar. + /// /// /// /// - /// The appears on the first row of the terminal and uses the full width. + /// The appears on the first row of the parent View and uses the full width. /// /// /// The provides global hotkeys for the application. See . /// + /// + /// See also: + /// /// public class MenuBar : View { internal int selected; internal int selectedSub; /// - /// Gets or sets the array of s for the menu. Only set this when the is visible. + /// Gets or sets the array of s for the menu. Only set this after the is visible. /// /// The menu array. public MenuBarItem [] Menus { get; set; } @@ -880,7 +885,7 @@ namespace Terminal.Gui { static ustring shortcutDelimiter = "+"; /// - /// Used for change the shortcut delimiter separator. + /// Sets or gets the shortcut delimiter separator. The default is "+". /// public static ustring ShortcutDelimiter { get => shortcutDelimiter; @@ -900,6 +905,13 @@ namespace Terminal.Gui { /// /// Gets or sets if the sub-menus must be displayed in a single or multiple frames. + /// + /// By default any sub-sub-menus (sub-menus of the main s) are displayed in a cascading manner, + /// where each sub-sub-menu pops out of the sub-menu frame + /// (either to the right or left, depending on where the sub-menu is relative to the edge of the screen). By setting + /// to , this behavior can be changed such that all sub-sub-menus are + /// drawn within a single frame below the MenuBar. + /// /// public bool UseSubMenusSingleFrame { get => useSubMenusSingleFrame; @@ -1123,7 +1135,7 @@ namespace Terminal.Gui { public event Action MenuClosing; /// - /// Raised when all the menu are closed. + /// Raised when all the menu is closed. /// public event Action MenuAllClosed; @@ -1146,7 +1158,7 @@ namespace Terminal.Gui { internal bool isMenuClosing; /// - /// True if the menu is open; otherwise false. + /// if the menu is open; otherwise . /// public bool IsMenuOpen { get; protected set; } @@ -1179,7 +1191,7 @@ namespace Terminal.Gui { } /// - /// Virtual method that will invoke the + /// Virtual method that will invoke the . /// /// The current menu to be closed. /// Whether the current menu will be reopen. @@ -1192,7 +1204,7 @@ namespace Terminal.Gui { } /// - /// Virtual method that will invoke the + /// Virtual method that will invoke the . /// public virtual void OnMenuAllClosed () { @@ -1202,7 +1214,7 @@ namespace Terminal.Gui { View lastFocused; /// - /// Get the lasted focused view before open the menu. + /// Gets the view that was last focused before opening the menu. /// public View LastFocused { get; private set; } @@ -1290,7 +1302,7 @@ namespace Terminal.Gui { } /// - /// Opens the current Menu programatically. + /// Opens the Menu programatically, as though the F9 key were pressed. /// public void OpenMenu () { @@ -1372,7 +1384,7 @@ namespace Terminal.Gui { } /// - /// Closes the current Menu programatically, if open and not canceled. + /// Closes the Menu programmatically if open and not canceled (as though F9 were pressed). /// public bool CloseMenu (bool ignoreUseSubMenusSingleFrame = false) { @@ -1474,26 +1486,6 @@ namespace Terminal.Gui { if (openSubMenu.Count > 0) openCurrentMenu = openSubMenu.Last (); - //if (openMenu.Subviews.Count == 0) - // return; - //if (index == 0) { - // //SuperView.SetFocus (previousSubFocused); - // FocusPrev (); - // return; - //} - - //for (int i = openMenu.Subviews.Count - 1; i > index; i--) { - // isMenuClosing = true; - // if (openMenu.Subviews.Count - 1 > 0) - // SuperView.SetFocus (openMenu.Subviews [i - 1]); - // else - // SuperView.SetFocus (openMenu); - // if (openMenu != null) { - // Remove (openMenu.Subviews [i]); - // openMenu.Remove (openMenu.Subviews [i]); - // } - // RemoveSubMenu (i); - //} isMenuClosing = false; } @@ -1894,47 +1886,6 @@ namespace Terminal.Gui { handled = false; return false; } - //if (me.View != this && me.Flags != MouseFlags.Button1Pressed) - // return true; - //else if (me.View != this && me.Flags == MouseFlags.Button1Pressed || me.Flags == MouseFlags.Button1DoubleClicked) { - // Application.UngrabMouse (); - // host.CloseAllMenus (); - // return true; - //} - - - //if (!(me.View is MenuBar) && !(me.View is Menu) && me.Flags != MouseFlags.Button1Pressed)) - // return false; - - //if (Application.MouseGrabView != null) { - // if (me.View is MenuBar || me.View is Menu) { - // me.X -= me.OfX; - // me.Y -= me.OfY; - // me.View.MouseEvent (me); - // return true; - // } else if (!(me.View is MenuBar || me.View is Menu) && me.Flags == MouseFlags.Button1Pressed || me.Flags == MouseFlags.Button1DoubleClicked) { - // Application.UngrabMouse (); - // CloseAllMenus (); - // } - //} else if (!isMenuClosed && selected == -1 && me.Flags == MouseFlags.Button1Pressed || me.Flags == MouseFlags.Button1DoubleClicked) { - // Application.GrabMouse (this); - // return true; - //} - - //if (Application.MouseGrabView != null) { - // if (Application.MouseGrabView == me.View && me.View == current) { - // me.X -= me.OfX; - // me.Y -= me.OfY; - // } else if (me.View != current && me.View is MenuBar && me.View is Menu) { - // Application.UngrabMouse (); - // Application.GrabMouse (me.View); - // } else if (me.Flags == MouseFlags.Button1Pressed || me.Flags == MouseFlags.Button1DoubleClicked) { - // Application.UngrabMouse (); - // CloseMenu (); - // } - //} else if ((!isMenuClosed && selected > -1)) { - // Application.GrabMouse (current); - //} handled = true; @@ -1988,12 +1939,13 @@ namespace Terminal.Gui { /// public MenuBarItem NewMenuBarItem { get; set; } /// - /// Flag that allows you to cancel the opening of the menu. + /// Flag that allows the cancellation of the event. If set to in the + /// event handler, the event will be canceled. /// public bool Cancel { get; set; } /// - /// Initializes a new instance of + /// Initializes a new instance of . /// /// The current parent. public MenuOpeningEventArgs (MenuBarItem currentMenu) @@ -2012,7 +1964,7 @@ namespace Terminal.Gui { public MenuBarItem CurrentMenu { get; } /// - /// Indicates whether the current menu will be reopen. + /// Indicates whether the current menu will reopen. /// public bool Reopen { get; } @@ -2022,15 +1974,16 @@ namespace Terminal.Gui { public bool IsSubMenu { get; } /// - /// Flag that allows you to cancel the opening of the menu. + /// Flag that allows the cancellation of the event. If set to in the + /// event handler, the event will be canceled. /// public bool Cancel { get; set; } /// - /// Initializes a new instance of + /// Initializes a new instance of . /// /// The current parent. - /// Whether the current menu will be reopen. + /// Whether the current menu will reopen. /// Indicates whether it is a sub-menu. public MenuClosingEventArgs (MenuBarItem currentMenu, bool reopen, bool isSubMenu) { diff --git a/UICatalog/Scenarios/Editor.cs b/UICatalog/Scenarios/Editor.cs index 633158ee5..5f679c74b 100644 --- a/UICatalog/Scenarios/Editor.cs +++ b/UICatalog/Scenarios/Editor.cs @@ -116,6 +116,8 @@ namespace UICatalog.Scenarios { new MenuBarItem ("_Languages", GetSupportedCultures ()) }) }); + menu.UseSubMenusSingleFrame = true; + Top.Add (menu); var statusBar = new StatusBar (new StatusItem [] {