document skinengine

1 files changed, 88 insertions, 2 deletions

diff --git a/ShiftOS_TheReturn/Skinning.cs b/ShiftOS_TheReturn/Skinning.cs
index c2f47fa..f5dd211 100644
--- a/ShiftOS_TheReturn/Skinning.cs
+++ b/ShiftOS_TheReturn/Skinning.cs
@@ -37,42 +37,71 @@ using System.Reflection;
 using ShiftOS.Engine.Scripting;
 namespace ShiftOS.Engine
 {
-
+    /// <summary>
+    /// Skinning API for Lua.
+    /// </summary>
     [Exposed("skinning")]
     public class SkinFunctions
     {
+        /// <summary>
+        /// Reload the current skin.
+        /// </summary>
         public void loadSkin()
         {
             SkinEngine.LoadSkin();
         }
 
+        /// <summary>
+        /// Get the current skin info.
+        /// </summary>
+        /// <returns>A proxy object containing all skin variables.</returns>
         public dynamic getSkin()
         {
             return SkinEngine.LoadedSkin;
         }
 
+        /// <summary>
+        /// Set the current skin to the specified <see cref="Skin"/> class. 
+        /// </summary>
+        /// <param name="skn">The <see cref="Skin"/> class to load.</param>
         public void setSkin(Skin skn)
         {
             Utils.WriteAllText(Paths.GetPath("skin.json"), JsonConvert.SerializeObject(skn));
             SkinEngine.LoadSkin();
         }
 
+        /// <summary>
+        /// Retrieves an image from the skin file.
+        /// </summary>
+        /// <param name="id">The skin image ID</param>
+        /// <returns>The loaded image, null (nil in Lua) if none is found.</returns>
         public dynamic getImage(string id)
         {
             return SkinEngine.GetImage(id);
         }
     }
 
-
+    /// <summary>
+    /// Skin engine management class.
+    /// </summary>
     public static class SkinEngine
     {
         private static ISkinPostProcessor processor = null;
 
+        /// <summary>
+        /// Load a new skin postprocessor into the engine.
+        /// </summary>
+        /// <param name="_processor">The postprocessor to load.</param>
         public static void SetPostProcessor(ISkinPostProcessor _processor)
         {
             processor = _processor;
         }
 
+        /// <summary>
+        /// Retrieve the user-specified image layout of a skin image.
+        /// </summary>
+        /// <param name="img">The skin image ID.</param>
+        /// <returns>The <see cref="ImageLayout"/> for the image.</returns>
         public static ImageLayout GetImageLayout(string img)
         {
             if (LoadedSkin.SkinImageLayouts.ContainsKey(img))
@@ -86,6 +115,11 @@ namespace ShiftOS.Engine
             }
         }
 
+        /// <summary>
+        /// Retrieves an image from the skin after postprocessing it.
+        /// </summary>
+        /// <param name="img">The image ID to search.</param>
+        /// <returns>The post-processed image, or null if none was found.</returns>
         public static System.Drawing.Image GetImage(string img)
         {
             var type = typeof(Skin);
@@ -111,11 +145,20 @@ namespace ShiftOS.Engine
             return null;
         }
 
+        /// <summary>
+        /// Set the engine's current icon prober.
+        /// </summary>
+        /// <param name="prober">The icon prober to use.</param>
         public static void SetIconProber(IIconProber prober)
         {
             _iconProber = prober;
         }
 
+        /// <summary>
+        /// Load a <see cref="Image"/> from a <see cref="byte"/> array.  
+        /// </summary>
+        /// <param name="image">The array to convert</param>
+        /// <returns>The resulting image.</returns>
         public static Image ImageFromBinary(byte[] image)
         {
             if (image == null)
@@ -126,6 +169,9 @@ namespace ShiftOS.Engine
 
         private static Skin loadedSkin = new Skin();
 
+        /// <summary>
+        /// Gets the currently loaded skin.
+        /// </summary>
         public static Skin LoadedSkin
         {
             get
@@ -138,6 +184,9 @@ namespace ShiftOS.Engine
             }
         }
 
+        /// <summary>
+        /// Initiates the skin engine.
+        /// </summary>
         public static void Init()
         {
             Application.ApplicationExit += (o, a) =>
@@ -160,8 +209,14 @@ namespace ShiftOS.Engine
             }
         }
 
+        /// <summary>
+        /// Occurs when the skin is loaded.
+        /// </summary>
         public static event EmptyEventHandler SkinLoaded;
 
+        /// <summary>
+        /// Reload the current skin.
+        /// </summary>
         public static void LoadSkin()
         {
             LoadedSkin = JsonConvert.DeserializeObject<Skin>(Utils.ReadAllText(Paths.GetPath("skin.json")));
@@ -170,6 +225,9 @@ namespace ShiftOS.Engine
             Desktop.PopulateAppLauncher();
         }
 
+        /// <summary>
+        /// Save the skin loaded in memory to the filesystem.
+        /// </summary>
         public static void SaveSkin()
         {
             Utils.WriteAllText(Paths.GetPath("skin.json"), JsonConvert.SerializeObject(LoadedSkin, Formatting.Indented));
@@ -177,6 +235,11 @@ namespace ShiftOS.Engine
 
         private static IIconProber _iconProber = null;
 
+        /// <summary>
+        /// Retrieves the default icon for a given icon ID.
+        /// </summary>
+        /// <param name="id">The icon ID to search.</param>
+        /// <returns>The resulting icon image.</returns>
         public static Image GetDefaultIcon(string id)
         {
             if (_iconProber == null)
@@ -213,6 +276,11 @@ namespace ShiftOS.Engine
             }
         }
 
+        /// <summary>
+        /// Retrieves the user-defined icon for a specified icon ID.
+        /// </summary>
+        /// <param name="id">The icon ID to search.</param>
+        /// <returns>The resulting icon image.</returns>
         public static Image GetIcon(string id)
         {
             if (!LoadedSkin.AppIcons.ContainsKey(id))
@@ -231,11 +299,23 @@ namespace ShiftOS.Engine
         }
     }
 
+    /// <summary>
+    /// Interface for probing app icons.
+    /// </summary>
     public interface IIconProber
     {
+        /// <summary>
+        /// Retrieve the icon image from a <see cref="DefaultIconAttribute"/>. 
+        /// </summary>
+        /// <param name="attr">The attribute data</param>
+        /// <returns>The resulting image.</returns>
         Image GetIcon(DefaultIconAttribute attr);
     }
 
+    /// <summary>
+    /// Sets the default icon ID for a <see cref="IShiftOSWindow"/>. 
+    /// </summary>
+    [AttributeUsage(AttributeTargets.Class, AllowMultiple =false)]
     public class DefaultIconAttribute : Attribute
     {
         public DefaultIconAttribute(string id)
@@ -246,6 +326,9 @@ namespace ShiftOS.Engine
         public string ID { get; private set; }
     }
 
+    /// <summary>
+    /// The data stored in any .skn file.
+    /// </summary>
     public class Skin
     {
         //borrowing from the discourse theme for the default skin
@@ -1372,6 +1455,9 @@ namespace ShiftOS.Engine
         public Font AdvALItemFont = SysFont2;
     }
 
+    /// <summary>
+    /// Marks a skin spec field as hidden from the Shifter.
+    /// </summary>
     public class ShifterHiddenAttribute : Attribute
     {