From 0a4d59ee8f4b2ec8d4d5275d6badd5e2ab44c827 Mon Sep 17 00:00:00 2001 From: Ray Greenwell Date: Tue, 5 Feb 2008 08:11:24 +0000 Subject: [PATCH] Documentation improvements. Removed the superfluous EZEvent. git-svn-id: svn+ssh://src.earth.threerings.net/vilya/trunk@554 c613c5cb-e716-0410-b11b-feb51c14d237 --- .../com/threerings/ezgame/AbstractControl.as | 6 ++- .../threerings/ezgame/AbstractGameControl.as | 1 + .../threerings/ezgame/AbstractSubControl.as | 4 ++ .../com/threerings/ezgame/EZBagsSubControl.as | 3 ++ src/as/com/threerings/ezgame/EZEvent.as | 48 ------------------- src/as/com/threerings/ezgame/EZGameControl.as | 3 ++ .../com/threerings/ezgame/EZGameSubControl.as | 21 ++++---- .../threerings/ezgame/EZLocalSubControl.as | 7 ++- .../com/threerings/ezgame/EZNetSubControl.as | 7 ++- .../threerings/ezgame/EZPlayerSubControl.as | 3 ++ .../threerings/ezgame/EZSeatingSubControl.as | 3 ++ .../threerings/ezgame/EZServicesSubControl.as | 3 ++ .../threerings/ezgame/MessageReceivedEvent.as | 12 +++-- .../threerings/ezgame/OccupantChangedEvent.as | 15 ++++-- .../threerings/ezgame/PropertyChangedEvent.as | 11 +++-- .../com/threerings/ezgame/SizeChangedEvent.as | 8 ++-- .../threerings/ezgame/StateChangedEvent.as | 8 ++-- src/as/com/threerings/ezgame/UserChatEvent.as | 11 ++--- 18 files changed, 82 insertions(+), 92 deletions(-) delete mode 100644 src/as/com/threerings/ezgame/EZEvent.as diff --git a/src/as/com/threerings/ezgame/AbstractControl.as b/src/as/com/threerings/ezgame/AbstractControl.as index 63a5fe63..09b571b2 100644 --- a/src/as/com/threerings/ezgame/AbstractControl.as +++ b/src/as/com/threerings/ezgame/AbstractControl.as @@ -28,6 +28,7 @@ import flash.events.EventDispatcher; /** * The abstract base class for Game controls and subcontrols. + * @private */ public class AbstractControl extends EventDispatcher { @@ -54,11 +55,13 @@ public class AbstractControl extends EventDispatcher * at once. * * Example: + * * _ctrl.doBatch(function () :void { * _ctrl.net.set("board", new Array()); * _ctrl.net.set("scores", new Array()); * _ctrl.net.set("captures", 0); * }); + * */ public function doBatch (fn :Function) :void { @@ -96,7 +99,7 @@ public class AbstractControl extends EventDispatcher { // Ideally we want to not be an EventDispatcher so that people // won't try to do this on us, but if we do that, then some other - // object will be the target during dispatch, and that's confusing. + // object will be the target during dispatch, and that's weird. throw new IllegalOperationError(); } @@ -109,6 +112,7 @@ public class AbstractControl extends EventDispatcher try { super.dispatchEvent(event); } catch (err :Error) { + // AFAIK, this will never happen: dispatchEvent catches and copes with all exceptions. trace("Error dispatching event to user game."); trace(err.getStackTrace()); } diff --git a/src/as/com/threerings/ezgame/AbstractGameControl.as b/src/as/com/threerings/ezgame/AbstractGameControl.as index ce536faf..f4ead225 100644 --- a/src/as/com/threerings/ezgame/AbstractGameControl.as +++ b/src/as/com/threerings/ezgame/AbstractGameControl.as @@ -42,6 +42,7 @@ import flash.geom.Point; /** * Abstract base class for GameControl implementations. + * @private */ public class AbstractGameControl extends AbstractControl { diff --git a/src/as/com/threerings/ezgame/AbstractSubControl.as b/src/as/com/threerings/ezgame/AbstractSubControl.as index eac684ff..7ea9139b 100644 --- a/src/as/com/threerings/ezgame/AbstractSubControl.as +++ b/src/as/com/threerings/ezgame/AbstractSubControl.as @@ -25,9 +25,13 @@ import flash.errors.IllegalOperationError; /** * Abstract base class. Do not instantiate. + * @private */ public class AbstractSubControl extends AbstractControl { + /** + * @private + */ public function AbstractSubControl (parent :AbstractControl) { super(); diff --git a/src/as/com/threerings/ezgame/EZBagsSubControl.as b/src/as/com/threerings/ezgame/EZBagsSubControl.as index c0e52333..b9330f0c 100644 --- a/src/as/com/threerings/ezgame/EZBagsSubControl.as +++ b/src/as/com/threerings/ezgame/EZBagsSubControl.as @@ -34,6 +34,9 @@ package com.threerings.ezgame { */ public class EZBagsSubControl extends AbstractSubControl { + /** + * @private Constructed via EZGameControl. + */ public function EZBagsSubControl (parent :AbstractControl) { super(parent); diff --git a/src/as/com/threerings/ezgame/EZEvent.as b/src/as/com/threerings/ezgame/EZEvent.as deleted file mode 100644 index f0cc2c82..00000000 --- a/src/as/com/threerings/ezgame/EZEvent.as +++ /dev/null @@ -1,48 +0,0 @@ -// -// $Id$ -// -// Vilya library - tools for developing networked games -// Copyright (C) 2002-2007 Three Rings Design, Inc., All Rights Reserved -// http://www.threerings.net/code/vilya/ -// -// This library is free software; you can redistribute it and/or modify it -// under the terms of the GNU Lesser General Public License as published -// by the Free Software Foundation; either version 2.1 of the License, or -// (at your option) any later version. -// -// This library is distributed in the hope that it will be useful, -// but WITHOUT ANY WARRANTY; without even the implied warranty of -// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU -// Lesser General Public License for more details. -// -// You should have received a copy of the GNU Lesser General Public -// License along with this library; if not, write to the Free Software -// Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA - -package com.threerings.ezgame { - -import flash.events.Event; - -/** - */ -public /*abstract*/ class EZEvent extends Event -{ - /** - * Access the game control to which this event applies. - * Note: you will need to cast this to the appropriate GameControl type. - */ - public function get gameControl () :AbstractGameControl - { - return _gameCtrl; - } - - public function EZEvent (type :String, gameCtrl :Object) - { - super(type); - _gameCtrl = gameCtrl as AbstractGameControl; - } - - /** The game control for this event. @private */ - protected var _gameCtrl :AbstractGameControl; -} -} diff --git a/src/as/com/threerings/ezgame/EZGameControl.as b/src/as/com/threerings/ezgame/EZGameControl.as index 4f1361d8..c3ea1e5b 100644 --- a/src/as/com/threerings/ezgame/EZGameControl.as +++ b/src/as/com/threerings/ezgame/EZGameControl.as @@ -26,6 +26,9 @@ import flash.display.DisplayObject; /** * The single point of control for each client in your multiplayer EZGame. * + * If you are creating a game for Whirled, you should use WhirledGameControl. + * @see com.whirled.WhirledGameControl + * * Usage: Usually, in your top-level movieclip/sprite: * _ctrl = new EZGameControl(this); * diff --git a/src/as/com/threerings/ezgame/EZGameSubControl.as b/src/as/com/threerings/ezgame/EZGameSubControl.as index 1dd6f34a..6b228db4 100644 --- a/src/as/com/threerings/ezgame/EZGameSubControl.as +++ b/src/as/com/threerings/ezgame/EZGameSubControl.as @@ -90,6 +90,9 @@ package com.threerings.ezgame { */ public class EZGameSubControl extends AbstractSubControl { + /** + * @private Constructed via EZGameControl. + */ public function EZGameSubControl (parent :AbstractGameControl) { super(parent); @@ -295,7 +298,7 @@ public class EZGameSubControl extends AbstractSubControl */ private function controlDidChange_v1 () :void { - dispatch(new StateChangedEvent(StateChangedEvent.CONTROL_CHANGED, _parent)); + dispatch(new StateChangedEvent(StateChangedEvent.CONTROL_CHANGED)); } /** @@ -303,7 +306,7 @@ public class EZGameSubControl extends AbstractSubControl */ private function turnDidChange_v1 () :void { - dispatch(new StateChangedEvent(StateChangedEvent.TURN_CHANGED, _parent)); + dispatch(new StateChangedEvent(StateChangedEvent.TURN_CHANGED)); } /** @@ -311,8 +314,8 @@ public class EZGameSubControl extends AbstractSubControl */ private function gameStateChanged_v1 (started :Boolean) :void { - dispatch(new StateChangedEvent(started ? StateChangedEvent.GAME_STARTED : - StateChangedEvent.GAME_ENDED, _parent)); + dispatch(new StateChangedEvent(started ? StateChangedEvent.GAME_STARTED + : StateChangedEvent.GAME_ENDED)); } /** @@ -320,8 +323,8 @@ public class EZGameSubControl extends AbstractSubControl */ private function roundStateChanged_v1 (started :Boolean) :void { - dispatch(new StateChangedEvent(started ? StateChangedEvent.ROUND_STARTED : - StateChangedEvent.ROUND_ENDED, _parent)); + dispatch(new StateChangedEvent(started ? StateChangedEvent.ROUND_STARTED + : StateChangedEvent.ROUND_ENDED)); } /** @@ -330,8 +333,8 @@ public class EZGameSubControl extends AbstractSubControl private function occupantChanged_v1 (occupantId :int, player :Boolean, enter :Boolean) :void { dispatch(new OccupantChangedEvent( - enter ? OccupantChangedEvent.OCCUPANT_ENTERED : - OccupantChangedEvent.OCCUPANT_LEFT, _parent, occupantId, player)); + enter ? OccupantChangedEvent.OCCUPANT_ENTERED + : OccupantChangedEvent.OCCUPANT_LEFT, occupantId, player)); } /** @@ -339,7 +342,7 @@ public class EZGameSubControl extends AbstractSubControl */ private function userChat_v1 (speaker :int, message :String) :void { - dispatch(new UserChatEvent(_parent, speaker, message)); + dispatch(new UserChatEvent(speaker, message)); } /** Contains any custom game configuration data. @private */ diff --git a/src/as/com/threerings/ezgame/EZLocalSubControl.as b/src/as/com/threerings/ezgame/EZLocalSubControl.as index 9f7b2f49..96bf7c18 100644 --- a/src/as/com/threerings/ezgame/EZLocalSubControl.as +++ b/src/as/com/threerings/ezgame/EZLocalSubControl.as @@ -52,6 +52,9 @@ import flash.geom.Point; */ public class EZLocalSubControl extends AbstractSubControl { + /** + * @private Constructed via EZGameControl. + */ public function EZLocalSubControl (parent :AbstractGameControl) { super(parent); @@ -130,7 +133,7 @@ public class EZLocalSubControl extends AbstractSubControl { super.populateProperties(o); - o["dispatchEvent_v1"] = dispatch; // for re-dispatching key events + o["dispatchEvent_v1"] = dispatch; // for re-dispatching keyboard events o["sizeChanged_v1"] = sizeChanged_v1; } @@ -139,7 +142,7 @@ public class EZLocalSubControl extends AbstractSubControl */ private function sizeChanged_v1 (size :Point) :void { - dispatch(new SizeChangedEvent(_parent, size)); + dispatch(new SizeChangedEvent(size)); } } } diff --git a/src/as/com/threerings/ezgame/EZNetSubControl.as b/src/as/com/threerings/ezgame/EZNetSubControl.as index 1011e81d..034c857a 100644 --- a/src/as/com/threerings/ezgame/EZNetSubControl.as +++ b/src/as/com/threerings/ezgame/EZNetSubControl.as @@ -43,6 +43,9 @@ package com.threerings.ezgame { */ public class EZNetSubControl extends AbstractSubControl { + /** + * @private Constructed via EZGameControl. + */ public function EZNetSubControl (parent :AbstractGameControl) { super(parent); @@ -164,7 +167,7 @@ public class EZNetSubControl extends AbstractSubControl private function propertyWasSet_v1 ( name :String, newValue :Object, oldValue :Object, index :int) :void { - dispatch(new PropertyChangedEvent(_parent, name, newValue, oldValue, index)); + dispatch(new PropertyChangedEvent(name, newValue, oldValue, index)); } /** @@ -172,7 +175,7 @@ public class EZNetSubControl extends AbstractSubControl */ private function messageReceived_v1 (name :String, value :Object) :void { - dispatch(new MessageReceivedEvent(_parent, name, value)); + dispatch(new MessageReceivedEvent(name, value)); } /** Game properties. @private */ diff --git a/src/as/com/threerings/ezgame/EZPlayerSubControl.as b/src/as/com/threerings/ezgame/EZPlayerSubControl.as index 855b73cb..ebeb5561 100644 --- a/src/as/com/threerings/ezgame/EZPlayerSubControl.as +++ b/src/as/com/threerings/ezgame/EZPlayerSubControl.as @@ -27,6 +27,9 @@ package com.threerings.ezgame { */ public class EZPlayerSubControl extends AbstractSubControl { + /** + * @private Constructed via EZGameControl + */ public function EZPlayerSubControl (parent :AbstractGameControl) { super(parent); diff --git a/src/as/com/threerings/ezgame/EZSeatingSubControl.as b/src/as/com/threerings/ezgame/EZSeatingSubControl.as index 0d618d12..49920753 100644 --- a/src/as/com/threerings/ezgame/EZSeatingSubControl.as +++ b/src/as/com/threerings/ezgame/EZSeatingSubControl.as @@ -29,6 +29,9 @@ package com.threerings.ezgame { // TODO: methods for allowing a player to pick a seat in SEATED_CONTINUOUS games. public class EZSeatingSubControl extends AbstractSubControl { + /** + * @private Constructed via EZGameControl. + */ public function EZSeatingSubControl (parent :AbstractControl, game :EZGameSubControl) { super(parent); diff --git a/src/as/com/threerings/ezgame/EZServicesSubControl.as b/src/as/com/threerings/ezgame/EZServicesSubControl.as index 0500c6bc..d0fe5a8c 100644 --- a/src/as/com/threerings/ezgame/EZServicesSubControl.as +++ b/src/as/com/threerings/ezgame/EZServicesSubControl.as @@ -27,6 +27,9 @@ package com.threerings.ezgame { */ public class EZServicesSubControl extends AbstractSubControl { + /** + * @private Constructed via EZGameControl. + */ public function EZServicesSubControl (parent :AbstractGameControl) { super(parent); diff --git a/src/as/com/threerings/ezgame/MessageReceivedEvent.as b/src/as/com/threerings/ezgame/MessageReceivedEvent.as index a48fcd4e..f228fcc5 100644 --- a/src/as/com/threerings/ezgame/MessageReceivedEvent.as +++ b/src/as/com/threerings/ezgame/MessageReceivedEvent.as @@ -26,7 +26,7 @@ import flash.events.Event; /** * Dispatched on the 'net' subcontrol when a message is sent by any client. */ -public class MessageReceivedEvent extends EZEvent +public class MessageReceivedEvent extends Event { /** * The type of all MessageReceivedEvents. @@ -51,10 +51,9 @@ public class MessageReceivedEvent extends EZEvent return _value; } - public function MessageReceivedEvent ( - gameCtrl :Object, messageName :String, value :Object) + public function MessageReceivedEvent (messageName :String, value :Object) { - super(MESSAGE_RECEIVED, gameCtrl); + super(MESSAGE_RECEIVED); _name = messageName; _value = value; } @@ -67,10 +66,13 @@ public class MessageReceivedEvent extends EZEvent override public function clone () :Event { - return new MessageReceivedEvent(_gameCtrl, _name, _value); + return new MessageReceivedEvent(_name, _value); } + /** @private */ protected var _name :String; + + /** @private */ protected var _value :Object; } } diff --git a/src/as/com/threerings/ezgame/OccupantChangedEvent.as b/src/as/com/threerings/ezgame/OccupantChangedEvent.as index d01836e5..c00b0226 100644 --- a/src/as/com/threerings/ezgame/OccupantChangedEvent.as +++ b/src/as/com/threerings/ezgame/OccupantChangedEvent.as @@ -23,7 +23,13 @@ package com.threerings.ezgame { import flash.events.Event; -public class OccupantChangedEvent extends EZEvent +/** + * Dispatched when an occupant enters or leaves. + * + * If a watcher becomes a player, you may get an OCCUPANT_LEFT event where player == false, + * followed immediately by an OCCUPANT_ENTERED event where player == true. + */ +public class OccupantChangedEvent extends Event { /** * @eventType OccupantEntered @@ -47,10 +53,9 @@ public class OccupantChangedEvent extends EZEvent return _player; } - public function OccupantChangedEvent ( - type :String, gameCtrl :Object, occupantId :int, player :Boolean) + public function OccupantChangedEvent (type :String, occupantId :int, player :Boolean) { - super(type, gameCtrl); + super(type); _occupantId = occupantId; _player = player; } @@ -64,7 +69,7 @@ public class OccupantChangedEvent extends EZEvent override public function clone () :Event { - return new OccupantChangedEvent(type, _gameCtrl, _occupantId, _player); + return new OccupantChangedEvent(type, _occupantId, _player); } /** @private */ diff --git a/src/as/com/threerings/ezgame/PropertyChangedEvent.as b/src/as/com/threerings/ezgame/PropertyChangedEvent.as index 66f44028..eed9d399 100644 --- a/src/as/com/threerings/ezgame/PropertyChangedEvent.as +++ b/src/as/com/threerings/ezgame/PropertyChangedEvent.as @@ -27,7 +27,7 @@ import flash.events.Event; * Property change events are dispatched after the property change was * validated on the server. */ -public class PropertyChangedEvent extends EZEvent +public class PropertyChangedEvent extends Event { /** * The type of a property change event. @@ -46,6 +46,8 @@ public class PropertyChangedEvent extends EZEvent /** * Get the property's new value. + * Note: if index is not -1 then this value is merely one element in an array that + * may be fully accessed using the 'net' subcontrol. */ public function get newValue () :Object { @@ -72,10 +74,9 @@ public class PropertyChangedEvent extends EZEvent * Constructor. */ public function PropertyChangedEvent ( - gameCtrl :Object, propName :String, newValue :Object, - oldValue :Object, index :int = -1) + propName :String, newValue :Object, oldValue :Object, index :int = -1) { - super(PROPERTY_CHANGED, gameCtrl); + super(PROPERTY_CHANGED); _name = propName; _newValue = newValue; _oldValue = oldValue; @@ -90,7 +91,7 @@ public class PropertyChangedEvent extends EZEvent override public function clone () :Event { - return new PropertyChangedEvent(_gameCtrl, _name, _newValue, _oldValue, _index); + return new PropertyChangedEvent(_name, _newValue, _oldValue, _index); } /** @private */ diff --git a/src/as/com/threerings/ezgame/SizeChangedEvent.as b/src/as/com/threerings/ezgame/SizeChangedEvent.as index 0fef929e..964bc560 100644 --- a/src/as/com/threerings/ezgame/SizeChangedEvent.as +++ b/src/as/com/threerings/ezgame/SizeChangedEvent.as @@ -29,7 +29,7 @@ import flash.geom.Point; * Dispatched when the size of the game area changes, for example as a result of the user * resizing their browser window. */ -public class SizeChangedEvent extends EZEvent +public class SizeChangedEvent extends Event { /** * The type of this event. @@ -50,9 +50,9 @@ public class SizeChangedEvent extends EZEvent /** * Constructor. */ - public function SizeChangedEvent (gameCtrl :Object, size :Point) + public function SizeChangedEvent (size :Point) { - super(SIZE_CHANGED, gameCtrl); + super(SIZE_CHANGED); _size = size; } @@ -63,7 +63,7 @@ public class SizeChangedEvent extends EZEvent override public function clone () :Event { - return new SizeChangedEvent(_gameCtrl, _size.clone()); + return new SizeChangedEvent(_size.clone()); // since _size is mutable } /** Our implementation details. @private */ diff --git a/src/as/com/threerings/ezgame/StateChangedEvent.as b/src/as/com/threerings/ezgame/StateChangedEvent.as index e78bd019..0e8caad1 100644 --- a/src/as/com/threerings/ezgame/StateChangedEvent.as +++ b/src/as/com/threerings/ezgame/StateChangedEvent.as @@ -26,7 +26,7 @@ import flash.events.Event; /** * Dispatched when the state of the game has changed. */ -public class StateChangedEvent extends EZEvent +public class StateChangedEvent extends Event { /** * Indicates that the game has transitioned to a started state. @@ -65,9 +65,9 @@ public class StateChangedEvent extends EZEvent // TODO: move to own event? public static const TURN_CHANGED :String = "TurnChanged"; - public function StateChangedEvent (type :String, gameCtrl :Object) + public function StateChangedEvent (type :String) { - super(type, gameCtrl); + super(type); } override public function toString () :String @@ -77,7 +77,7 @@ public class StateChangedEvent extends EZEvent override public function clone () :Event { - return new StateChangedEvent(type, _gameCtrl); + return new StateChangedEvent(type); } } } diff --git a/src/as/com/threerings/ezgame/UserChatEvent.as b/src/as/com/threerings/ezgame/UserChatEvent.as index 156b1f75..4d9353da 100644 --- a/src/as/com/threerings/ezgame/UserChatEvent.as +++ b/src/as/com/threerings/ezgame/UserChatEvent.as @@ -26,7 +26,7 @@ import flash.events.Event; /** * Dispatched when a player speaks. */ -public class UserChatEvent extends EZEvent +public class UserChatEvent extends Event { /** * The type of a property change event. @@ -50,12 +50,9 @@ public class UserChatEvent extends EZEvent return _message; } - /** - * Constructor. - */ - public function UserChatEvent (gameCtrl :Object, speaker :int, message :String) + public function UserChatEvent (speaker :int, message :String) { - super(USER_CHAT, gameCtrl); + super(USER_CHAT); _speaker = speaker; _message = message; } @@ -67,7 +64,7 @@ public class UserChatEvent extends EZEvent override public function clone () :Event { - return new UserChatEvent(_gameCtrl, _speaker, _message); + return new UserChatEvent(_speaker, _message); } /** @private */