diff --git a/Terminal.Gui/Core/View.cs b/Terminal.Gui/Core/View.cs index aa121d131..8548be267 100644 --- a/Terminal.Gui/Core/View.cs +++ b/Terminal.Gui/Core/View.cs @@ -1,16 +1,4 @@ -// -// Authors: -// Miguel de Icaza (miguel@gnome.org) -// -// Pending: -// - Check for NeedDisplay on the hierarchy and repaint -// - Layout support -// - "Colors" type or "Attributes" type? -// - What to surface as "BackgroundColor" when clearing a window, an attribute or colors? -// -// Optimizations -// - Add rendering limitation to the exposed area -using System; +using System; using System.Collections.Generic; using System.ComponentModel; using System.Linq; @@ -19,9 +7,9 @@ using NStack; namespace Terminal.Gui { /// - /// Determines the LayoutStyle for a view, if Absolute, during LayoutSubviews, the - /// value from the Frame will be used, if the value is Computed, then the Frame - /// will be updated from the X, Y Pos objects and the Width and Height Dim objects. + /// Determines the LayoutStyle for a , if Absolute, during , the + /// value from the will be used, if the value is Computed, then + /// will be updated from the X, Y objects and the Width and Height objects. /// public enum LayoutStyle { /// @@ -37,17 +25,19 @@ namespace Terminal.Gui { } /// - /// View is the base class for all views on the screen and represents a visible element that can render itself and contains zero or more nested views. + /// View is the base class for all views on the screen and represents a visible element that can render itself and + /// contains zero or more nested views. /// /// /// - /// The View defines the base functionality for user interface elements in Terminal.Gui. Views + /// The View defines the base functionality for user interface elements in Terminal.Gui. Views /// can contain one or more subviews, can respond to user input and render themselves on the screen. /// /// - /// Views supports two layout styles: Absolute or Computed. The choice as to which layout style is used by the View + /// Views supports two layout styles: or . + /// The choice as to which layout style is used by the View /// is determined when the View is initialized. To create a View using Absolute layout, call a constructor that takes a - /// Rect parameter to specify the absolute position and size (the View.)/. To create a View + /// Rect parameter to specify the absolute position and size (the View.). To create a View /// using Computed layout use a constructor that does not take a Rect parameter and set the X, Y, Width and Height /// properties on the view. Both approaches use coordinates that are relative to the container they are being added to. /// @@ -60,9 +50,9 @@ namespace Terminal.Gui { /// properties are Dim and Pos objects that dynamically update the position of a view. /// The X and Y properties are of type /// and you can use either absolute positions, percentages or anchor - /// points. The Width and Height properties are of type + /// points. The Width and Height properties are of type /// and can use absolute position, - /// percentages and anchors. These are useful as they will take + /// percentages and anchors. These are useful as they will take /// care of repositioning views when view's frames are resized or /// if the terminal size changes. /// @@ -72,17 +62,17 @@ namespace Terminal.Gui { /// property. /// /// - /// Subviews (child views) can be added to a View by calling the method. + /// Subviews (child views) can be added to a View by calling the method. /// The container of a View can be accessed with the property. /// /// - /// To flag a region of the View's to be redrawn call . To flag the entire view - /// for redraw call . + /// To flag a region of the View's to be redrawn call . + /// To flag the entire view for redraw call . /// /// /// Views have a property that defines the default colors that subviews - /// should use for rendering. This ensures that the views fit in the context where - /// they are being used, and allows for themes to be plugged in. For example, the + /// should use for rendering. This ensures that the views fit in the context where + /// they are being used, and allows for themes to be plugged in. For example, the /// default colors for windows and toplevels uses a blue background, while it uses /// a white background for dialog boxes and a red background for errors. /// @@ -98,16 +88,16 @@ namespace Terminal.Gui { /// /// /// Views that are focusable should implement the to make sure that - /// the cursor is placed in a location that makes sense. Unix terminals do not have + /// the cursor is placed in a location that makes sense. Unix terminals do not have /// a way of hiding the cursor, so it can be distracting to have the cursor left at - /// the last focused view. So views should make sure that they place the cursor + /// the last focused view. So views should make sure that they place the cursor /// in a visually sensible place. /// /// /// The method is invoked when the size or layout of a view has - /// changed. The default processing system will keep the size and dimensions - /// for views that use the , and will recompute the - /// frames for the vies that use . + /// changed. The default processing system will keep the size and dimensions + /// for views that use the , and will recompute the + /// frames for the vies that use . /// /// public partial class View : Responder, ISupportInitializeNotification { @@ -333,7 +323,8 @@ namespace Terminal.Gui { bool tabStop = true; /// - /// This only be true if the is also true and the focus can be avoided by setting this to false + /// This only be if the is also + /// and the focus can be avoided by setting this to /// public bool TabStop { get => tabStop; @@ -431,7 +422,7 @@ namespace Terminal.Gui { /// /// Gets or sets a value indicating whether this wants mouse position reports. /// - /// true if want mouse position reports; otherwise, false. + /// if want mouse position reports; otherwise, . public virtual bool WantMousePositionReports { get; set; } /// @@ -518,7 +509,7 @@ namespace Terminal.Gui { Pos x, y; /// - /// Gets or sets the X position for the view (the column). Only used the is . + /// Gets or sets the X position for the view (the column). Only used if the is . /// /// The X Position. /// @@ -538,7 +529,7 @@ namespace Terminal.Gui { } /// - /// Gets or sets the Y position for the view (the row). Only used the is . + /// Gets or sets the Y position for the view (the row). Only used if the is . /// /// The y position (line). /// @@ -633,7 +624,7 @@ namespace Terminal.Gui { /// Verifies if the minimum width or height can be sets in the view. /// /// The size. - /// if the size can be set, otherwise. + /// if the size can be set, otherwise. public bool GetMinWidthHeight (out Size size) { size = Size.Empty; @@ -662,7 +653,7 @@ namespace Terminal.Gui { /// /// Sets the minimum width or height if the view can be resized. /// - /// if the size can be set, otherwise. + /// if the size can be set, otherwise. public bool SetMinWidthHeight () { if (GetMinWidthHeight (out Size size)) { @@ -686,7 +677,7 @@ namespace Terminal.Gui { /// /// Initializes a new instance of a class with the absolute - /// dimensions specified in the frame parameter. + /// dimensions specified in the parameter. /// /// The region covered by this view. /// @@ -704,12 +695,12 @@ namespace Terminal.Gui { /// /// /// Use , , , and properties to dynamically control the size and location of the view. - /// The will be created using - /// coordinates. The initial size ( will be + /// The will be created using + /// coordinates. The initial size () will be /// adjusted to fit the contents of , including newlines ('\n') for multiple lines. /// /// - /// If Height is greater than one, word wrapping is provided. + /// If is greater than one, word wrapping is provided. /// /// /// This constructor initialize a View with a of . @@ -724,15 +715,15 @@ namespace Terminal.Gui { /// /// /// The will be created at the given - /// coordinates with the given string. The size ( will be + /// coordinates with the given string. The size () will be /// adjusted to fit the contents of , including newlines ('\n') for multiple lines. /// /// /// No line wrapping is provided. /// /// - /// column to locate the Label. - /// row to locate the Label. + /// column to locate the View. + /// row to locate the View. /// text to initialize the property with. public View (int x, int y, ustring text) : this (TextFormatter.CalcRect (x, y, text), text) { } @@ -742,7 +733,7 @@ namespace Terminal.Gui { /// /// /// The will be created at the given - /// coordinates with the given string. The initial size ( will be + /// coordinates with the given string. The initial size () will be /// adjusted to fit the contents of , including newlines ('\n') for multiple lines. /// /// @@ -763,11 +754,11 @@ namespace Terminal.Gui { /// /// /// The will be created using - /// coordinates with the given string. The initial size ( will be + /// coordinates with the given string. The initial size () will be /// adjusted to fit the contents of , including newlines ('\n') for multiple lines. /// /// - /// If Height is greater than one, word wrapping is provided. + /// If is greater than one, word wrapping is provided. /// /// /// text to initialize the property with. @@ -921,7 +912,8 @@ namespace Terminal.Gui { /// Adds a subview (child) to this view. /// /// - /// The Views that have been added to this view can be retrieved via the property. See also + /// The Views that have been added to this view can be retrieved via the property. + /// See also /// public virtual void Add (View view) { @@ -961,7 +953,8 @@ namespace Terminal.Gui { /// /// Array of one or more views (can be optional parameter). /// - /// The Views that have been added to this view can be retrieved via the property. See also + /// The Views that have been added to this view can be retrieved via the property. + /// See also /// public void Add (params View [] views) { @@ -1133,7 +1126,7 @@ namespace Terminal.Gui { /// View-relative row. /// Absolute column; screen-relative. /// Absolute row; screen-relative. - /// Whether to clip the result of the ViewToScreen method, if set to true, the rcol, rrow values are clamped to the screen (terminal) dimensions (0..TerminalDim-1). + /// Whether to clip the result of the ViewToScreen method, if set to , the rcol, rrow values are clamped to the screen (terminal) dimensions (0..TerminalDim-1). internal void ViewToScreen (int col, int row, out int rcol, out int rrow, bool clipped = true) { // Computes the real row, col relative to the screen. @@ -1219,7 +1212,7 @@ namespace Terminal.Gui { /// /// View-relative region for the frame to be drawn. /// The padding to add around the outside of the drawn frame. - /// If set to true it fill will the contents. + /// If set to it fill will the contents. public void DrawFrame (Rect region, int padding = 0, bool fill = false) { var scrRect = ViewToScreen (region); @@ -1256,7 +1249,7 @@ namespace Terminal.Gui { /// Utility function to draw strings that contains a hotkey using a and the "focused" state. /// /// String to display, the underscore before a letter flags the next letter as the hotkey. - /// If set to true this uses the focused colors from the color scheme, otherwise the regular ones. + /// If set to this uses the focused colors from the color scheme, otherwise the regular ones. /// The color scheme to use. public void DrawHotString (ustring text, bool focused, ColorScheme scheme) { @@ -1273,7 +1266,7 @@ namespace Terminal.Gui { /// Col. /// Row. /// Whether to clip the result of the ViewToScreen method, - /// if set to true, the col, row values are clamped to the screen (terminal) dimensions (0..TerminalDim-1). + /// if set to , the col, row values are clamped to the screen (terminal) dimensions (0..TerminalDim-1). public void Move (int col, int row, bool clipped = true) { if (Driver.Rows == 0) { @@ -1355,7 +1348,7 @@ namespace Terminal.Gui { } /// - /// Method invoked when a subview is being added to this view. + /// Method invoked when a subview is being added to this view. /// /// The subview being added. public virtual void OnAdded (View view) @@ -1414,7 +1407,7 @@ namespace Terminal.Gui { /// /// Returns the most focused view in the chain of subviews (the leaf view that has the focus). /// - /// The most focused. + /// The most focused View. public View MostFocused { get { if (Focused == null) @@ -1485,7 +1478,7 @@ namespace Terminal.Gui { /// /// /// Overrides of must ensure they do not set Driver.Clip to a clip region - /// larger than the region parameter. + /// larger than the parameter, as this will cause the driver to clip the entire region. /// /// public virtual void Redraw (Rect bounds) @@ -1748,11 +1741,11 @@ namespace Terminal.Gui { /// If the key is already bound to a different it will be /// rebound to this one /// Commands are only ever applied to the current (i.e. this feature - /// cannot be used to switch focus to another view and perform multiple commands there) + /// cannot be used to switch focus to another view and perform multiple commands there) /// /// /// The command(s) to run on the when is pressed. - /// When specifying multiple, all commands will be applied in sequence. The bound strike + /// When specifying multiple commands, all commands will be applied in sequence. The bound strike /// will be consumed if any took effect. public void AddKeyBinding (Key key, params Command [] command) { @@ -1782,18 +1775,17 @@ namespace Terminal.Gui { } /// - /// Checks if key combination already exist. + /// Checks if the key binding already exists. /// /// The key to check. - /// true If the key already exist, falseotherwise. + /// If the key already exist, otherwise. public bool ContainsKeyBinding (Key key) { return KeyBindings.ContainsKey (key); } /// - /// Removes all bound keys from the View making including the default - /// key combinations such as cursor navigation, scrolling etc + /// Removes all bound keys from the View and resets the default bindings. /// public void ClearKeybindings () { @@ -1801,7 +1793,7 @@ namespace Terminal.Gui { } /// - /// Clears the existing keybinding (if any) for the given + /// Clears the existing keybinding (if any) for the given . /// /// public void ClearKeybinding (Key key) @@ -1810,7 +1802,7 @@ namespace Terminal.Gui { } /// - /// Removes all key bindings that trigger the given command. Views can have multiple different + /// Removes all key bindings that trigger the given command. Views can have multiple different /// keys bound to the same command and this method will clear all of them. /// /// @@ -1843,7 +1835,7 @@ namespace Terminal.Gui { } /// - /// Returns all commands that are supported by this + /// Returns all commands that are supported by this . /// /// public IEnumerable GetSupportedCommands () @@ -1913,7 +1905,7 @@ namespace Terminal.Gui { } /// - /// Invoked when a key is pressed + /// Invoked when a key is pressed. /// public event Action KeyDown; @@ -1943,7 +1935,7 @@ namespace Terminal.Gui { } /// - /// Invoked when a key is released + /// Invoked when a key is released. /// public event Action KeyUp; @@ -1973,7 +1965,7 @@ namespace Terminal.Gui { } /// - /// Finds the first view in the hierarchy that wants to get the focus if nothing is currently focused, otherwise, it does nothing. + /// Finds the first view in the hierarchy that wants to get the focus if nothing is currently focused, otherwise, does nothing. /// public void EnsureFocus () { @@ -2036,7 +2028,7 @@ namespace Terminal.Gui { /// /// Focuses the previous view. /// - /// true, if previous was focused, false otherwise. + /// if previous was focused, otherwise. public bool FocusPrev () { if (!CanBeVisible (this)) { @@ -2083,7 +2075,7 @@ namespace Terminal.Gui { /// /// Focuses the next view. /// - /// true, if next was focused, false otherwise. + /// if next was focused, otherwise. public bool FocusNext () { if (!CanBeVisible (this)) { @@ -2447,10 +2439,10 @@ namespace Terminal.Gui { /// /// Gets or sets a flag that determines whether the View will be automatically resized to fit the . - /// The default is `false`. Set to `true` to turn on AutoSize. If is `true` the + /// The default is . Set to to turn on AutoSize. If is the /// and will always be used if the text size is lower. If the text size is higher the bounds will /// be resized to fit it. - /// In addition, if is `true` the new values of and + /// In addition, if is the new values of and /// must be of the same types of the existing one to avoid breaking the settings. /// public virtual bool AutoSize { @@ -2469,9 +2461,10 @@ namespace Terminal.Gui { /// /// Gets or sets a flag that determines whether will have trailing spaces preserved - /// or not when is enabled. If `true` any trailing spaces will be trimmed when - /// either the property is changed or when is set to `true`. - /// The default is `false`. + /// or not when is enabled. If + /// any trailing spaces will be trimmed when either the property is changed or + /// when is set to . + /// The default is . /// public virtual bool PreserveTrailingSpaces { get => TextFormatter.PreserveTrailingSpaces; @@ -2713,7 +2706,7 @@ namespace Terminal.Gui { /// /// Get the width or height of the length. /// - /// trueif is the width (default)falseif is the height. + /// if is the width (default) if is the height. /// The length of the . public int GetHotKeySpecifierLength (bool isWidth = true) { @@ -2752,7 +2745,7 @@ namespace Terminal.Gui { } /// - /// Specifies the event arguments for . This is a higher-level construct + /// Specifies the event arguments for . This is a higher-level construct /// than the wrapped class and is used for the events defined on /// and subclasses of View (e.g. and ). /// @@ -2817,7 +2810,7 @@ namespace Terminal.Gui { /// Method invoked when a mouse event is generated /// /// - /// true, if the event was handled, false otherwise. + /// , if the event was handled, otherwise. public virtual bool OnMouseEvent (MouseEvent mouseEvent) { if (!Enabled) { @@ -2987,7 +2980,7 @@ namespace Terminal.Gui { /// /// The desired width. /// The real result width. - /// true if the width can be directly assigned, false otherwise. + /// if the width can be directly assigned, otherwise. public bool SetWidth (int desiredWidth, out int resultWidth) { return CanSetWidth (desiredWidth, out resultWidth); @@ -2998,7 +2991,7 @@ namespace Terminal.Gui { /// /// The desired height. /// The real result height. - /// true if the height can be directly assigned, false otherwise. + /// if the height can be directly assigned, otherwise. public bool SetHeight (int desiredHeight, out int resultHeight) { return CanSetHeight (desiredHeight, out resultHeight); @@ -3008,7 +3001,7 @@ namespace Terminal.Gui { /// Gets the current width based on the settings. /// /// The real current width. - /// true if the width can be directly assigned, false otherwise. + /// if the width can be directly assigned, otherwise. public bool GetCurrentWidth (out int currentWidth) { SetRelativeLayout (SuperView?.frame ?? frame); @@ -3021,7 +3014,7 @@ namespace Terminal.Gui { /// Calculate the height based on the settings. /// /// The real current height. - /// true if the height can be directly assigned, false otherwise. + /// if the height can be directly assigned, otherwise. public bool GetCurrentHeight (out int currentHeight) { SetRelativeLayout (SuperView?.frame ?? frame); @@ -3060,7 +3053,7 @@ namespace Terminal.Gui { /// /// The view. /// The method name. - /// if it's overridden, otherwise. + /// if it's overridden, otherwise. public bool IsOverridden (View view, string method) { Type t = view.GetType ();