From e2ae0c030aba3e49f905b9bc64b1391aabed3f35 Mon Sep 17 00:00:00 2001 From: Miguel de Icaza Date: Sat, 17 Feb 2018 23:18:44 -0500 Subject: [PATCH] Docs, plus some bones --- Terminal.Gui/Core.cs | 52 ++++++++++--- Terminal.Gui/Driver.cs | 23 +++++- Terminal.Gui/Views/Button.cs | 8 +- Terminal.Gui/Views/Dialog.cs | 2 +- Terminal.Gui/Views/FileDialog.cs | 125 ++++++++++++++++++++++++++++++ Terminal.Gui/Views/ProgressBar.cs | 3 +- 6 files changed, 191 insertions(+), 22 deletions(-) create mode 100644 Terminal.Gui/Views/FileDialog.cs diff --git a/Terminal.Gui/Core.cs b/Terminal.Gui/Core.cs index 0820a5d32..688848d5e 100644 --- a/Terminal.Gui/Core.cs +++ b/Terminal.Gui/Core.cs @@ -1289,9 +1289,9 @@ namespace Terminal.Gui { /// /// Releases all resource used by the object. /// - /// Call when you are finished using the . The - /// method leaves the in an unusable state. After - /// calling , you must release all references to the + /// Call when you are finished using the . The + /// method leaves the in an unusable state. After + /// calling , you must release all references to the /// so the garbage collector can reclaim the memory that the /// was occupying. public void Dispose () @@ -1305,7 +1305,7 @@ namespace Terminal.Gui { /// /// The dispose. /// If set to true disposing. - 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 { } } + /// + /// Building block API: Prepares the provided toplevel for execution. + /// + /// The runstate handle that needs to be passed to the End() method upon completion. + /// Toplevel to prepare execution for. + /// + /// 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 method, and then the method upon termination which will + /// undo these changes. + /// static public RunState Begin (Toplevel toplevel) { if (toplevel == null) @@ -1436,12 +1449,16 @@ namespace Terminal.Gui { return rs; } - static public void End (RunState rs) + /// + /// Building block API: completes the exection of a Toplevel that was started with Begin. + /// + /// The runstate returned by the method. + 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 { /// 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 { } /// - /// Runs the main loop for the created dialog + /// Building block API: Runs the main loop for the created dialog /// /// /// Use the wait parameter to control whether this is a - /// blocking or non-blocking call. + /// blocking or non-blocking call. /// + /// The state returned by the Begin method. + /// 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. 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. /// + /// + /// 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. + /// + /// + /// 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. + /// /// public static void Run (Toplevel view) { diff --git a/Terminal.Gui/Driver.cs b/Terminal.Gui/Driver.cs index b321d5610..77d92a7fd 100644 --- a/Terminal.Gui/Driver.cs +++ b/Terminal.Gui/Driver.cs @@ -268,7 +268,16 @@ namespace Terminal.Gui { /// Ends the execution of the console driver. /// public abstract void End (); - public abstract void RedrawTop (); + + /// + /// Redraws the physical screen with the contents that have been queued up via any of the printing commands. + /// + public abstract void UpdateScreen (); + + /// + /// Selects the specified attribute as the attribute to use for future calls to AddRune, AddString. + /// + /// C. public abstract void SetAttribute (Attribute c); // Set Colors from limit sets of colors @@ -284,6 +293,12 @@ namespace Terminal.Gui { /// Background color identifier. public abstract void SetColors (short foregroundColorId, short backgroundColorId); + /// + /// Draws a frame on the specified region with the specified padding around the frame. + /// + /// Region where the frame will be drawn.. + /// Padding to add on the sides. + /// If set to true it will clear the contents with the current color, otherwise the contents will be left untouched. 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; diff --git a/Terminal.Gui/Views/Button.cs b/Terminal.Gui/Views/Button.cs index eaa8a1af1..75394d309 100644 --- a/Terminal.Gui/Views/Button.cs +++ b/Terminal.Gui/Views/Button.cs @@ -62,7 +62,7 @@ namespace Terminal.Gui { /// text length. This button is not a default button. /// /// The button's text - public Button (string text) : this (0, 0, text) { } + public Button (ustring text) : this (0, 0, text) { } /// /// Public constructor, creates a button based on @@ -75,7 +75,7 @@ namespace Terminal.Gui { /// /// The button's text /// 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 - 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) { } /// /// Public constructor, creates a button based on @@ -88,7 +88,7 @@ namespace Terminal.Gui { /// X position where the button will be shown. /// Y position where the button will be shown. /// The button's text - 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) { } /// /// The text displayed by this widget. @@ -138,7 +138,7 @@ namespace Terminal.Gui { /// Y position where the button will be shown. /// The button's text /// 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 - 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; diff --git a/Terminal.Gui/Views/Dialog.cs b/Terminal.Gui/Views/Dialog.cs index 26e376f61..d74106c55 100644 --- a/Terminal.Gui/Views/Dialog.cs +++ b/Terminal.Gui/Views/Dialog.cs @@ -25,7 +25,7 @@ namespace Terminal.Gui { /// Width for the dialog. /// Height for the dialog. /// Optional buttons to lay out at the bottom of the dialog. - 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; diff --git a/Terminal.Gui/Views/FileDialog.cs b/Terminal.Gui/Views/FileDialog.cs new file mode 100644 index 000000000..c275fe738 --- /dev/null +++ b/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); + } + + /// + /// Gets or sets the prompt label for the button displayed to the user + /// + /// The prompt. + public ustring Prompt { + get => prompt.Text; + set { + prompt.Text = value; + } + } + + /// + /// Gets or sets the name field label. + /// + /// The name field label. + public ustring NameFieldLabel { + get => nameFieldLabel.Text; + set { + nameFieldLabel.Text = value; + } + } + + /// + /// Gets or sets the message displayed to the user, defaults to nothing + /// + /// The message. + public ustring Message { get; set; } + + + /// + /// Gets or sets a value indicating whether this can create directories. + /// + /// true if can create directories; otherwise, false. + public bool CanCreateDirectories { get; set; } + + /// + /// Gets or sets a value indicating whether this is extension hidden. + /// + /// true if is extension hidden; otherwise, false. + public bool IsExtensionHidden { get; set; } + + /// + /// Gets or sets the directory path for this panel + /// + /// The directory path. + public ustring DirectoryPath { get; set; } + + /// + /// The array of filename extensions allowed, or null if all file extensions are allowed. + /// + /// The allowed file types. + public ustring [] AllowedFileTypes { get; set; } + + + /// + /// Gets or sets a value indicating whether this allows the file to be saved with a different extension + /// + /// true if allows other file types; otherwise, false. + public bool AllowsOtherFileTypes { get; set; } + + /// + /// The File path that is currently shown on the panel + /// + /// The absolute file path for the file path entered. + 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) + { + } + + /// + /// Gets or sets a value indicating whether this can choose files. + /// + /// true if can choose files; otherwise, false. + public bool CanChooseFiles { get; set; } + + /// + /// Gets or sets a value indicating whether this can choose directories. + /// + /// true if can choose directories; otherwise, false. + public bool CanChooseDirectories { get; set; } + + /// + /// Gets or sets a value indicating whether this allows multiple selection. + /// + /// true if allows multiple selection; otherwise, false. + public bool AllowsMultipleSelection { get; set; } + + /// + /// Gets the file paths selected + /// + /// The file paths. + public IReadOnlyList FilePaths { get; } + } +} diff --git a/Terminal.Gui/Views/ProgressBar.cs b/Terminal.Gui/Views/ProgressBar.cs index b3335dfbc..6de6f29bf 100644 --- a/Terminal.Gui/Views/ProgressBar.cs +++ b/Terminal.Gui/Views/ProgressBar.cs @@ -18,7 +18,6 @@ namespace Terminal.Gui { public class ProgressBar : View { bool isActivity; int activityPos, delta; - float progress; /// /// Initializes a new instance of the 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;