Merge pull request #1 from GimmickNG/experimental

Merged experimental branch commits into master.

src/airdock/config/ContainerConfig.as

@@ -1,7 +1,9 @@
 package airdock.config 
 {
 	/**
-	 * ...
+	 * Base configuration class for creating a container.
+	 * The width and height parameters are the minimum required parameters for creating the container; 
+	 * additional parameters can be added for extra customizability.
 	 * @author Gimmick
 	 */
 	public class ContainerConfig extends Object
@@ -25,7 +27,5 @@ package airdock.config
 		public function set height(value:Number):void {
 			num_height = value;
 		}
-
 	}
-
 }

src/airdock/config/DockConfig.as

@@ -10,7 +10,7 @@ package airdock.config
 	import flash.display.DisplayObjectContainer;
 	import flash.display.NativeWindowInitOptions;
 	/**
-	 * ...
+	 * Base configuration class for creating a Docker instance.
 	 * @author Gimmick
 	 */
 	public class DockConfig extends Object
@@ -30,107 +30,216 @@ package airdock.config
 		private var cl_defaultContainerOptions:ContainerConfig;
 		public function DockConfig() { }
 
+		/**
+		 * The main container to which the Docker instance is attached to.
+		 * This can be any container which extends DisplayObjectContainer, provided the following conditions are met:
+		 * * It is always present on the stage, either within the viewport or somewhere outside the visible stage bounds
+		 * * The nativeWindow of the container's stage is always visible, either off the user's Screen or as a transparent NativeWindow
+		 * If the above conditions are not met, then certain features, like docking windows to the user's mouse location, will cease to function correctly.
+		 */
 		public function get mainContainer():DisplayObjectContainer {
 			return dsp_mainContainer;
 		}
 
+		/**
+		 * The main container to which the Docker instance is attached to.
+		 * This can be any container which extends DisplayObjectContainer, provided the following conditions are met:
+		 * * It is always present on the stage, either within the viewport or somewhere outside the visible stage bounds
+		 * * The nativeWindow of the container's stage is always visible, either off the user's Screen or as a transparent NativeWindow
+		 * If the above conditions are not met, then certain features, like docking windows to the user's mouse location, will cease to function correctly.
+		 */
 		public function set mainContainer(value:DisplayObjectContainer):void {
 			dsp_mainContainer = value;
 		}
 
+		/**
+		 * Any instance of a dock helper.
+		 * A dock helper is a visual which appears whenever the user drags a panel, or a container, over another;
+		 * the user can then drop the panel or container onto the dock helper, which then reports back to the Docker to finish docking the panel or container.
+		 * Setting this to null prevents the user from docking panels or containers, unless another component (e.g. the container's panelList) accepts the drop.
+		 */
 		public function set dockHelper(dockHelper:IDockHelper):void {
 			cl_dockHelper = dockHelper
 		}
 
+		/**
+		 * Any instance of a dock helper.
+		 * A dock helper is a visual which appears whenever the user drags a panel, or a container, over another;
+		 * the user can then drop the panel or container onto the dock helper, which then reports back to the Docker to finish docking the panel or container.
+		 * Setting this to null prevents the user from docking panels or containers, unless another component (e.g. the container's panelList) accepts the drop.
+		 */
 		public function get dockHelper():IDockHelper {
 			return cl_dockHelper;
 		}
 
+		/**
+		 * The factory responsible for creating panelList instances for a given container.
+		 */
 		public function get panelListFactory():IPanelListFactory {
 			return cl_panelListFactory;
 		}
 
+		/**
+		 * The factory responsible for creating panelList instances for a given container.
+		 */
 		public function set panelListFactory(value:IPanelListFactory):void {
 			cl_panelListFactory = value;
 		}
 
-		public function get dragImageHeight():Number 
-		{
+		/**
+		 * The height of the thumbnail of the panel or container being dragged by the user.
+		 * A value less than or equal to 1 represents a percentage of the container / panel height; values greater than 1 are rounded down to the nearest integer, and represent absolute sizes.
+		 */
+		public function get dragImageHeight():Number {
 			return num_dragImageHeight;
 		}
 
+		/**
+		 * The height of the thumbnail of the panel or container being dragged by the user.
+		 * A value less than or equal to 1 represents a percentage of the container / panel height; values greater than 1 are rounded down to the nearest integer, and represent absolute sizes.
+		 */
 		public function set dragImageHeight(value:Number):void {
 			num_dragImageHeight = value;
 		}
 
+		/**
+		 * The width of the thumbnail of the panel or container being dragged by the user.
+		 * A value less than or equal to 1 represents a percentage of the container / panel width; values greater than 1 are rounded down to the nearest integer, and represent absolute sizes.
+		 */
 		public function get dragImageWidth():Number {
 			return num_dragImageWidth;
 		}
 
+		/**
+		 * The width of the thumbnail of the panel or container being dragged by the user.
+		 * A value less than or equal to 1 represents a percentage of the container / panel width; values greater than 1 are rounded down to the nearest integer, and represent absolute sizes.
+		 */
 		public function set dragImageWidth(value:Number):void {
 			num_dragImageWidth = value;
 		}
 
+		/**
+		 * The default options to be used when creating a NativeWindow for a given container.
+		 * Note: The resizable attribute is ignored, and the resizable attribute of the respective panel is used instead.
+		 */
 		public function get defaultWindowOptions():NativeWindowInitOptions {
 			return cl_defaultWindowOptions;
 		}
 
+		/**
+		 * The default options to be used when creating a NativeWindow for a given container.
+		 * Note: The resizable attribute is ignored, and the resizable attribute of the respective panel is used instead.
+		 */
 		public function set defaultWindowOptions(value:NativeWindowInitOptions):void {
 			cl_defaultWindowOptions = value;
 		}
 
+		/**
+		 * The factory used to create panels as requested through the createPanel() method of the Docker instance.
+		 */
 		public function get panelFactory():IPanelFactory {
 			return cl_panelFactory;
 		}
 
+		/**
+		 * The factory used to create panels as requested through the createPanel() method of the Docker instance.
+		 */
 		public function set panelFactory(value:IPanelFactory):void {
 			cl_panelFactory = value;
 		}
 
+		/**
+		 * The factory used to create container as requested through the createContainer() method of the Docker instance.
+		 * By default, containers created this way are regarded as "root" containers - that is, until they are added directly to another container (and not merged)
+		 */
 		public function get containerFactory():IContainerFactory {
 			return cl_containerFactory;
 		}
 
+		/**
+		 * The factory used to create container as requested through the createContainer() method of the Docker instance.
+		 * By default, containers created this way are regarded as "root" containers - that is, until they are added directly to another container (and not merged)
+		 */
 		public function set containerFactory(value:IContainerFactory):void {
 			cl_containerFactory = value;
 		}
 
+		/**
+		 * The default container options used when automatically creating the parked containers for a panel's NativeWindow.
+		 * This is separate from the ContainerConfig instance supplied in the createContainer() method of the Docker instance.
+		 */
 		public function get defaultContainerOptions():ContainerConfig {
 			return cl_defaultContainerOptions;
 		}
 
+		/**
+		 * The default container options used when automatically creating the parked containers for a panel's NativeWindow.
+		 * This is separate from the ContainerConfig instance supplied in the createContainer() method of the Docker instance.
+		 */
 		public function set defaultContainerOptions(value:ContainerConfig):void {
 			cl_defaultContainerOptions = value;
 		}
 
+		/**
+		 * The resize helper instance. This is used to let the user resize containers, when they activate this - usually by hovering at the border of two containers.
+		 * Setting this to null prevents the user from resizing panels, and can hence be used to enforce strict panel sizes for a given Docker instance.
+		 */
 		public function get resizeHelper():IResizer {
 			return cl_resizeHelper;
 		}
 
+		/**
+		 * The resize helper instance. This is used to let the user resize containers, when they activate this - usually by hovering at the border of two containers.
+		 * Setting this to null prevents the user from resizing panels, and can hence be used to enforce strict panel sizes for a given Docker instance.
+		 */
 		public function set resizeHelper(value:IResizer):void {
 			cl_resizeHelper = value;
 		}
 
+		/**
+		 * The default dock format string key used to indicate panel and container clipboard data.
+		 * Useful when intercepting drag events and capturing the panel and/or container instances.
+		 */
 		public function get dockFormat():IDockFormat {
 			return cl_dockFormat;
 		}
 
+		/**
+		 * The default dock format string key used to indicate panel and container clipboard data.
+		 * Useful when intercepting drag events and capturing the panel and/or container instances.
+		 */
 		public function set dockFormat(value:IDockFormat):void {
 			cl_dockFormat = value;
 		}
 
+		/**
+		 * The default tree resolver for this Docker.
+		 * Used to retrieve the relationships between different containers and their children, which are including, but not limited to, panels.
+		 */
 		public function get treeResolver():ITreeResolver {
 			return cl_treeResolver;
 		}
 
+		/**
+		 * The default tree resolver for this Docker.
+		 * Used to retrieve the relationships between different containers and their children, which are including, but not limited to, panels.
+		 */
 		public function set treeResolver(value:ITreeResolver):void {
 			cl_treeResolver = value;
 		}
 
+		/**
+		 * The cross docking policy for this Docker instance; acceptable values are enumerated in the CrossDockingPolicy class.
+		 * Change this value to achieve finer control over which containers are allowed out or in, from or to this Docker instance.
+		 */
 		public function get crossDockingPolicy():int {
 			return i_crossDockingPolicy;
 		}
 
+		/**
+		 * The cross docking policy for this Docker instance; acceptable values are enumerated in the CrossDockingPolicy class.
+		 * Change this value to achieve finer control over which containers are allowed out or in, from or to this Docker instance.
+		 */
 		public function set crossDockingPolicy(value:int):void {
 			i_crossDockingPolicy = value;
 		}

src/airdock/config/PanelConfig.as

@@ -1,7 +1,8 @@
 package airdock.config 
 {
 	/**
-	 * ...
+	 * Base configuration class for creating a panel. 
+	 * Extra attributes can be added for customizability, subject to the instance of the PanelFactory used by the Docker.
 	 * @author Gimmick
 	 */
 	public class PanelConfig extends Object
@@ -10,41 +11,87 @@ package airdock.config
 		private var num_width:Number;
 		private var num_height:Number;
 		private var b_resizable:Boolean;
-		public function PanelConfig() { }
+		private var b_dockable:Boolean;
+		/**
+		 * Creates a new panel configuration instance.
+		 * By default, panels are resizable and dockable unless explicitly set otherwise.
+		 */
+		public function PanelConfig() {
+			b_resizable = b_dockable = true;
+		}
 
+		/**
+		 * The default background color of the panel, when it is created.
+		 */
 		public function get color():uint {
 			return u_color;
 		}
 
+		/**
+		 * The default background color of the panel, when it is created.
+		 */
 		public function set color(value:uint):void {
 			u_color = value;
 		}
 
+		/**
+		 * The default width of the panel, when it is created.
+		 */
 		public function get width():Number {
 			return num_width;
 		}
 
+		/**
+		 * The default width of the panel, when it is created.
+		 */
 		public function set width(value:Number):void {
 			num_width = value;
 		}
 
+		/**
+		 * The default height of the panel, when it is created.
+		 */
 		public function get height():Number {
 			return num_height;
 		}
 
+		/**
+		 * The default height of the panel, when it is created.
+		 */
 		public function set height(value:Number):void {
 			num_height = value;
 		}
 
+		/**
+		 * This attribute determines whether the panel is intended to be resizable, or not.
+		 * However, it is up to the container whether to respect this attribute or to override it.
+		 */
 		public function get resizable():Boolean {
 			return b_resizable;
 		}
 
-		public function set resizable(value:Boolean):void 
-		{
+		/**
+		 * This attribute determines whether the panel is intended to be resizable, or not.
+		 * However, it is up to the container whether to respect this attribute or to override it.
+		 */
+		public function set resizable(value:Boolean):void {
 			b_resizable = value;
 		}
+		/**
+		 * A Boolean indicating whether the panel is dockable or not.
+		 * Non-dockable panels cannot be removed from the root container which they are a part of, by the user.
+		 */
+		public function set dockable(value:Boolean):void {
+			b_dockable = value;
+		}
 
+		/**
+		 * A Boolean indicating whether the panel is dockable or not.
+		 * Non-dockable panels cannot be removed from the root container which they are a part of, by the user.
+		 */
+		public function get dockable():Boolean {
+			return b_dockable;
+		}
 	}
 
 }