1 /**
  2  * @class component
  3  * @description
  4  * Extends the functionality of an {@link entity} as a swappable object. </br></br>
  5  *
  6  * To work, all components have hosts; when a host updates, all components do as well.
  7  * Like {@link entity}, a component can have a Draw and a Step function with an overloadable
  8  * OnStep / OnDraw. In addition, all component's also have event handling capabilities.
  9  * Setable with strings, it is possible to maintain and assign functions to run on 
 10  * certain events and even define your own events for custom components.</br></br>
 11  *  
 12  * When making your own components, you will typically also want to include 
 13  * your own custom events. installEvent() is the function that adds 
 14  * a new recognized event with the given name. Once installed, emitEvent() should be called 
 15  * at the appropriate time user functions should be run. </br></br>
 16  *
 17  * All components will emit the 2 fallowing events:
 18  * <pre>
 19  * - on-attach: Called when the component is attached to an entity.
 20  * - on-detach: Called when the component is about to be destroyed.
 21  * </pre>
 22  *
 23  * Built-in components, like {@link clock}, have their installed events marked in their 
 24  * class descriptions.
 25  * @example 
 26  
 27  
 28  *
 29  */ 
 30 function component() {
 31 
 32     /**
 33      * Does the naturally defined step iteration. This invokes the "onStep" property method
 34      * if defined. For built-in components, this may trigger native code.
 35      * For hosts that are part of the engine hierarchy, step() is called for you when 
 36      * the entity step()s.
 37      */
 38     this.step = function(){};
 39 
 40     /**
 41      * Does the naturally defined draw iteration. This invokes the "onDraw" property method
 42      * if defined. For built-in components, this may trigger native code.
 43      * For hosts that are part of the engine hierarchy, draw() is called for you when 
 44      * the entity draw()s.
 45      */
 46     this.draw = function(){};
 47 
 48     /**
 49      * Adds a new event to be recognized by the EventSystem.
 50      *
 51      * if mainHandler is undefined, the event is still added, but has no default
 52      * handler is set. The default handler is always guaranteed to run last for the event.
 53      * @param {String} eventName The name of the new event to install.
 54      * @param {Function} mainHandler (optional) The default handler for this event. Always called first before any hooks. See {@link component.installHandler} for parameters passed to handler function objects.
 55      */
 56     this.installEvent = function(eventName, mainHandler){};
 57 
 58     /**
 59      * Removes the event from the component.
 60      * @param {String} event Event to remove.
 61      */
 62     this.uninstallEvent = function(event){};
 63 
 64     /**
 65      * Triggers the specified event for this component.
 66      *
 67      * Returns whether the event was allowed to propogate all the
 68      * way to the main handler (in other words, lets you know whether
 69      * all the handlers allowed the event to happen)
 70      * Source is passed to the handler and is usually the source of the event (but does not have to be)
 71      * @param {String} eventName Name of the event. This should match the name that was installed.
 72      * @param {entity} source (Optional) entity that indicates the source of the event. For example, in a collision, this may be the object collided with.
 73      */
 74     this.emitEvent = function(eventName, source){};
 75 
 76     /**
 77      * Returns whether the given event is installed.
 78      * @param {String} eventName The event to query.
 79      */
 80     this.canHandleEvent = function(eventName){};
 81 
 82     /**
 83      * Adds a hook to the event. 
 84      *
 85      * A hook happens at the end of a given event after all the
 86      * handlers have been run. Hooks occur regardless of event handler propogation.
 87      * Hook function signatures contain the following parameters: </br></br>
 88      * <pre>
 89      * hook(component, componentHost, eventSource)
 90      * </pre></br></br>
 91      * Where component is the this component, componentHost is the host entity of this component 
 92      * , and eventSource is the entity given from the emitEvent() call, if any.
 93      * @param {String} eventName Name of the installed event.
 94      * @param {Function} hook The hook to add. See class description for function signature.
 95      */
 96     this.installHook = function(eventName, hook){};
 97 
 98     /**
 99      * Removes the given hook.
100      * @param {String} eventName
101      */
102     this.uninstallHook = function(eventName){};
103 
104     /**
105      * Adds a handler to an event. 
106      *
107      * Handlers that are added are run in LIFO order
108      * and their return values dictate whether the event should propogate.
109      * The last handler run for an event is always the main handler of the event. </br>
110      * Handler function signatures contain the following parameters: </br></br>
111      * <pre>
112      * {boolean} handler(component, componentHost, eventSource)
113      * </pre></br></br>
114      * Where component is the this component, componentHost is the host entity of this component 
115      * , and eventSource is the entity given from the emitEvent() call, if any. The return value 
116      * is a boolean determining if the event should continue propogating. If no return value is given, 
117      * the value is assumed true, meaning the event should propogate.
118      * @param {String} eventName Name of the installed event to add a handler to
119      * @param {Function} handler Function to add as the handler.
120      */
121     this.installHandler = function(eventName, handler){};
122 
123     /**
124      * Removes a previously installed handler.
125      * @param {String} eventName
126      */
127     this.uninstallHandler = function(eventName){};
128 
129     /**
130      * Returns a list of all events installed that can be processed.
131      * @returns {Array} An array of event name strings.
132      */
133     this.getKnownEvents = function(){};
134 
135 
136 
137 
138     /**
139      * Function called on the step iteration of the component.
140      * @type {Function}
141      */
142     this.onStep = {};
143 
144     /**
145     * Function called on the draw iteration of the component.
146      * @type {Function}
147      */
148     this.onDraw = {};
149     
150     /**
151      * Function called when the component is attached to a host.
152      * @type {Function}
153      */
154     this.onAttach = {};
155 
156 
157     /**
158      * Identifying tag of the component. The tag can be used in access functions such as {@link entity.queryComponent}.
159      * @type {String}
160      */
161     this.tag = 0;
162 
163     /**
164      * Human-readable information on this component viable in the inspector/debugger. 
165      * For built-in components, this usually contains stats and useful info regarding the current 
166      * state of the component.
167      * @type {String}
168      */
169     this.info = 0;
170 
171     /**
172      * Whether this component should have its step() function called automatically by the engine. 
173      * The default is true.
174      * @type {Boolean}
175      */
176     this.isStepping = 0;
177 
178     /**
179      * Whether this component should have its draw() function called automatically by the engine. 
180      * The default is true.
181      * @type {Boolean}
182      */
183     this.isDrawing = 0;
184 
185     /**
186      * The current host entity of the component. See {@link entity.addComponent}.
187      * @type {entity}
188      */
189     this.host = 0;
190 
191 
192 
193     return this;
194 }
195