Docs, plus some bones

Terminal.Gui/Core.cs

@@ -1289,9 +1289,9 @@ namespace Terminal.Gui {
 			/// <summary>
 			/// Releases all resource used by the <see cref="T:Terminal.Gui.Application.RunState"/> object.
 			/// </summary>
-			/// <remarks>Call <see cref="Dispose"/> when you are finished using the <see cref="T:Terminal.Gui.Application.RunState"/>. The
-			/// <see cref="Dispose"/> method leaves the <see cref="T:Terminal.Gui.Application.RunState"/> in an unusable state. After
-			/// calling <see cref="Dispose"/>, you must release all references to the
+			/// <remarks>Call <see cref="Dispose()"/> when you are finished using the <see cref="T:Terminal.Gui.Application.RunState"/>. The
+			/// <see cref="Dispose()"/> method leaves the <see cref="T:Terminal.Gui.Application.RunState"/> in an unusable state. After
+			/// calling <see cref="Dispose()"/>, you must release all references to the
 			/// <see cref="T:Terminal.Gui.Application.RunState"/> so the garbage collector can reclaim the memory that the
 			/// <see cref="T:Terminal.Gui.Application.RunState"/> was occupying.</remarks>
 			public void Dispose ()
@@ -1305,7 +1305,7 @@ namespace Terminal.Gui {
 			/// </summary>
 			/// <returns>The dispose.</returns>
 			/// <param name="disposing">If set to <c>true</c> disposing.</param>
-			public virtual void Dispose (bool disposing)
+			protected virtual void Dispose (bool disposing)
 			{
 				if (Toplevel != null) {
 					Application.End (Toplevel);
@@ -1417,6 +1417,19 @@ namespace Terminal.Gui {
 			}
 		}
 
+		/// <summary>
+		/// Building block API: Prepares the provided toplevel for execution.
+		/// </summary>
+		/// <returns>The runstate handle that needs to be passed to the End() method upon completion.</returns>
+		/// <param name="toplevel">Toplevel to prepare execution for.</param>
+		/// <remarks>
+		///  This method prepares the provided toplevel for running with the focus,
+		///  it adds this to the list of toplevels, sets up the mainloop to process the 
+		///  event, lays out the subviews, focuses the first element, and draws the
+		///  toplevel in the screen.   This is usually followed by executing
+		///  the <see cref="RunLoop"/> method, and then the <see cref="End(RunState)"/> method upon termination which will
+		///   undo these changes.
+		/// </remarks>
 		static public RunState Begin (Toplevel toplevel)
 		{
 			if (toplevel == null)
@@ -1436,12 +1449,16 @@ namespace Terminal.Gui {
 			return rs;
 		}
 
-		static public void End (RunState rs)
+		/// <summary>
+		/// Building block API: completes the exection of a Toplevel that was started with Begin.
+		/// </summary>
+		/// <param name="runState">The runstate returned by the <see cref="Begin(Toplevel)"/> method.</param>
+		static public void End (RunState runState)
 		{
-			if (rs == null)
-				throw new ArgumentNullException (nameof (rs));
+			if (runState == null)
+				throw new ArgumentNullException (nameof (runState));
 
-			rs.Dispose ();
+			runState.Dispose ();
 		}
 
 		static void Shutdown ()
@@ -1466,7 +1483,7 @@ namespace Terminal.Gui {
 		/// </summary>
 		public static void Refresh ()
 		{
-			Driver.RedrawTop ();
+			Driver.UpdateScreen ();
 			View last = null;
 			foreach (var v in toplevels.Reverse ()) {
 				v.SetNeedsDisplay ();
@@ -1491,12 +1508,14 @@ namespace Terminal.Gui {
 		}
 
 		/// <summary>
-		///   Runs the main loop for the created dialog
+		///   Building block API: Runs the main loop for the created dialog
 		/// </summary>
 		/// <remarks>
 		///   Use the wait parameter to control whether this is a
-		///   blocking or non-blocking call.
+		///   blocking or non-blocking call.   
 		/// </remarks>
+		/// <param name="state">The state returned by the Begin method.</param>
+		/// <param name="wait">By default this is true which will execute the runloop waiting for events, if you pass false, you can use this method to run a single iteration of the events.</param>
 		public static void RunLoop (RunState state, bool wait = true)
 		{
 			if (state == null)
@@ -1553,6 +1572,17 @@ namespace Terminal.Gui {
 		///     To make a toplevel stop execution, set the "Running"
 		///     property to false.
 		///   </para>
+		///   <para>
+		///     This is equivalent to calling Begin on the toplevel view, followed by RunLoop with the
+		///     returned value, and then calling end on the return value.
+		///   </para>
+		///   <para>
+		///     Alternatively, if your program needs to control the main loop and needs to 
+		///     process events manually, you can invoke Begin to set things up manually and then
+		///     repeatedly call RunLoop with the wait parameter set to false.   By doing this
+		///     the RunLoop method will only process any pending events, timers, idle handlers and
+		///     then return control immediately.
+		///   </para>
 		/// </remarks>
 		public static void Run (Toplevel view)
 		{

Terminal.Gui/Driver.cs

@@ -268,7 +268,16 @@ namespace Terminal.Gui {
 		/// Ends the execution of the console driver.
 		/// </summary>
 		public abstract void End ();
-		public abstract void RedrawTop ();
+
+		/// <summary>
+		/// Redraws the physical screen with the contents that have been queued up via any of the printing commands.
+		/// </summary>
+		public abstract void UpdateScreen ();
+
+		/// <summary>
+		/// Selects the specified attribute as the attribute to use for future calls to AddRune, AddString.
+		/// </summary>
+		/// <param name="c">C.</param>
 		public abstract void SetAttribute (Attribute c);
 
 		// Set Colors from limit sets of colors
@@ -284,6 +293,12 @@ namespace Terminal.Gui {
 		/// <param name="backgroundColorId">Background color identifier.</param>
 		public abstract void SetColors (short foregroundColorId, short backgroundColorId);
 
+		/// <summary>
+		/// Draws a frame on the specified region with the specified padding around the frame.
+		/// </summary>
+		/// <param name="region">Region where the frame will be drawn..</param>
+		/// <param name="padding">Padding to add on the sides.</param>
+		/// <param name="fill">If set to <c>true</c> it will clear the contents with the current color, otherwise the contents will be left untouched.</param>
 		public virtual void DrawFrame (Rect region, int padding, bool fill)
 		{
 			int width = region.Width;
@@ -481,7 +496,7 @@ namespace Terminal.Gui {
 
 		public override void Refresh () => Curses.refresh ();
 		public override void End () => Curses.endwin ();
-		public override void RedrawTop () => window.redrawwin ();
+		public override void UpdateScreen () => window.redrawwin ();
 		public override void SetAttribute (Attribute c) => Curses.attrset (c.value);
 		public Curses.Window window;
 
@@ -875,7 +890,7 @@ namespace Terminal.Gui {
 					crow++;
 			}
 			if (sync)
-				RedrawTop ();
+				UpdateScreen ();
 		}
 
 		public override void AddStr (ustring str)
@@ -951,7 +966,7 @@ namespace Terminal.Gui {
 			Console.ForegroundColor = (ConsoleColor)((color >> 16) & 0xffff);
 		}
 
-		public override void RedrawTop ()
+		public override void UpdateScreen ()
 		{
 			int rows = Rows;
 			int cols = Cols;

Terminal.Gui/Views/Button.cs

@@ -62,7 +62,7 @@ namespace Terminal.Gui {
 		///   text length.   This button is not a default button.
 		/// </remarks>
 		/// <param name="text">The button's text</param>
-		public Button (string text) : this (0, 0, text) { }
+		public Button (ustring text) : this (0, 0, text) { }
 
 		/// <summary>
 		///   Public constructor, creates a button based on
@@ -75,7 +75,7 @@ namespace Terminal.Gui {
 		/// </remarks>
 		/// <param name="text">The button's text</param>
 		/// <param name="is_default">If set, this makes the button the default button in the current view, which means that if the user presses return on a view that does not handle return, it will be treated as if he had clicked on the button</param>
-		public Button (string text, bool is_default) : this (0, 0, text, is_default) { }
+		public Button (ustring text, bool is_default) : this (0, 0, text, is_default) { }
 
 		/// <summary>
 		///   Public constructor, creates a button based on
@@ -88,7 +88,7 @@ namespace Terminal.Gui {
 		/// <param name="x">X position where the button will be shown.</param>
 		/// <param name="y">Y position where the button will be shown.</param>
 		/// <param name="text">The button's text</param>
-		public Button (int x, int y, string text) : this (x, y, text, false) { }
+		public Button (int x, int y, ustring text) : this (x, y, text, false) { }
 
 		/// <summary>
 		///   The text displayed by this widget.
@@ -138,7 +138,7 @@ namespace Terminal.Gui {
 		/// <param name="y">Y position where the button will be shown.</param>
 		/// <param name="text">The button's text</param>
 		/// <param name="is_default">If set, this makes the button the default button in the current view, which means that if the user presses return on a view that does not handle return, it will be treated as if he had clicked on the button</param>
-		public Button (int x, int y, string text, bool is_default)
+		public Button (int x, int y, ustring text, bool is_default)
 		    : base (new Rect (x, y, text.Length + 4 + (is_default ? 2 : 0), 1))
 		{
 			CanFocus = true;

Terminal.Gui/Views/Dialog.cs

@@ -25,7 +25,7 @@ namespace Terminal.Gui {
 		/// <param name="width">Width for the dialog.</param>
 		/// <param name="height">Height for the dialog.</param>
 		/// <param name="buttons">Optional buttons to lay out at the bottom of the dialog.</param>
-		public Dialog (string title, int width, int height, params Button [] buttons) : base (Application.MakeCenteredRect (new Size (width, height)), title, padding: padding)
+		public Dialog (ustring title, int width, int height, params Button [] buttons) : base (Application.MakeCenteredRect (new Size (width, height)), title, padding: padding)
 		{
 			ColorScheme = Colors.Dialog;
 

Terminal.Gui/Views/FileDialog.cs

@@ -0,0 +1,125 @@
+// 
+// FileDialog.cs: File system dialogs for open and save
+//
+
+using System;
+using System.Collections.Generic;
+using NStack;
+
+namespace Terminal.Gui {
+	public class FileDialog : Dialog {
+		Button prompt;
+		Label nameFieldLabel, message;
+
+		public FileDialog (ustring title, ustring prompt, ustring nameFieldLabel, ustring message) : base (title, Driver.Cols - 20, Driver.Rows - 6, null)
+		{
+			this.prompt = new Button (prompt);
+			AddButton (this.prompt);
+
+			this.nameFieldLabel = new Label (Rect.Empty, nameFieldLabel);
+			this.message = new Label (Rect.Empty, message);
+		}
+
+		/// <summary>
+		/// Gets or sets the prompt label for the button displayed to the user
+		/// </summary>
+		/// <value>The prompt.</value>
+		public ustring Prompt {
+			get => prompt.Text;
+			set {
+				prompt.Text = value;
+			}
+		}
+
+		/// <summary>
+		/// Gets or sets the name field label.
+		/// </summary>
+		/// <value>The name field label.</value>
+		public ustring NameFieldLabel {
+			get => nameFieldLabel.Text;
+			set {
+				nameFieldLabel.Text = value;
+			}
+		}
+
+		/// <summary>
+		/// Gets or sets the message displayed to the user, defaults to nothing
+		/// </summary>
+		/// <value>The message.</value>
+		public ustring Message { get; set; }
+
+
+		/// <summary>
+		/// Gets or sets a value indicating whether this <see cref="T:Terminal.Gui.FileDialog"/> can create directories.
+		/// </summary>
+		/// <value><c>true</c> if can create directories; otherwise, <c>false</c>.</value>
+		public bool CanCreateDirectories { get; set; }
+
+		/// <summary>
+		/// Gets or sets a value indicating whether this <see cref="T:Terminal.Gui.FileDialog"/> is extension hidden.
+		/// </summary>
+		/// <value><c>true</c> if is extension hidden; otherwise, <c>false</c>.</value>
+		public bool IsExtensionHidden { get; set; }
+
+		/// <summary>
+		/// Gets or sets the directory path for this panel
+		/// </summary>
+		/// <value>The directory path.</value>
+		public ustring DirectoryPath { get; set; }
+
+		/// <summary>
+		/// The array of filename extensions allowed, or null if all file extensions are allowed.
+		/// </summary>
+		/// <value>The allowed file types.</value>
+		public ustring [] AllowedFileTypes { get; set; }
+
+
+		/// <summary>
+		/// Gets or sets a value indicating whether this <see cref="T:Terminal.Gui.FileDialog"/> allows the file to be saved with a different extension
+		/// </summary>
+		/// <value><c>true</c> if allows other file types; otherwise, <c>false</c>.</value>
+		public bool AllowsOtherFileTypes { get; set; }
+
+		/// <summary>
+		/// The File path that is currently shown on the panel
+		/// </summary>
+		/// <value>The absolute file path for the file path entered.</value>
+		public ustring FilePath { get; set; }
+	}
+
+	public class SaveDialog : FileDialog {
+		public SaveDialog (ustring title, ustring message) : base (title, "Save", "Save as:", message)
+		{
+		}
+	}
+
+	public class OpenDialog : FileDialog {
+		public OpenDialog (ustring title, ustring message) : base (title, "Open", "Open", message)
+		{
+		}
+
+		/// <summary>
+		/// Gets or sets a value indicating whether this <see cref="T:Terminal.Gui.OpenDialog"/> can choose files.
+		/// </summary>
+		/// <value><c>true</c> if can choose files; otherwise, <c>false</c>.</value>
+		public bool CanChooseFiles { get; set; }
+
+		/// <summary>
+		/// Gets or sets a value indicating whether this <see cref="T:Terminal.Gui.OpenDialog"/> can choose directories.
+		/// </summary>
+		/// <value><c>true</c> if can choose directories; otherwise, <c>false</c>.</value>
+		public bool CanChooseDirectories { get; set; }
+
+		/// <summary>
+		/// Gets or sets a value indicating whether this <see cref="T:Terminal.Gui.OpenDialog"/> allows multiple selection.
+		/// </summary>
+		/// <value><c>true</c> if allows multiple selection; otherwise, <c>false</c>.</value>
+		public bool AllowsMultipleSelection { get; set; }
+
+		/// <summary>
+		/// Gets the file paths selected
+		/// </summary>
+		/// <value>The file paths.</value>
+		public IReadOnlyList<ustring> FilePaths { get; }
+	}
+}

Terminal.Gui/Views/ProgressBar.cs

@@ -18,7 +18,6 @@ namespace Terminal.Gui {
 	public class ProgressBar : View {
 		bool isActivity;
 		int activityPos, delta;
-		float progress;
 
 		/// <summary>
 		/// Initializes a new instance of the <see cref="T:Terminal.Gui.ProgressBar"/> class, starts in percentage mode.
@@ -27,7 +26,7 @@ namespace Terminal.Gui {
 		public ProgressBar (Rect rect) : base (rect)
 		{
 			CanFocus = false;
-			progress = 0;
+			fraction = 0;
 		}
 
 		float fraction;