1 /* 2 * Copyright the original author or authors. 3 * 4 * Licensed under the MOZILLA PUBLIC LICENSE, Version 1.1 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.mozilla.org/MPL/MPL-1.1.html 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 import org.as2lib.app.exec.Executable; 18 import org.as2lib.env.event.EventListenerSource; 19 import org.as2lib.env.event.impulse.ImpulseListener; 20 21 /** 22 * {@code Impulse} is a definition for events that gets executed periodically. 23 * 24 * <p>Periodical events could be frame executions, seconds, hours or dates. 25 * {@code Impulse} allows to seperate the certain kind of Impulse from the 26 * execution code. 27 * 28 * <p>The {@code Impulse} executes {@link Executable#execute} on each impulse to 29 * the connected executables. 30 * 31 * Example: 32 * <code> 33 * import org.as2lib.env.event.impulse.Impulse; 34 * import org.as2lib.env.event.impulse.FrameImpulse; 35 * import org.as2lib.app.exec.Call; 36 * 37 * function test(impulse:Impulse) { 38 * trace(impulse+" executed at "+getTimer()+"ms"); 39 * } 40 * 41 * var impulse:Impulse = FrameImpulse.getInstance(); 42 * impulse.connectExecutable(new Call(this, test)); 43 * </code> 44 * 45 * <p>Additionally its possible to work with the impulse as EventListenerSource. 46 * With you can add {@link ImpulseListener} implementations 47 * as listener to the code. 48 * 49 * Listener: 50 * <code> 51 * import org.as2lib.env.event.impulse.ImpulseListener; 52 * import org.as2lib.env.event.impulse.Impulse; 53 * 54 * class TraceImpulseListener implements ImpulseListener { 55 * public function onImpulse(impulse:Impulse):Void { 56 * trace(impulse+" executed at "+getTimer()+"ms"); 57 * } 58 * } 59 * </code> 60 * 61 * Test: 62 * <code> 63 * import org.as2lib.env.event.impulse.Impulse; 64 * import org.as2lib.env.event.impulse.FrameImpulse; 65 * 66 * var impulse:Impulse = FrameImpulse.getInstance(); 67 * impulse.addImpulseListener(new TraceImpulseListener()); 68 * </code> 69 * 70 * <p>The {@link #addListener} referes to eighter {@connectExecutable} or to 71 * {@addImpulseListener} depending to what kind of listener you pass. If you 72 * pass a not-matching impulse it will throw a 73 * {@link org.as2lib.env.except.IllegalArgumentException}. 74 * 75 * @author Martin Heidegger 76 * @version 1.1 77 */ 78 interface org.as2lib.env.event.impulse.Impulse extends EventListenerSource { 79 80 /** 81 * Adds a {@link ImpulseListener} for listening to the onImpulse event to 82 * the Impulse. 83 * 84 * @param listener Listener to be added. 85 */ 86 public function addImpulseListener(listener:ImpulseListener):Void; 87 88 /** 89 * Removes a added {@link ImpulseListener} from listening to the onImpulse 90 * event. 91 * 92 * <p>If the certain listener also implements other event types it will also 93 * be remove from listening to those events. 94 * 95 * @param listener Listener to be added. 96 */ 97 public function removeImpulseListener(listener:ImpulseListener):Void; 98 99 /** 100 * Adds a list of {@link ImpulseListener}s as listener to the events. 101 * 102 * @param listeners List of all listener to add. 103 * @throws IllegalArgumentException if one listener didn't match to any listener type. 104 * @see #addListener 105 */ 106 public function addAllImpulseListeners(listener:Array):Void; 107 108 /** 109 * Getter for the list of all added {@link ImpulseListener}s. 110 * 111 * @return List that contains all added listeners. 112 */ 113 public function getAllImpulseListeners(Void):Array; 114 115 /** 116 * Checks if the {@code listener} has been added. 117 * 118 * @param listener Listener to be checked if it has been added. 119 * @return True if the certain listener has been added. 120 */ 121 public function hasImpulseListener(listener:ImpulseListener):Boolean; 122 123 /** 124 * Removes all added {@link ImpulseListener}s from listening to any event. 125 */ 126 public function removeAllImpulseListeners(Void):Void; 127 128 /** 129 * Connect a certain executable to listen to the continous event. 130 * 131 * @param executable {@link Executable} that should be connected 132 */ 133 public function connectExecutable(executable:Executable):Void; 134 135 /** 136 * Connects a list of {@link Executable}s to be executed on the continous event. 137 * 138 * @param executables List of {@link Executable}s to be added. 139 */ 140 public function connectAllExecutables(executables:Array):Void; 141 142 /** 143 * Getter for the list of all connected {@link Executable}s. 144 * 145 * @return List that contains all connected executables. 146 */ 147 public function getAllConnectedExecutables(Void):Array; 148 149 /** 150 * Disconnect a certain executable from listening to the {@code Impulse}. 151 * 152 * @param executable Executable that should be disconnected 153 */ 154 public function disconnectExecutable(executable:Executable):Void; 155 156 /** 157 * Checks if a certain {@link Executable} has been added as listener. 158 * 159 * @param executable {@link Executable} to be checked if it has been added. 160 * @return True if the certain listener has been added. 161 */ 162 public function isExecutableConnected(executable:Executable):Boolean; 163 164 /** 165 * Method to disconnect all connected Executables 166 */ 167 public function disconnectAllExecutables(Void):Void; 168 169 }