From 664645986d11ec314047dcb58ea1a293d829eaca Mon Sep 17 00:00:00 2001
From: Michael <Michael@some.where>
Date: Sun, 16 Apr 2017 08:06:17 -0400
Subject: Document the Appearance Manager

Also removed obsolete/unused code.
---
 ShiftOS_TheReturn/AppearanceManager.cs | 255 ++++++++++++++++++++++++---------
 1 file changed, 187 insertions(+), 68 deletions(-)

(limited to 'ShiftOS_TheReturn')

diff --git a/ShiftOS_TheReturn/AppearanceManager.cs b/ShiftOS_TheReturn/AppearanceManager.cs
index dc88092..4c1754e 100644
--- a/ShiftOS_TheReturn/AppearanceManager.cs
+++ b/ShiftOS_TheReturn/AppearanceManager.cs
@@ -38,6 +38,9 @@ using static ShiftOS.Engine.SaveSystem;
 
 namespace ShiftOS.Engine
 {
+    /// <summary>
+    /// Provides functionality for managing windows within ShiftOS.
+    /// </summary>
     public static class AppearanceManager
     {
         [Obsolete("Please use Localization.GetAllLanguages().")]
@@ -46,38 +49,16 @@ namespace ShiftOS.Engine
             return Localization.GetAllLanguages();
         }
 
-        public static void AddFocusEvents(Control ctrl, Control child)
-        {
-            child.Enter += (o, a) =>
-            {
-                ctrl.BringToFront();
-            };
-            child.MouseDown += (o, a) =>
-            {
-                ctrl.BringToFront();
-            };
-
-            foreach (Control c in child.Controls)
-            {
-                c.Enter += (o, a) =>
-                {
-                    ctrl.BringToFront();
-                };
-                c.MouseDown += (o, a) =>
-                {
-                    ctrl.BringToFront();
-                };
-
-                try
-                {
-                    AddFocusEvents(ctrl, c);
-                }
-                catch { }
-            }
-        }
-
+        /// <summary>
+        /// Sets the title text of the specified window.
+        /// </summary>
+        /// <param name="window">The window to modify</param>
+        /// <param name="title">The title text to use</param>
+        /// <exception cref="ArgumentNullException">Thrown if the window is null.</exception>
         public static void SetWindowTitle(IShiftOSWindow window, string title)
         {
+            if (window == null)
+                throw new ArgumentNullException("window", "The window cannot be null.");
             winmgr.SetTitle(window, title);
         }
 
@@ -103,8 +84,16 @@ namespace ShiftOS.Engine
             return types;
         }
 
+        /// <summary>
+        /// Returns the default window title for a specified <see cref="IShiftOSWindow"/>-inheriting type. 
+        /// </summary>
+        /// <param name="winType">The type to scan</param>
+        /// <returns>The default title</returns>
+        /// <exception cref="ArgumentNullException">Thrown if <paramref name="winType"/> is null.</exception>
         public static string GetDefaultTitle(Type winType)
         {
+            if (winType == null)
+                throw new ArgumentNullException("winType");
             foreach(var attrib in winType.GetCustomAttributes(false))
             {
                 if(attrib is DefaultTitleAttribute)
@@ -115,78 +104,123 @@ namespace ShiftOS.Engine
             return winType.Name;
         }
 
-        public static string LastTerminalText { get; set; }
+        /// <summary>
+        /// Current cursor position of the console
+        /// </summary>
         public static int CurrentPosition { get; set; }
+
+        /// <summary>
+        /// We don't know what this does. It may be gone if it does nothing.
+        /// </summary>
         public static int LastLength { get; set; }
 
 
+        /// <summary>
+        /// Minimize a window.
+        /// </summary>
+        /// <param name="form">The window border to minimize.</param>
+        /// <exception cref="ArgumentNullException">Thrown if <paramref name="form"/> is null.</exception> 
+        /// <exception cref="EngineModuleDisabledException">Thrown if this part of the engine hasn't been enabled.</exception> 
         public static void Minimize(IWindowBorder form)
         {
+            if (form == null)
+                throw new ArgumentNullException("form");
+            if (winmgr == null)
+                throw new EngineModuleDisabledException();
             winmgr.Minimize(form);
         }
 
+        /// <summary>
+        /// Maximizes a window.
+        /// </summary>
+        /// <param name="form">The window border to maximize.</param>
+        /// <exception cref="ArgumentNullException">Thrown if <paramref name="form"/> is null.</exception> 
+        /// <exception cref="EngineModuleDisabledException">Thrown if this engine module hasn't been enabled.</exception>
         public static void Maximize(IWindowBorder form)
         {
+            if (form == null)
+                throw new ArgumentNullException("form");
+            if (winmgr == null)
+                throw new EngineModuleDisabledException();
             winmgr.Maximize(form);
         }
 
 
-        
+        /// <summary>
+        /// Provides a list of all open ShiftOS windows.
+        /// </summary>
         public static List<IWindowBorder> OpenForms = new List<IWindowBorder>();
 
-        public static bool CanOpenWindow(IShiftOSWindow form)
-        {
-#if !MUD_RAPIDDEV
-            if (ServerManager.IsSingleplayer)
-            {
-                foreach (var attr in form.GetType().GetCustomAttributes(false))
-                {
-                    if (attr is MultiplayerOnlyAttribute)
-                        return false;
-                }
-            }
-#endif
-            return true;
-        }
-
+        /// <summary>
+        /// Decorates a window with a border, then shows the window.
+        /// </summary>
+        /// <param name="form">The window to decorate and show.</param>
+        /// <exception cref="ArgumentNullException">Thrown if <paramref name="form"/> is null. </exception>
+        /// <exception cref="EngineModuleDisabledException">Thrown if this engine module has not been initiated yet.</exception> 
         public static void SetupWindow(IShiftOSWindow form)
         {
+            if (form == null)
+                throw new ArgumentNullException("form");
+            if (winmgr == null)
+                throw new EngineModuleDisabledException();
             winmgr.SetupWindow(form);
             Desktop.ResetPanelButtons();
         }
 
+        /// <summary>
+        /// Closes the specified window.
+        /// </summary>
+        /// <param name="win">The window to close.</param>
+        /// <exception cref="ArgumentNullException">Thrown if <paramref name="win"/> is null. </exception>
+        /// <exception cref="EngineModuleDisabledException">Thrown if this engine module has not been initiated yet.</exception> 
         public static void Close(IShiftOSWindow win)
         {
+            if (win == null)
+                throw new ArgumentNullException("win");
+            if (winmgr == null)
+                throw new EngineModuleDisabledException();
             winmgr.Close(win);
             Desktop.ResetPanelButtons();
         }
 
+        /// <summary>
+        /// Decorates a window with a border, then shows the window, as a dialog box.
+        /// </summary>
+        /// <param name="form">The window to decorate and show.</param>
+        /// <exception cref="ArgumentNullException">Thrown if <paramref name="form"/> is null. </exception>
+        /// <exception cref="EngineModuleDisabledException">Thrown if this engine module has not been initiated yet.</exception> 
         public static void SetupDialog(IShiftOSWindow form)
         {
+            if (form == null)
+                throw new ArgumentNullException("form");
+            if (winmgr == null)
+                throw new EngineModuleDisabledException();
             winmgr.SetupDialog(form);
             Desktop.ResetPanelButtons();
         }
 
+        /// <summary>
+        /// The underlying window manager for this engine module
+        /// </summary>
         private static WindowManager winmgr = null;
 
-        public static double Measure(this string text, Font font)
-        {
-            return Graphics.FromImage(new Bitmap(1, 1)).MeasureString(text, font).Width;
-        }
-
+        /// <summary>
+        /// Initiate this engine module, and perform mandatory configuration.
+        /// </summary>
+        /// <param name="mgr">A working, configured <see cref="WindowManager"/> to use as a backend for this module </param>
         public static void Initiate(WindowManager mgr)
         {
             winmgr = mgr;
         }
 
-        [Obsolete("This is a stub.")]
-        public static void DoWinformsSkinningMagicOnWpf(this UserControl ctrl)
-        {
-            //SetupControls(ctrl);
-        }
-
+        /// <summary>
+        /// Raised when the engine is entering its shutdown phase. Save your work!
+        /// </summary>
         public static event EmptyEventHandler OnExit;
 
+        /// <summary>
+        /// Starts the engine's exit routine, firing the OnExit event.
+        /// </summary>
         internal static void Exit()
         {
             OnExit?.Invoke();
@@ -194,61 +228,133 @@ namespace ShiftOS.Engine
             ServerManager.Disconnect();
         }
 
-
-        internal static bool BordersHidden(Form frm)
-        {
-            string t = frm.Tag as string;
-            if (t == null)
-                return false;
-
-            return t.Contains("hidden");
-        }
-
+        /// <summary>
+        /// The current terminal body control.
+        /// </summary>
         public static ITerminalWidget ConsoleOut { get; set; }
 
+        /// <summary>
+        /// Redirects the .NET <see cref="Console"/> to a new <see cref="TerminalTextWriter"/> instance.  
+        /// </summary>
         public static void StartConsoleOut()
         {
             Console.SetOut(new TerminalTextWriter());
         }
 
+        /// <summary>
+        /// Invokes an action on the window management thread.
+        /// </summary>
+        /// <param name="act">The action to invoke</param>
         public static void Invoke(Action act)
         {
             winmgr.InvokeAction(act);
         }
     }
 
+    /// <summary>
+    /// Provides the base functionality for a ShiftOS terminal.
+    /// </summary>
     public interface ITerminalWidget
     {
+        /// <summary>
+        /// Write text to this Terminal.
+        /// </summary>
+        /// <param name="text">Text to write</param>
         void Write(string text);
+        /// <summary>
+        /// Write text to this Terminal, followed by a newline.
+        /// </summary>
+        /// <param name="text">Text to write.</param>
         void WriteLine(string text);
+        /// <summary>
+        /// Clear the contents of this Terminal.
+        /// </summary>
         void Clear();
+        /// <summary>
+        /// Move the cursor to the last character in the Terminal.
+        /// </summary>
         void SelectBottom();
     }
 
+    /// <summary>
+    /// Provides the base functionality for a ShiftOS window manager.
+    /// </summary>
     public abstract class WindowManager
     {
+        /// <summary>
+        /// Minimizes a window
+        /// </summary>
+        /// <param name="border">The window border to minimize</param>
         public abstract void Minimize(IWindowBorder border);
+
+        /// <summary>
+        /// Maximizes a window
+        /// </summary>
+        /// <param name="border">The window border to maximize</param>
         public abstract void Maximize(IWindowBorder border);
 
+        /// <summary>
+        /// Closes a window
+        /// </summary>
+        /// <param name="win">The window to close</param>
         public abstract void Close(IShiftOSWindow win);
 
+        /// <summary>
+        /// Decorates a window with a window border, then shows it to the user.
+        /// </summary>
+        /// <param name="win">The window to decorate.</param>
         public abstract void SetupWindow(IShiftOSWindow win);
+
+        /// <summary>
+        /// Decorates a window with a border, then shows it to the user as a dialog box.
+        /// </summary>
+        /// <param name="win">The window to decorate</param>
         public abstract void SetupDialog(IShiftOSWindow win);
 
+        /// <summary>
+        /// Invokes an action on the window management thread.
+        /// </summary>
+        /// <param name="act">The action to invoke.</param>
         public abstract void InvokeAction(Action act);
 
+        /// <summary>
+        /// Sets the title text of a window.
+        /// </summary>
+        /// <param name="win">The window to modify.</param>
+        /// <param name="title">The new title text.</param>
         public abstract void SetTitle(IShiftOSWindow win, string title);
     }
 
+    /// <summary>
+    /// Provides the base functionality for a typical ShiftOS window border.
+    /// </summary>
     public interface IWindowBorder
     {
+        /// <summary>
+        /// Closes the border along with its window. Unload events should be invoked here.
+        /// </summary>
         void Close();
+
+        /// <summary>
+        /// Gets or sets the title text for the window border.
+        /// </summary>
         string Text { get; set; }
+
+        /// <summary>
+        /// Gets or sets the underlying <see cref="IShiftOSWindow"/> for this border. 
+        /// </summary>
         IShiftOSWindow ParentWindow { get; set; }
     }
     
+    /// <summary>
+    /// Provides a way of setting default title text for <see cref="IShiftOSWindow"/> classes. 
+    /// </summary>
     public class DefaultTitleAttribute : Attribute
     {
+        /// <summary>
+        /// Creates a new instance of the <see cref="DefaultTitleAttribute"/>. 
+        /// </summary>
+        /// <param name="title">A default title to associate with this attribute.</param>
         public DefaultTitleAttribute(string title)
         {
             Title = title;
@@ -257,4 +363,17 @@ namespace ShiftOS.Engine
         public string Title { get; private set; }
     }
 
+    /// <summary>
+    /// An exception that is thrown when mandatory configuration to run a specific method or module hasn't been done yet.
+    /// </summary>
+    public class EngineModuleDisabledException : Exception
+    {
+        /// <summary>
+        /// Initializes a new instance of the <see cref="EngineModuleDisabledException"/>. 
+        /// </summary>
+        public EngineModuleDisabledException() : base("This engine module has not yet been enabled.")
+        {
+
+        }
+    }
 }
-- 
cgit v1.2.3