Document the Appearance Manager

Also removed obsolete/unused code.

5 files changed, 187 insertions, 185 deletions

diff --git a/ShiftOS.Updater.exe/App.config b/ShiftOS.Updater.exe/App.config
deleted file mode 100644
index 88fa402..0000000
--- a/ShiftOS.Updater.exe/App.config
+++ /dev/null
@@ -1,6 +0,0 @@
-<?xml version="1.0" encoding="utf-8" ?>
-<configuration>
-    <startup> 
-        <supportedRuntime version="v4.0" sku=".NETFramework,Version=v4.5.2" />
-    </startup>
-</configuration>
\ No newline at end of file
diff --git a/ShiftOS.Updater.exe/Program.cs b/ShiftOS.Updater.exe/Program.cs
deleted file mode 100644
index aa87901..0000000
--- a/ShiftOS.Updater.exe/Program.cs
+++ /dev/null
@@ -1,15 +0,0 @@
-using System;
-using System.Collections.Generic;
-using System.Linq;
-using System.Text;
-using System.Threading.Tasks;
-
-namespace ShiftOS.Updater.exe
-{
-    class Program
-    {
-        static void Main(string[] args)
-        {
-        }
-    }
-}
diff --git a/ShiftOS.Updater.exe/Properties/AssemblyInfo.cs b/ShiftOS.Updater.exe/Properties/AssemblyInfo.cs
deleted file mode 100644
index 69ba9c9..0000000
--- a/ShiftOS.Updater.exe/Properties/AssemblyInfo.cs
+++ /dev/null
@@ -1,36 +0,0 @@
-using System.Reflection;
-using System.Runtime.CompilerServices;
-using System.Runtime.InteropServices;
-
-// General Information about an assembly is controlled through the following 
-// set of attributes. Change these attribute values to modify the information
-// associated with an assembly.
-[assembly: AssemblyTitle("ShiftOS.Updater.exe")]
-[assembly: AssemblyDescription("")]
-[assembly: AssemblyConfiguration("")]
-[assembly: AssemblyCompany("")]
-[assembly: AssemblyProduct("ShiftOS.Updater.exe")]
-[assembly: AssemblyCopyright("Copyright ©  2017")]
-[assembly: AssemblyTrademark("")]
-[assembly: AssemblyCulture("")]
-
-// Setting ComVisible to false makes the types in this assembly not visible 
-// to COM components.  If you need to access a type in this assembly from 
-// COM, set the ComVisible attribute to true on that type.
-[assembly: ComVisible(false)]
-
-// The following GUID is for the ID of the typelib if this project is exposed to COM
-[assembly: Guid("8031adf5-caf0-4210-bec0-964a9db130a9")]
-
-// Version information for an assembly consists of the following four values:
-//
-//      Major Version
-//      Minor Version 
-//      Build Number
-//      Revision
-//
-// You can specify all the values or you can default the Build and Revision Numbers 
-// by using the '*' as shown below:
-// [assembly: AssemblyVersion("1.0.*")]
-[assembly: AssemblyVersion("1.0.0.0")]
-[assembly: AssemblyFileVersion("1.0.0.0")]
diff --git a/ShiftOS.Updater.exe/ShiftOS.Updater.exe.csproj b/ShiftOS.Updater.exe/ShiftOS.Updater.exe.csproj
deleted file mode 100644
index 6142844..0000000
--- a/ShiftOS.Updater.exe/ShiftOS.Updater.exe.csproj
+++ /dev/null
@@ -1,60 +0,0 @@
-<?xml version="1.0" encoding="utf-8"?>
-<Project ToolsVersion="14.0" DefaultTargets="Build" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
-  <Import Project="$(MSBuildExtensionsPath)\$(MSBuildToolsVersion)\Microsoft.Common.props" Condition="Exists('$(MSBuildExtensionsPath)\$(MSBuildToolsVersion)\Microsoft.Common.props')" />
-  <PropertyGroup>
-    <Configuration Condition=" '$(Configuration)' == '' ">Debug</Configuration>
-    <Platform Condition=" '$(Platform)' == '' ">AnyCPU</Platform>
-    <ProjectGuid>{8031ADF5-CAF0-4210-BEC0-964A9DB130A9}</ProjectGuid>
-    <OutputType>Exe</OutputType>
-    <AppDesignerFolder>Properties</AppDesignerFolder>
-    <RootNamespace>ShiftOS.Updater.exe</RootNamespace>
-    <AssemblyName>ShiftOS.Updater.exe</AssemblyName>
-    <TargetFrameworkVersion>v4.5.2</TargetFrameworkVersion>
-    <FileAlignment>512</FileAlignment>
-    <AutoGenerateBindingRedirects>true</AutoGenerateBindingRedirects>
-  </PropertyGroup>
-  <PropertyGroup Condition=" '$(Configuration)|$(Platform)' == 'Debug|AnyCPU' ">
-    <PlatformTarget>AnyCPU</PlatformTarget>
-    <DebugSymbols>true</DebugSymbols>
-    <DebugType>full</DebugType>
-    <Optimize>false</Optimize>
-    <OutputPath>bin\Debug\</OutputPath>
-    <DefineConstants>DEBUG;TRACE</DefineConstants>
-    <ErrorReport>prompt</ErrorReport>
-    <WarningLevel>4</WarningLevel>
-  </PropertyGroup>
-  <PropertyGroup Condition=" '$(Configuration)|$(Platform)' == 'Release|AnyCPU' ">
-    <PlatformTarget>AnyCPU</PlatformTarget>
-    <DebugType>pdbonly</DebugType>
-    <Optimize>true</Optimize>
-    <OutputPath>bin\Release\</OutputPath>
-    <DefineConstants>TRACE</DefineConstants>
-    <ErrorReport>prompt</ErrorReport>
-    <WarningLevel>4</WarningLevel>
-  </PropertyGroup>
-  <ItemGroup>
-    <Reference Include="System" />
-    <Reference Include="System.Core" />
-    <Reference Include="System.Xml.Linq" />
-    <Reference Include="System.Data.DataSetExtensions" />
-    <Reference Include="Microsoft.CSharp" />
-    <Reference Include="System.Data" />
-    <Reference Include="System.Net.Http" />
-    <Reference Include="System.Xml" />
-  </ItemGroup>
-  <ItemGroup>
-    <Compile Include="Program.cs" />
-    <Compile Include="Properties\AssemblyInfo.cs" />
-  </ItemGroup>
-  <ItemGroup>
-    <None Include="App.config" />
-  </ItemGroup>
-  <Import Project="$(MSBuildToolsPath)\Microsoft.CSharp.targets" />
-  <!-- To modify your build process, add your task inside one of the targets below and uncomment it. 
-       Other similar extension points exist, see Microsoft.Common.targets.
-  <Target Name="BeforeBuild">
-  </Target>
-  <Target Name="AfterBuild">
-  </Target>
-  -->
-</Project>
\ No newline at end of file
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.")
+        {
+
+        }
+    }
 }