API docs updates

Core.cs

@@ -145,9 +145,12 @@ namespace Terminal {
 	///    added to a SuperView, so your subclasses should not rely on ColorScheme being
 	///    set at construction time.
 	/// </para>
+	/// <para>
+	///    Using ColorSchemes has the advantage that your application will work both
+	///    in color as well as black and white displays.
+	/// </para>
 	/// </remarks>
 	public class View : Responder, IEnumerable {
-		string id = "";
 		View container = null;
 		View focused = null;
 
@@ -170,12 +173,11 @@ namespace Terminal {
 		// The frame for the object
 		Rect frame;
 
-		public string Id {
-			get => id;
-			set {
-				id = value;
-			}
-		}
+		/// <summary>
+		/// Gets or sets an identifier for the view;
+		/// </summary>
+		/// <value>The identifier.</value>
+		public string Id { get; set; } = "";
 
 		/// <summary>
 		/// Gets or sets a value indicating whether this <see cref="T:Terminal.View"/> want mouse position reports.
@@ -816,7 +818,7 @@ namespace Terminal {
 		/// <returns>A <see cref="T:System.String"/> that represents the current <see cref="T:Terminal.View"/>.</returns>
 		public override string ToString ()
 		{
-			return $"{GetType ().Name}({id})({Frame})";
+			return $"{GetType ().Name}({Id})({Frame})";
 		}
 	}
 
@@ -830,6 +832,10 @@ namespace Terminal {
 	///   </para>
 	/// </remarks>
 	public class Toplevel : View {
+		/// <summary>
+		/// This flag is checked on each iteration of the mainloop and it continues
+		/// running until this flag is set to false.   
+		/// </summary>
 		public bool Running;
 
 		/// <summary>
@@ -1143,6 +1149,9 @@ namespace Terminal {
 			Current = Top;
 		}
 
+		/// <summary>
+		/// Captures the execution state for the provided TopLevel view.
+		/// </summary>
 		public class RunState : IDisposable {
 			internal RunState (Toplevel view)
 			{
@@ -1150,12 +1159,25 @@ namespace Terminal {
 			}
 			internal Toplevel Toplevel;
 
+			/// <summary>
+			/// Releases all resource used by the <see cref="T:Terminal.Application.RunState"/> object.
+			/// </summary>
+			/// <remarks>Call <see cref="Dispose"/> when you are finished using the <see cref="T:Terminal.Application.RunState"/>. The
+			/// <see cref="Dispose"/> method leaves the <see cref="T:Terminal.Application.RunState"/> in an unusable state. After
+			/// calling <see cref="Dispose"/>, you must release all references to the
+			/// <see cref="T:Terminal.Application.RunState"/> so the garbage collector can reclaim the memory that the
+			/// <see cref="T:Terminal.Application.RunState"/> was occupying.</remarks>
 			public void Dispose ()
 			{
 				Dispose (true);
 				GC.SuppressFinalize (this);
 			}
 
+			/// <summary>
+			/// Dispose the specified disposing.
+			/// </summary>
+			/// <returns>The dispose.</returns>
+			/// <param name="disposing">If set to <c>true</c> disposing.</param>
 			public virtual void Dispose (bool disposing)
 			{
 				if (Toplevel != null) {
@@ -1370,7 +1392,7 @@ namespace Terminal {
 			}
 		}
 
-		public static bool DebugDrawBounds;
+		internal static bool DebugDrawBounds;
 
 		// Need to look into why this does not work properly.
 		static void DrawBounds (View v)

Driver.cs

@@ -16,21 +16,69 @@ namespace Terminal {
 	/// Basic colors that can be used to set the foreground and background colors in console applications.  These can only be
 	/// </summary>
 	public enum Color {
+		/// <summary>
+		/// The black color.
+		/// </summary>
 		Black,
+		/// <summary>
+		/// The blue color.
+		/// </summary>
 		Blue,
+		/// <summary>
+		/// The green color.
+		/// </summary>
 		Green,
+		/// <summary>
+		/// The cyan color.
+		/// </summary>
 		Cyan,
+		/// <summary>
+		/// The red color.
+		/// </summary>
 		Red,
+		/// <summary>
+		/// The magenta color.
+		/// </summary>
 		Magenta,
+		/// <summary>
+		/// The brown color.
+		/// </summary>
 		Brown,
+		/// <summary>
+		/// The gray color.
+		/// </summary>
 		Gray,
+		/// <summary>
+		/// The dark gray color.
+		/// </summary>
 		DarkGray,
+		/// <summary>
+		/// The bright bBlue color.
+		/// </summary>
 		BrightBlue,
+		/// <summary>
+		/// The bright green color.
+		/// </summary>
 		BrightGreen,
+		/// <summary>
+		/// The brigh cyan color.
+		/// </summary>
 		BrighCyan,
+		/// <summary>
+		/// The bright red color.
+		/// </summary>
 		BrightRed,
+		/// <summary>
+		/// The bright magenta color.
+		/// </summary>
 		BrightMagenta,
+		/// <summary>
+		/// The bright yellow color.
+		/// </summary>
 		BrightYellow,
+		/// <summary>
+		/// The White color.
+		/// </summary>
 		White
 	}
 
@@ -59,18 +107,58 @@ namespace Terminal {
 	/// views contained inside.
 	/// </summary>
 	public class ColorScheme {
+		/// <summary>
+		/// The default color for text, when the view is not focused.
+		/// </summary>
 		public Attribute Normal;
+		/// <summary>
+		/// The color for text when the view has the focus.
+		/// </summary>
 		public Attribute Focus;
+
+		/// <summary>
+		/// The color for the hotkey when a view is not focused
+		/// </summary>
 		public Attribute HotNormal;
+
+		/// <summary>
+		/// The color for the hotkey when the view is focused.
+		/// </summary>
 		public Attribute HotFocus;
 	}
 
+	/// <summary>
+	/// The default ColorSchemes for the application.
+	/// </summary>
 	public static class Colors {
-		public static ColorScheme Base, Dialog, Menu, Error;
+		/// <summary>
+		/// The base color scheme, for the default toplevel views.
+		/// </summary>
+		public static ColorScheme Base;
+		/// <summary>
+		/// The dialog color scheme, for standard popup dialog boxes
+		/// </summary>
+		public static ColorScheme Dialog;
+
+		/// <summary>
+		/// The menu bar color
+		/// </summary>
+		public static ColorScheme Menu;
+
+		/// <summary>
+		/// The color scheme for showing errors.
+		/// </summary>
+		public static ColorScheme Error;
 
 	}
 
+	/// <summary>
+	/// Special characters that can be drawn with Driver.AddSpecial.
+	/// </summary>
 	public enum SpecialChar {
+		/// <summary>
+		/// Horizontal line character.
+		/// </summary>
 		HLine,
 	}
 
@@ -78,14 +166,45 @@ namespace Terminal {
 	/// ConsoleDriver is an abstract class that defines the requirements for a console driver.   One implementation if the CursesDriver, and another one uses the .NET Console one.
 	/// </summary>
 	public abstract class ConsoleDriver {
+		/// <summary>
+		/// The current number of columns in the terminal.
+		/// </summary>
 		public abstract int Cols { get; }
+		/// <summary>
+		/// The current number of rows in the terminal.
+		/// </summary>
 		public abstract int Rows { get; }
+		/// <summary>
+		/// Initializes the driver
+		/// </summary>
+		/// <param name="terminalResized">Method to invoke when the terminal is resized.</param>
 		public abstract void Init (Action terminalResized);
+		/// <summary>
+		/// Moves the cursor to the specified column and row.
+		/// </summary>
+		/// <param name="col">Column to move the cursor to.</param>
+		/// <param name="row">Row to move the cursor to.</param>
 		public abstract void Move (int col, int row);
-		public abstract void AddCh (int ch);
+		/// <summary>
+		/// Adds the specified rune to the display at the current cursor position
+		/// </summary>
+		/// <param name="rune">Rune to add.</param>
+		public abstract void AddCh (int rune);
+		/// <summary>
+		/// Adds the specified 
+		/// </summary>
+		/// <param name="str">String.</param>
 		public abstract void AddStr (string str);
 		public abstract void PrepareToRun (MainLoop mainLoop, Action<KeyEvent> target, Action<MouseEvent> mouse);
+
+		/// <summary>
+		/// Updates the screen to reflect all the changes that have been done to the display buffer
+		/// </summary>
 		public abstract void Refresh ();
+
+		/// <summary>
+		/// Ends the execution of the console driver.
+		/// </summary>
 		public abstract void End ();
 		public abstract void RedrawTop ();
 		public abstract void SetAttribute (Attribute c);
@@ -95,14 +214,32 @@ namespace Terminal {
 
 		// Advanced uses - set colors to any pre-set pairs, you would need to init_color
 		// that independently with the R, G, B values.
-		public abstract void SetColors (short foreColorId, short backgroundColorId);
+		/// <summary>
+		/// Advanced uses - set colors to any pre-set pairs, you would need to init_color 
+		/// that independently with the R, G, B values.
+		/// </summary>
+		/// <param name="foregroundColorId">Foreground color identifier.</param>
+		/// <param name="backgroundColorId">Background color identifier.</param>
+		public abstract void SetColors (short foregroundColorId, short backgroundColorId);
 
 		public abstract void DrawFrame (Rect region, bool fill);
+		/// <summary>
+		/// Draws a special characters in the screen
+		/// </summary>
+		/// <param name="ch">Ch.</param>
 		public abstract void AddSpecial (SpecialChar ch);
 
+		/// <summary>
+		/// Suspend the application, typically needs to save the state, suspend the app and upon return, reset the console driver.
+		/// </summary>
 		public abstract void Suspend ();
 
 		Rect clip;
+
+		/// <summary>
+		/// Controls the current clipping region that AddCh/AddStr is subject to.
+		/// </summary>
+		/// <value>The clip.</value>
 		public Rect Clip {
 			get => clip;
 			set => this.clip = value;
@@ -115,7 +252,7 @@ namespace Terminal {
 	/// <summary>
 	/// This is the Curses driver for the gui.cs/Terminal framework.
 	/// </summary>
-	public class CursesDriver : ConsoleDriver {
+	internal class CursesDriver : ConsoleDriver {
 		Action terminalResized;
 
 		public override int Cols => Curses.Cols;
@@ -139,14 +276,14 @@ namespace Terminal {
 		}
 
 		static bool sync;
-		public override void AddCh (int ch)
+		public override void AddCh (int rune)
 		{
 			if (Clip.Contains (ccol, crow)) {
 				if (needMove) {
 					Curses.move (crow, ccol);
 					needMove = false;
 				}
-				Curses.addch (ch);
+				Curses.addch (rune);
 			} else
 				needMove = true;
 			if (sync)
@@ -166,8 +303,8 @@ namespace Terminal {
 		public override void AddStr (string str)
 		{
 			// TODO; optimize this to determine if the str fits in the clip region, and if so, use Curses.addstr directly
-			foreach (var c in str)
-				AddCh ((int)c);
+			foreach (var rune in str)
+				AddCh ((int)rune);
 		}
 
 		public override void Refresh () => Curses.refresh ();
@@ -488,4 +625,4 @@ namespace Terminal {
 			return true;
 		}
 	}
-}
+}

Event.cs

@@ -20,6 +20,9 @@ namespace Terminal {
 	/// <para>
 	///   Control keys are the values between 1 and 26 corresponding to Control-A to Control-Z
 	/// </para>
+	/// <para>
+	///   Unicode runes are also stored here, the letter 'A" for example is encoded as a value 65 (not surfaced in the enum).
+	/// </para>
 	/// </remarks>
 	public enum Key : uint {
 		CharMask = 0xfffff,
@@ -30,71 +33,251 @@ namespace Terminal {
 		/// </summary>
 		SpecialMask = 0xfff00000,
 
-
+		/// <summary>
+	        /// The key code for the user pressing Control-A
+		/// </summary>
 		ControlA = 1,
+		/// <summary>
+		/// The key code for the user pressing Control-B
+		/// </summary>
 		ControlB,
+		/// <summary>
+		/// The key code for the user pressing Control-C
+		/// </summary>
 		ControlC,
+		/// <summary>
+		/// The key code for the user pressing Control-D
+		/// </summary>
 		ControlD,
+		/// <summary>
+		/// The key code for the user pressing Control-E
+		/// </summary>
 		ControlE,
+		/// <summary>
+		/// The key code for the user pressing Control-F
+		/// </summary>
 		ControlF,
+		/// <summary>
+		/// The key code for the user pressing Control-G
+		/// </summary>
 		ControlG,
+		/// <summary>
+		/// The key code for the user pressing Control-H
+		/// </summary>
 		ControlH,
+		/// <summary>
+		/// The key code for the user pressing Control-I (same as the tab key).
+		/// </summary>
 		ControlI,
+		/// <summary>
+		/// The key code for the user pressing the tab key (same as pressing Control-I).
+		/// </summary>
 		Tab = ControlI,
+		/// <summary>
+		/// The key code for the user pressing Control-J
+		/// </summary>
 		ControlJ,
+		/// <summary>
+		/// The key code for the user pressing Control-K
+		/// </summary>
 		ControlK,
+		/// <summary>
+		/// The key code for the user pressing Control-L
+		/// </summary>
 		ControlL,
+		/// <summary>
+		/// The key code for the user pressing Control-M
+		/// </summary>
 		ControlM,
+		/// <summary>
+		/// The key code for the user pressing Control-N (same as the return key).
+		/// </summary>
 		ControlN,
+		/// <summary>
+		/// The key code for the user pressing Control-O
+		/// </summary>
 		ControlO,
+		/// <summary>
+		/// The key code for the user pressing Control-P
+		/// </summary>
 		ControlP,
+		/// <summary>
+		/// The key code for the user pressing Control-Q
+		/// </summary>
 		ControlQ,
+		/// <summary>
+		/// The key code for the user pressing Control-R
+		/// </summary>
 		ControlR,
+		/// <summary>
+		/// The key code for the user pressing Control-S
+		/// </summary>
 		ControlS,
+		/// <summary>
+		/// The key code for the user pressing Control-T
+		/// </summary>
 		ControlT,
+		/// <summary>
+		/// The key code for the user pressing Control-U
+		/// </summary>
 		ControlU,
+		/// <summary>
+		/// The key code for the user pressing Control-V
+		/// </summary>
 		ControlV,
+		/// <summary>
+		/// The key code for the user pressing Control-W
+		/// </summary>
 		ControlW,
+		/// <summary>
+		/// The key code for the user pressing Control-X
+		/// </summary>
 		ControlX,
+		/// <summary>
+		/// The key code for the user pressing Control-Y
+		/// </summary>
 		ControlY,
+		/// <summary>
+		/// The key code for the user pressing Control-Z
+		/// </summary>
 		ControlZ,
+			
+		/// <summary>
+		/// The key code for the user pressing the escape key
+		/// </summary>
 		Esc = 27,
+
+		/// <summary>
+		/// The key code for the user pressing the return key.
+		/// </summary>
 		Enter = '\n',
+
+		/// <summary>
+		/// The key code for the user pressing the space bar
+		/// </summary>
 		Space = 32,
+
+		/// <summary>
+		/// The key code for the user pressing the delete key.
+		/// </summary>
 		Delete = 127,
 
+		/// <summary>
+		///   When this value is set, the Key encodes the sequence Alt-KeyValue.
+		///   And the actual value must be extracted by removing the AltMask.
+		/// </summary>
 		AltMask = 0x80000000,
 
+		/// <summary>
+		/// Backspace key.
+		/// </summary>
 		Backspace = 0x100000,
+
+		/// <summary>
+		/// Cursor up key
+		/// </summary>
 		CursorUp,
+		/// <summary>
+		/// Cursor down key.
+		/// </summary>
 		CursorDown,
+		/// <summary>
+		/// Cursor left key.
+		/// </summary>
 		CursorLeft,
+		/// <summary>
+		/// Cursor right key.
+		/// </summary>
 		CursorRight,
+		/// <summary>
+		/// Page Up key.
+		/// </summary>
 		PageUp,
+		/// <summary>
+		/// Page Down key.
+		/// </summary>
 		PageDown,
+		/// <summary>
+		/// Home key
+		/// </summary>
 		Home,
+		/// <summary>
+		/// End key
+		/// </summary>
 		End,
+		/// <summary>
+		/// Delete character key
+		/// </summary>
 		DeleteChar,
+		/// <summary>
+		/// Insert character key
+		/// </summary>
 		InsertChar,
+		/// <summary>
+		/// F1 key.
+		/// </summary>
 		F1,
+		/// <summary>
+		/// F2 key.
+		/// </summary>
 		F2,
+		/// <summary>
+		/// F3 key.
+		/// </summary>
 		F3,
+		/// <summary>
+		/// F4 key.
+		/// </summary>
 		F4,
+		/// <summary>
+		/// F5 key.
+		/// </summary>
 		F5,
+		/// <summary>
+		/// F6 key.
+		/// </summary>
 		F6,
+		/// <summary>
+		/// F7 key.
+		/// </summary>
 		F7,
+		/// <summary>
+		/// F8 key.
+		/// </summary>
 		F8,
+		/// <summary>
+		/// F9 key.
+		/// </summary>
 		F9,
+		/// <summary>
+		/// F10 key.
+		/// </summary>
 		F10,
+		/// <summary>
+		/// Shift-tab key (backwards tab key).
+		/// </summary>
 		BackTab,
+		/// <summary>
+		/// A key with an unknown mapping was raised.
+		/// </summary>
 		Unknown
 	}
 
 	/// <summary>
-	/// Describes a keyboard event
+	/// Describes a keyboard event.
 	/// </summary>
 	public struct KeyEvent {
+
+		/// <summary>
+		/// Symb olid definition for the key.
+		/// </summary>
 		public Key Key;
+
+		/// <summary>
+		///   The key value cast to an integer, you will typicall use this for
+		///   extracting the Unicode rune value out of a key, when none of the
+		///   symbolic options are in use.
+		/// </summary>
 		public int KeyValue => (int)Key;
 
 		/// <summary>
@@ -109,6 +292,9 @@ namespace Terminal {
 		/// <value><c>true</c> if is ctrl; otherwise, <c>false</c>.</value>
 		public bool IsCtrl => ((uint)Key >= 1) && ((uint)Key <= 26);
 
+		/// <summary>
+		///   Constructs a new KeyEvent from the provided Key value - can be a rune cast into a Key value
+		/// </summary>
 		public KeyEvent (Key k)
 		{
 			Key = k;
@@ -123,30 +309,105 @@ namespace Terminal {
 	/// </remarks>
 	[Flags]
 	public enum MouseFlags {
+		/// <summary>
+		/// The first mouse button was pressed.
+		/// </summary>
 		Button1Pressed = unchecked((int)0x2),
+		/// <summary>
+		/// The first mouse button was released.
+		/// </summary>
 		Button1Released = unchecked((int)0x1),
+		/// <summary>
+		/// The first mouse button was clicked (press+release).
+		/// </summary>
 		Button1Clicked = unchecked((int)0x4),
+		/// <summary>
+		/// The first mouse button was double-clicked.
+		/// </summary>
 		Button1DoubleClicked = unchecked((int)0x8),
+		/// <summary>
+		/// The first mouse button was tripple-clicked.
+		/// </summary>
 		Button1TripleClicked = unchecked((int)0x10),
+		/// <summary>
+		/// The second mouse button was pressed.
+		/// </summary>
 		Button2Pressed = unchecked((int)0x80),
+		/// <summary>
+		/// The second mouse button was released.
+		/// </summary>
 		Button2Released = unchecked((int)0x40),
+		/// <summary>
+		/// The second mouse button was clicked (press+release).
+		/// </summary>
 		Button2Clicked = unchecked((int)0x100),
+		/// <summary>
+		/// The second mouse button was double-clicked.
+		/// </summary>
 		Button2DoubleClicked = unchecked((int)0x200),
+		/// <summary>
+		/// The second mouse button was tripple-clicked.
+		/// </summary>
 		Button2TrippleClicked = unchecked((int)0x400),
+		/// <summary>
+		/// The third mouse button was pressed.
+		/// </summary>
 		Button3Pressed = unchecked((int)0x2000),
+		/// <summary>
+		/// The third mouse button was released.
+		/// </summary>
 		Button3Released = unchecked((int)0x1000),
+		/// <summary>
+		/// The third mouse button was clicked (press+release).
+		/// </summary>
 		Button3Clicked = unchecked((int)0x4000),
+		/// <summary>
+		/// The third mouse button was double-clicked.
+		/// </summary>
 		Button3DoubleClicked = unchecked((int)0x8000),
+		/// <summary>
+		/// The third mouse button was tripple-clicked.  
+		/// </summary>
 		Button3TripleClicked = unchecked((int)0x10000),
+		/// <summary>
+		/// The fourth mouse button was pressed.
+		/// </summary>
 		Button4Pressed = unchecked((int)0x80000),
+		/// <summary>
+		/// The fourth mouse button was released.
+		/// </summary>
 		Button4Released = unchecked((int)0x40000),
+		/// <summary>
+		/// The fourth button was clicked (press+release).
+		/// </summary>
 		Button4Clicked = unchecked((int)0x100000),
+		/// <summary>
+		/// The fourth button was double-clicked.
+		/// </summary>
 		Button4DoubleClicked = unchecked((int)0x200000),
+		/// <summary>
+		/// The fourth button was tripple-clicked.
+		/// </summary>
 		Button4TripleClicked = unchecked((int)0x400000),
+		/// <summary>
+		/// The fourth button was pressed.
+		/// </summary>
 		ButtonShift = unchecked((int)0x2000000),
+		/// <summary>
+		/// Flag: the shift key was pressed when the mouse button took place.
+		/// </summary>
 		ButtonCtrl = unchecked((int)0x1000000),
+		/// <summary>
+		/// Flag: the alt key was pressed when the mouse button took place.
+		/// </summary>
 		ButtonAlt = unchecked((int)0x4000000),
+		/// <summary>
+		/// The mouse position is being reported in this event.
+		/// </summary>
 		ReportMousePosition = unchecked((int)0x8000000),
+		/// <summary>
+		/// Mask that captures all the events.
+		/// </summary>
 		AllEvents = unchecked((int)0x7ffffff),
 	}
 
@@ -169,7 +430,6 @@ namespace Terminal {
 		/// </summary>
 		public MouseFlags Flags;
 
-
 		/// <summary>
 		/// Returns a <see cref="T:System.String"/> that represents the current <see cref="T:Terminal.MouseEvent"/>.
 		/// </summary>
@@ -179,4 +439,4 @@ namespace Terminal {
 			return $"({X},{Y}:{Flags}";
 		}
 	}
-}
+}

Views/Menu.cs

@@ -101,6 +101,10 @@ namespace Terminal {
 			TitleLength = len;
 		}
 
+		/// <summary>
+		/// Gets or sets the title to display.
+		/// </summary>
+		/// <value>The title.</value>
 		public string Title { get; set; }
 		public MenuItem [] Children { get; set; }
 		internal int TitleLength { get; private set; }

Views/RadioGroup.cs

@@ -37,7 +37,6 @@ namespace Terminal {
 		/// <param name="y">The y coordinate.</param>
 		/// <param name="radioLabels">Radio labels, the strings can contain hotkeys using an undermine before the letter.</param>
 		/// <param name="selected">The item to be selected, the value is clamped to the number of items.</param>		
-		/// <summary>
 		public RadioGroup (int x, int y, string [] radioLabels, int selected = 0) : this (MakeRect (x, y, radioLabels), radioLabels, selected)
 		{
 		}