some helpful comments / documentation

This commit is contained in:
Jeremy Penner 2011-02-02 09:14:07 -08:00
parent 40eb555605
commit 5c2180f2ed
7 changed files with 58 additions and 20 deletions

View file

@ -1,7 +1,7 @@
package package
{ {
/** /**
* ... * Button widget; when clicked, calls a function.
* @author jjp * @author jjp
*/ */
public class Button extends EntitySidebarImg public class Button extends EntitySidebarImg

View file

@ -3,7 +3,8 @@ package
import flash.geom.Point; import flash.geom.Point;
import net.flashpunk.utils.Input; 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 * @author jjp
*/ */
public class Drag public class Drag

View file

@ -28,5 +28,4 @@ package
public function OnClick(): void { } public function OnClick(): void { }
public function Fade(pct:Number):void { } public function Fade(pct:Number):void { }
} }
} }

View file

@ -5,7 +5,8 @@ package
import flash.events.EventDispatcher; import flash.events.EventDispatcher;
import flash.filesystem.File; 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 * @author jjp
*/ */
public class FileWatcher public class FileWatcher

View file

@ -11,7 +11,8 @@ package
import flash.filesystem.File; import flash.filesystem.File;
import flash.net.URLRequest; 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 * @author jjp
*/ */
public class Imgdir extends EventDispatcher public class Imgdir extends EventDispatcher

View file

@ -11,7 +11,9 @@ package
import net.flashpunk.utils.Ease; 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 * @author jjp
*/ */
public class Sidebar extends Entity public class Sidebar extends Entity

View file

@ -16,6 +16,13 @@
// bar/baz/ -- urfd // bar/baz/ -- urfd
// bar/ -- urpd // 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 package
{ {
import flash.display.BitmapData; import flash.display.BitmapData;
@ -110,15 +117,8 @@ package
{ {
return new Point((pointReal.x - pointView.x) * zoom, (pointReal.y - pointView.y) * zoom); 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 public function UabFromUrf(urf:String): String
{ {
return uabd + urf; return uabd + urf;
@ -131,6 +131,8 @@ package
{ {
return rgurpd.join("") + "/"; return rgurpd.join("") + "/";
} }
// left sidebar (folders and objects) management
public function Chdir(urpd: String): void public function Chdir(urpd: String): void
{ {
if (alarmImgdir !== null) if (alarmImgdir !== null)
@ -160,6 +162,16 @@ package
if (rgurpd.length > 0) if (rgurpd.length > 0)
OnNewImg(new EvNewImg(Imgdir.LOADED, "../", null)); 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 private function SidebarFind(layer: int):Sidebar
{ {
for each (var sidebar:Sidebar in rgsidebar) for each (var sidebar:Sidebar in rgsidebar)
@ -179,6 +191,7 @@ package
return true; return true;
}, this); }, this);
} }
// add a sidebar to the world, replacing an existing sidebar on the same layer (if any).
private function AddSidebar(sidebar: Sidebar):Sidebar private function AddSidebar(sidebar: Sidebar):Sidebar
{ {
RemoveSidebar(sidebar.LayerEntities()); RemoveSidebar(sidebar.LayerEntities());
@ -191,9 +204,22 @@ package
for each (var sidebar: Sidebar in rgsidebar) for each (var sidebar: Sidebar in rgsidebar)
sidebar.Toggle(); 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 override public function update():void
{ {
var dyFactory:int = 0;
if (Input.mouseUp && dragView !== null) if (Input.mouseUp && dragView !== null)
{ {
trace("drag done"); trace("drag done");
@ -203,9 +229,9 @@ package
if (Input.mousePressed) if (Input.mousePressed)
{ {
if (Input.check(Key.SHIFT)) if (Input.check(Key.SHIFT)) // shift-click -- begin view dragging
dragView = Drag.Claim(); dragView = Drag.Claim();
else else // click -- select a token
{ {
var rgtok: Array = []; var rgtok: Array = [];
getLayer(LAYER_TOKENS, rgtok); getLayer(LAYER_TOKENS, rgtok);
@ -223,15 +249,18 @@ package
trace("clicked on " + tokSelected); trace("clicked on " + tokSelected);
} }
} }
if (dragView !== null) if (dragView !== null) // shift-drag -- do view dragging
{ {
pointView = pointView.subtract(dragView.Delta(zoom)); pointView = pointView.subtract(dragView.Delta(zoom));
dragView.Update(); dragView.Update();
} }
if (Input.pressed(Key.TAB)) if (Input.pressed(Key.TAB))
ToggleUI(); ToggleUI();
if (Input.mouseWheel) if (Input.mouseWheel)
{ {
// scroll a sidebar if overtop of a scrollable one
var fSidebarScrolled:Boolean = false; var fSidebarScrolled:Boolean = false;
for each (var sidebar: Sidebar in rgsidebar) for each (var sidebar: Sidebar in rgsidebar)
{ {
@ -242,7 +271,7 @@ package
break; break;
} }
} }
if (!fSidebarScrolled) if (!fSidebarScrolled) // otherwise adjust zoom
{ {
var zoomNew: Number = zoom + (Input.mouseWheelDelta / 100); var zoomNew: Number = zoom + (Input.mouseWheelDelta / 100);
if (zoomNew <= 0) if (zoomNew <= 0)
@ -258,6 +287,7 @@ package
super.update(); super.update();
} }
// message management
public function ShowMsg(stMsg: String):void public function ShowMsg(stMsg: String):void
{ {
rgmsg.push(stMsg); rgmsg.push(stMsg);
@ -285,12 +315,16 @@ package
alarmMsg = Alarm(addTween(new Alarm(2, function():void { sidebarMsg.Toggle(ShowNextMsg); }, Tween.ONESHOT), true)); alarmMsg = Alarm(addTween(new Alarm(2, function():void { sidebarMsg.Toggle(ShowNextMsg); }, Tween.ONESHOT), true));
} }
} }
// right sidebar commands
private function ResetZoom(): void private function ResetZoom(): void
{ {
var pointMiddle: Point = new Point(FP.halfWidth, FP.halfHeight); var pointMiddle: Point = new Point(FP.halfWidth, FP.halfHeight);
pointView = PointRealFromScreen(pointMiddle).subtract(pointMiddle); pointView = PointRealFromScreen(pointMiddle).subtract(pointMiddle);
zoom = 1; zoom = 1;
} }
// persistence (save/load/XML generation)
public function Save(): void public function Save(): void
{ {
var stream: FileStream = new FileStream(); var stream: FileStream = new FileStream();