diff --git a/MBS.Framework/Application.cs b/MBS.Framework/Application.cs index 1005868..f7ff8cf 100644 --- a/MBS.Framework/Application.cs +++ b/MBS.Framework/Application.cs @@ -20,11 +20,17 @@ // along with this program. If not, see . using System; using System.Collections.Generic; +using System.Text; namespace MBS.Framework { public class Application { + /// + /// Implements a which notifies + /// the containing of context addition and + /// removal. + /// public class ApplicationContextCollection : Context.ContextCollection { @@ -48,12 +54,29 @@ namespace MBS.Framework } } + /// + /// Gets or sets the currently-running + /// instance. + /// + /// + /// The currently-running instance. + /// public static Application Instance { get; set; } = null; protected virtual Command FindCommandInternal(string commandID) { return null; } + /// + /// Finds the command with the given , + /// searching across application-global commands as well as commands + /// defined in the currently-loaded s. + /// + /// + /// The command with the given , or + /// if the command was not found. + /// + /// Command identifier. public Command FindCommand(string commandID) { Command cmd = Commands[commandID]; @@ -131,7 +154,7 @@ namespace MBS.Framework { return new string[] { - // first look in the application root directory since this will be overridden by everything else + // first look in the application root directory since this will override everything else BasePath, // then look in /usr/share/universal-editor or C:\ProgramData\Mike Becker's Software\Universal Editor String.Join(System.IO.Path.DirectorySeparatorChar.ToString(), new string[] @@ -173,6 +196,13 @@ namespace MBS.Framework private Dictionary> _CommandEventHandlers = new Dictionary>(); public Command.CommandCollection Commands { get; } = new Command.CommandCollection(); + + /// + /// Attachs the specified to handle the with the given . + /// + /// true, if the command was found, false otherwise. + /// Command identifier. + /// Handler. public bool AttachCommandEventHandler(string commandID, EventHandler handler) { Command cmd = Commands[commandID]; @@ -195,6 +225,11 @@ namespace MBS.Framework return false; } + /// + /// Executes the command with the given . + /// + /// Identifier. + /// Named parameters. public void ExecuteCommand(string id, KeyValuePair[] namedParameters = null) { Command cmd = Commands[id]; @@ -260,25 +295,53 @@ namespace MBS.Framework // CONTEXTS /// - /// Gets a collection of objects representing system, application, user, and custom contexts for settings and other items. + /// Gets a collection of objects representing + /// system, application, user, and custom contexts for settings and other + /// items. /// - /// A collection of objects representing cpublic for settings and other items. + /// + /// A collection of objects representing system, + /// application, user, and custom contexts for settings and other items. + /// public ApplicationContextCollection Contexts { get; } = new ApplicationContextCollection(); + /// + /// The event raised when a is added to the + /// . + /// public ContextChangedEventHandler ContextAdded; + /// + /// Called when a is added to the + /// . The default behavior is to simply fire + /// the event. Implementations should handle + /// adding context-specific behaviors and UI elements in this method. + /// + /// Event arguments. protected virtual void OnContextAdded(ContextChangedEventArgs e) { ContextAdded?.Invoke(this, e); } + /// + /// The event raised when a is removed from the + /// . + /// public ContextChangedEventHandler ContextRemoved; + /// + /// Called when a is removed from the + /// . The default behavior is to simply fire + /// the event. Implementations should handle + /// removing context-specific behaviors and UI elements in this method. + /// + /// Event arguments. protected virtual void OnContextRemoved(ContextChangedEventArgs e) { ContextRemoved?.Invoke(this, e); } /// - /// Handles updating the menus, toolbars, keyboard shortcuts, and other UI elements associated with the application . + /// Handles updating the menus, toolbars, keyboard shortcuts, and other + /// UI elements associated with the application . /// private void AddContext(Context ctx) { @@ -286,34 +349,55 @@ namespace MBS.Framework } /// - /// Handles updating the menus, toolbars, keyboard shortcuts, and other UI elements associated with the application . + /// Handles updating the menus, toolbars, keyboard shortcuts, and other + /// UI elements associated with the application . /// private void RemoveContext(Context ctx) { OnContextRemoved(new ContextChangedEventArgs(ctx)); } - // LOGGING + /// + /// Log the specified message. + /// + /// Message. public void Log(string message) { Log(null, 0, message); } + /// + /// Log the specified message, including information about the relevant + /// object instance or static class , line number of + /// the corresponding source code. + /// + /// Object. + /// Line number. + /// Message. public void Log(object obj, int lineNumber, string message) { - if (obj is Type) + Type type = (obj is Type ? ((Type)obj) : (obj != null ? obj.GetType() : null)); + StringBuilder sb = new StringBuilder(); + if (type != null) { - Console.WriteLine("{0}: {1}", ((Type)obj).FullName, message); - } - else if (obj != null) - { - Console.WriteLine("{0}: {1}", obj.GetType().FullName, message); - } - else - { - Console.WriteLine("{0}", message); + sb.Append('['); + sb.Append(type.Assembly.GetName().Name); + sb.Append("] "); + sb.Append(type.FullName); + sb.Append('('); + sb.Append(lineNumber); + sb.Append(')'); + sb.Append(": "); } + sb.Append(message); + + System.Diagnostics.Debug.WriteLine(sb); } + /// + /// Gets a value indicating whether this is + /// currently in the process of shutting down. + /// + /// true if stopping; otherwise, false. public bool Stopping { get; private set; } = false; protected virtual void OnStopping(System.ComponentModel.CancelEventArgs e) @@ -325,7 +409,16 @@ namespace MBS.Framework } + /// + /// The event raised when the method is called, before + /// the application is stopped. + /// public event System.ComponentModel.CancelEventHandler BeforeShutdown; + /// + /// Event handler for event. Called when the + /// method is called, before the application is stopped. + /// + /// Event arguments. protected virtual void OnBeforeShutdown(System.ComponentModel.CancelEventArgs e) { BeforeShutdown?.Invoke(this, e); @@ -344,9 +437,28 @@ namespace MBS.Framework Start(); } + /// + /// Informs the underlying system backend that it is to begin the process + /// of application shutdown, gracefully ending the main loop before + /// returning the specified to the operating + /// system. + /// + /// + /// The exit code to return to the operating system. + /// protected virtual void StopInternal(int exitCode) { } + + /// + /// Shuts down the application gracefully, calling any event handlers + /// attached to the shutdown event to give listeners the opportunity to + /// cancel the shutdown and passing the specified + /// to the operating system. + /// + /// + /// The exit code to return to the operating system. + /// public void Stop(int exitCode = 0) { if (Stopping) diff --git a/MBS.Framework/Command.cs b/MBS.Framework/Command.cs index 03aafbb..cfa3ae5 100644 --- a/MBS.Framework/Command.cs +++ b/MBS.Framework/Command.cs @@ -92,6 +92,7 @@ namespace MBS.Framework /// /// Executes this . /// + [Obsolete("Please use Application.ExecuteCommand. Command.Execute does not always work and will be removed in a future release.")] public void Execute() { if (Executed != null) Executed(this, EventArgs.Empty); diff --git a/MBS.Framework/StockType.cs b/MBS.Framework/StockType.cs index 7b24823..0e6af95 100644 --- a/MBS.Framework/StockType.cs +++ b/MBS.Framework/StockType.cs @@ -16,6 +16,7 @@ namespace MBS.Framework ArrowUp, Bold, + Bookmarks, Cancel, CapsLockWarning, // not for buttons CDROM,