From 5c2180f2edcdf6a38416af868ffd764fb9b84ecd Mon Sep 17 00:00:00 2001 From: Jeremy Penner Date: Wed, 2 Feb 2011 09:14:07 -0800 Subject: [PATCH] some helpful comments / documentation --- src/Button.as | 2 +- src/Drag.as | 3 ++- src/EntitySidebar.as | 1 - src/FileWatcher.as | 3 ++- src/Imgdir.as | 3 ++- src/Sidebar.as | 4 ++- src/WorldStage.as | 62 ++++++++++++++++++++++++++++++++++---------- 7 files changed, 58 insertions(+), 20 deletions(-) diff --git a/src/Button.as b/src/Button.as index a4dc041..93c1ac0 100644 --- a/src/Button.as +++ b/src/Button.as @@ -1,7 +1,7 @@ package { /** - * ... + * Button widget; when clicked, calls a function. * @author jjp */ public class Button extends EntitySidebarImg diff --git a/src/Drag.as b/src/Drag.as index 28b2dc6..92f6ac4 100644 --- a/src/Drag.as +++ b/src/Drag.as @@ -3,7 +3,8 @@ package import flash.geom.Point; import net.flashpunk.utils.Input; /** - * ... + * Keeps track of mouse dragging. Has a global scheme that ensures only one thing is being dragged at a time. + * Use Drag.Claim instead of new Drag(). * @author jjp */ public class Drag diff --git a/src/EntitySidebar.as b/src/EntitySidebar.as index 6b5dfc6..b6d5264 100644 --- a/src/EntitySidebar.as +++ b/src/EntitySidebar.as @@ -28,5 +28,4 @@ package public function OnClick(): void { } public function Fade(pct:Number):void { } } - } \ No newline at end of file diff --git a/src/FileWatcher.as b/src/FileWatcher.as index 8cb2604..0f74f65 100644 --- a/src/FileWatcher.as +++ b/src/FileWatcher.as @@ -5,7 +5,8 @@ package import flash.events.EventDispatcher; import flash.filesystem.File; /** - * ... + * Watches an image file for changes, reloads it if it sees any. Uses a global reference-counting scheme to keep track of + * which objects care about a particular file. Use "FileWatcher.Get", not "new Filewatcher". * @author jjp */ public class FileWatcher diff --git a/src/Imgdir.as b/src/Imgdir.as index 26c1e93..da332cb 100644 --- a/src/Imgdir.as +++ b/src/Imgdir.as @@ -11,7 +11,8 @@ package import flash.filesystem.File; import flash.net.URLRequest; /** - * ... + * Monitors a directory for new image files placed in it, and sends out AS3 events containing their BitmapData when it finds some. + * Also contians a static helper function for asynchronously loading image files. * @author jjp */ public class Imgdir extends EventDispatcher diff --git a/src/Sidebar.as b/src/Sidebar.as index 3052b64..1ce87cb 100644 --- a/src/Sidebar.as +++ b/src/Sidebar.as @@ -11,7 +11,9 @@ package import net.flashpunk.utils.Ease; /** - * ... + * A sidebar contains a vertically-stacked list of EntitySidebars, can be shuffled on and off the screen, and can optionally be scrolled. + * A sidebar claims two layers; the layer passed in to the sidebar constructor is where the EntitySidebars live, and layer + 1 is where + * the sidebar entity lives. NO OTHER ENTITIES SHOULD BE ON THESE LAYERS. * @author jjp */ public class Sidebar extends Entity diff --git a/src/WorldStage.as b/src/WorldStage.as index 2c2c934..a425cbc 100644 --- a/src/WorldStage.as +++ b/src/WorldStage.as @@ -16,6 +16,13 @@ // bar/baz/ -- urfd // bar/ -- urpd +// seriously I promise after fifteen minutes of working with this nomenclature it becomes second nature. + +// dg -- function pointer +// rg -- list +// mpfoo_bar -- a dictionary with foos for keys and bars for values +// bmp -- a FlashPunk "source" like BitmapData or a Class of an embedded image + package { import flash.display.BitmapData; @@ -110,15 +117,8 @@ package { return new Point((pointReal.x - pointView.x) * zoom, (pointReal.y - pointView.y) * zoom); } - private function OnNewImg(ev: EvNewImg) : void - { - var entity: Entity; - if (ev.bmp === null) - entity = new Folder(SidebarFind(LAYER_SIDEBAR), ev.urp); - else - entity = new Factory(SidebarFind(LAYER_SIDEBAR), ev.urp, ev.bmp); - } - + + // path management helpers public function UabFromUrf(urf:String): String { return uabd + urf; @@ -131,6 +131,8 @@ package { return rgurpd.join("") + "/"; } + + // left sidebar (folders and objects) management public function Chdir(urpd: String): void { if (alarmImgdir !== null) @@ -160,6 +162,16 @@ package if (rgurpd.length > 0) OnNewImg(new EvNewImg(Imgdir.LOADED, "../", null)); } + private function OnNewImg(ev: EvNewImg) : void + { + var entity: Entity; + if (ev.bmp === null) + entity = new Folder(SidebarFind(LAYER_SIDEBAR), ev.urp); + else + entity = new Factory(SidebarFind(LAYER_SIDEBAR), ev.urp, ev.bmp); + } + + // sidebar management private function SidebarFind(layer: int):Sidebar { for each (var sidebar:Sidebar in rgsidebar) @@ -179,6 +191,7 @@ package return true; }, this); } + // add a sidebar to the world, replacing an existing sidebar on the same layer (if any). private function AddSidebar(sidebar: Sidebar):Sidebar { RemoveSidebar(sidebar.LayerEntities()); @@ -191,9 +204,22 @@ package for each (var sidebar: Sidebar in rgsidebar) sidebar.Toggle(); } + + // top-level UI policy (token selection, sidebar clicking & scrolling, stage zooming & dragging, UI hiding & showing) + + // yes this is messy but at our current level of UI complexity it should be clear how all of the policies interact + // it would be "better" in some abstract sense if the world simply dispatched events to widget objects, but that's + // not how FlashPunk works so that's not how we do it either + + // leave this function cleaner than you found it + + // if it turns out we need more than one of a particular kind of widget please create a class and design a protocol for handing + // off control to that thing from this (like tokSelected) + + // I've passed the stage in my programming career where I would happily spend a few months designing a generic GUI library in + // response to this problem and consequently forget about my original goal; there are a few other projects doing that for me override public function update():void { - var dyFactory:int = 0; if (Input.mouseUp && dragView !== null) { trace("drag done"); @@ -203,9 +229,9 @@ package if (Input.mousePressed) { - if (Input.check(Key.SHIFT)) + if (Input.check(Key.SHIFT)) // shift-click -- begin view dragging dragView = Drag.Claim(); - else + else // click -- select a token { var rgtok: Array = []; getLayer(LAYER_TOKENS, rgtok); @@ -223,15 +249,18 @@ package trace("clicked on " + tokSelected); } } - if (dragView !== null) + if (dragView !== null) // shift-drag -- do view dragging { pointView = pointView.subtract(dragView.Delta(zoom)); dragView.Update(); } + if (Input.pressed(Key.TAB)) ToggleUI(); + if (Input.mouseWheel) { + // scroll a sidebar if overtop of a scrollable one var fSidebarScrolled:Boolean = false; for each (var sidebar: Sidebar in rgsidebar) { @@ -242,7 +271,7 @@ package break; } } - if (!fSidebarScrolled) + if (!fSidebarScrolled) // otherwise adjust zoom { var zoomNew: Number = zoom + (Input.mouseWheelDelta / 100); if (zoomNew <= 0) @@ -258,6 +287,7 @@ package super.update(); } + // message management public function ShowMsg(stMsg: String):void { rgmsg.push(stMsg); @@ -285,12 +315,16 @@ package alarmMsg = Alarm(addTween(new Alarm(2, function():void { sidebarMsg.Toggle(ShowNextMsg); }, Tween.ONESHOT), true)); } } + + // right sidebar commands private function ResetZoom(): void { var pointMiddle: Point = new Point(FP.halfWidth, FP.halfHeight); pointView = PointRealFromScreen(pointMiddle).subtract(pointMiddle); zoom = 1; } + + // persistence (save/load/XML generation) public function Save(): void { var stream: FileStream = new FileStream();