From c0614c4f218d9ad071e8af3a2cad46d254a33b53 Mon Sep 17 00:00:00 2001
From: Michael <Michael@some.where>
Date: Sat, 20 May 2017 09:00:52 -0400
Subject: [PATCH] document skinengine
---
ShiftOS_TheReturn/Skinning.cs | 90 ++++++++++++++++++++++++++++++++++-
1 file 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
{