1 /*******************************************************************************
\r
2 * Copyright 2011 See AUTHORS file.
\r
4 * Licensed under the Apache License, Version 2.0 (the "License");
\r
5 * you may not use this file except in compliance with the License.
\r
6 * You may obtain a copy of the License at
\r
8 * http://www.apache.org/licenses/LICENSE-2.0
\r
10 * Unless required by applicable law or agreed to in writing, software
\r
11 * distributed under the License is distributed on an "AS IS" BASIS,
\r
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
\r
13 * See the License for the specific language governing permissions and
\r
14 * limitations under the License.
\r
15 ******************************************************************************/
\r
17 package com.badlogic.gdx.scenes.scene2d;
\r
19 import com.badlogic.gdx.graphics.Color;
\r
20 import com.badlogic.gdx.graphics.g2d.SpriteBatch;
\r
21 import com.badlogic.gdx.math.MathUtils;
\r
22 import com.badlogic.gdx.math.Rectangle;
\r
23 import com.badlogic.gdx.math.Vector2;
\r
24 import com.badlogic.gdx.scenes.scene2d.InputEvent.Type;
\r
25 import com.badlogic.gdx.scenes.scene2d.utils.ScissorStack;
\r
26 import com.badlogic.gdx.utils.Array;
\r
27 import com.badlogic.gdx.utils.DelayedRemovalArray;
\r
28 import com.badlogic.gdx.utils.GdxRuntimeException;
\r
29 import com.badlogic.gdx.utils.Pools;
\r
31 /** 2D scene graph node. An actor has a position, rectangular size, origin, scale, rotation, and color. The position corresponds to
\r
32 * the unrotated, unscaled bottom left corner of the actor. The position is relative to the actor's parent. The origin is relative
\r
33 * to the position and is used for scale and rotation.
\r
35 * An actor also has a list of actions that can manipulate the actor over time, and a list of listeners that are notified of
\r
36 * events the actor receives.
\r
38 * @author Nathan Sweet */
\r
39 public class Actor {
\r
40 private Stage stage;
\r
41 private Group parent;
\r
42 private final DelayedRemovalArray<EventListener> listeners = new DelayedRemovalArray(0);
\r
43 private final DelayedRemovalArray<EventListener> captureListeners = new DelayedRemovalArray(0);
\r
44 private final Array<Action> actions = new Array(0);
\r
46 private String name;
\r
47 private Touchable touchable = Touchable.enabled;
\r
48 private boolean visible = true;
\r
50 private float width, height;
\r
51 private float originX, originY;
\r
52 private float scaleX = 1, scaleY = 1;
\r
53 private float rotation;
\r
54 private final Color color = new Color(1, 1, 1, 1);
\r
56 /** Draws the actor. The SpriteBatch is configured to draw in the parent's coordinate system.
\r
57 * {@link SpriteBatch#draw(com.badlogic.gdx.graphics.g2d.TextureRegion, float, float, float, float, float, float, float, float, float)
\r
58 * This draw method} is convenient to draw a rotated and scaled TextureRegion. {@link SpriteBatch#begin()} has already been
\r
59 * called on the SpriteBatch. If {@link SpriteBatch#end()} is called to draw without the SpriteBatch then
\r
60 * {@link SpriteBatch#begin()} must be called before the method returns.
\r
62 * The default implementation does nothing.
\r
63 * @param parentAlpha Should be multipied with the actor's alpha, allowing a parent's alpha to affect all children. */
\r
64 public void draw (SpriteBatch batch, float parentAlpha) {
\r
67 /** Updates the actor based on time. Typically this is called each frame by {@link Stage#act(float)}.
\r
69 * The default implementation calls {@link Action#act(float)} on each action and removes actions that are complete.
\r
70 * @param delta Time in seconds since the last frame. */
\r
71 public void act (float delta) {
\r
72 for (int i = 0, n = actions.size; i < n; i++) {
\r
73 Action action = actions.get(i);
\r
74 if (action.act(delta)) {
\r
75 actions.removeIndex(i);
\r
76 action.setActor(null);
\r
83 /** Sets this actor as the event {@link Event#setTarget(Actor) target} and propagates the event to this actor and ancestor
\r
84 * actors as necessary. If this actor is not in the stage, the stage must be set before calling this method.
\r
86 * Events are fired in 2 phases. The first phase notifies listeners on each actor starting at the root and propagating downward
\r
87 * to (and including) this actor. The second phase notifes listeners on each actor starting at this actor and, if
\r
88 * {@link Event#getBubbles()} is true, propagating upward to the root. If the event is {@link Event#stop() stopped} at any time,
\r
89 * it will not propagate to the next actor.
\r
90 * @return true of the event was {@link Event#cancel() cancelled}. */
\r
91 public boolean fire (Event event) {
\r
92 if (event.getStage() == null) event.setStage(getStage());
\r
93 event.setTarget(this);
\r
95 // Collect ancestors so event propagation is unaffected by hierarchy changes.
\r
96 Array<Group> ancestors = Pools.obtain(Array.class);
\r
97 Group parent = getParent();
\r
98 while (parent != null) {
\r
99 ancestors.add(parent);
\r
100 parent = parent.getParent();
\r
104 // Notify all parent capture listeners, starting at the root. Ancestors may stop an event before children receive it.
\r
105 for (int i = ancestors.size - 1; i >= 0; i--) {
\r
106 Group currentTarget = ancestors.get(i);
\r
107 currentTarget.notify(event, true);
\r
108 if (event.isStopped()) return event.isCancelled();
\r
111 // Notify the target capture listeners.
\r
112 notify(event, true);
\r
113 if (event.isStopped()) return event.isCancelled();
\r
115 // Notify the target listeners.
\r
116 notify(event, false);
\r
117 if (!event.getBubbles()) return event.isCancelled();
\r
118 if (event.isStopped()) return event.isCancelled();
\r
120 // Notify all parent listeners, starting at the target. Children may stop an event before ancestors receive it.
\r
121 for (int i = 0, n = ancestors.size; i < n; i++) {
\r
122 ancestors.get(i).notify(event, false);
\r
123 if (event.isStopped()) return event.isCancelled();
\r
126 return event.isCancelled();
\r
129 Pools.free(ancestors);
\r
133 /** Notifies this actor's listeners of the event. The event is not propagated to any parents. Before notifying the listeners,
\r
134 * this actor is set as the {@link Event#getListenerActor() listener actor}. The event {@link Event#setTarget(Actor) target}
\r
135 * must be set before calling this method. If this actor is not in the stage, the stage must be set before calling this method.
\r
136 * @param capture If true, the capture listeners will be notified instead of the regular listeners.
\r
137 * @return true of the event was {@link Event#cancel() cancelled}. */
\r
138 public boolean notify (Event event, boolean capture) {
\r
139 if (event.getTarget() == null) throw new IllegalArgumentException("The event target cannot be null.");
\r
141 DelayedRemovalArray<EventListener> listeners = capture ? captureListeners : this.listeners;
\r
142 if (listeners.size == 0) return event.isCancelled();
\r
144 event.setListenerActor(this);
\r
145 event.setCapture(capture);
\r
146 if (event.getStage() == null) event.setStage(stage);
\r
149 for (int i = 0, n = listeners.size; i < n; i++) {
\r
150 EventListener listener = listeners.get(i);
\r
151 if (listener.handle(event)) {
\r
153 if (event instanceof InputEvent) {
\r
154 InputEvent inputEvent = (InputEvent)event;
\r
155 if (inputEvent.getType() == Type.touchDown) {
\r
156 event.getStage().addTouchFocus(listener, this, inputEvent.getTarget(), inputEvent.getPointer(),
\r
157 inputEvent.getButton());
\r
164 return event.isCancelled();
\r
167 /** Returns the deepest actor that contains the specified point and is {@link #getTouchable() touchable} and
\r
168 * {@link #isVisible() visible}, or null if no actor was hit. The point is specified in the actor's local coordinate system (0,0
\r
169 * is the bottom left of the actor and width,height is the upper right).
\r
171 * This method is used to delegate touchDown events. If this method returns null, touchDown will not occur.
\r
173 * The default implementation returns this actor if the point is within this actor's bounds.
\r
174 * @param touchable If true, the hit detection will respect the {@link #setTouchable(Touchable) touchability}.
\r
175 * @see Touchable */
\r
176 public Actor hit (float x, float y, boolean touchable) {
\r
177 if (touchable && this.touchable != Touchable.enabled) return null;
\r
178 return x >= 0 && x < width && y >= 0 && y < height ? this : null;
\r
181 /** Removes this actor from its parent, if it has a parent.
\r
182 * @see Group#removeActor(Actor) */
\r
183 public boolean remove () {
\r
184 if (parent != null) return parent.removeActor(this);
\r
188 public boolean addListener (EventListener listener) {
\r
189 if (!listeners.contains(listener, true)) {
\r
190 listeners.add(listener);
\r
196 public boolean removeListener (EventListener listener) {
\r
197 return listeners.removeValue(listener, true);
\r
200 public Array<EventListener> getListeners () {
\r
204 /** Adds a listener that is only notified during the capture phase.
\r
205 * @see #fire(Event) */
\r
206 public boolean addCaptureListener (EventListener listener) {
\r
207 if (!captureListeners.contains(listener, true)) captureListeners.add(listener);
\r
211 public boolean removeCaptureListener (EventListener listener) {
\r
212 return captureListeners.removeValue(listener, true);
\r
215 public Array<EventListener> getCaptureListeners () {
\r
216 return captureListeners;
\r
219 public void addAction (Action action) {
\r
220 action.setActor(this);
\r
221 actions.add(action);
\r
224 public void removeAction (Action action) {
\r
225 if (actions.removeValue(action, true)) action.setActor(null);
\r
228 public Array<Action> getActions () {
\r
232 /** Removes all actions on this actor. */
\r
233 public void clearActions () {
\r
234 for (int i = actions.size - 1; i >= 0; i--)
\r
235 actions.get(i).setActor(null);
\r
239 /** Returns the stage that this actor is currently in, or null if not in a stage. */
\r
240 public Stage getStage () {
\r
244 /** Called by the framework when this actor or any parent is added to a group that is in the stage.
\r
245 * @param stage May be null if the actor or any parent is no longer in a stage. */
\r
246 protected void setStage (Stage stage) {
\r
247 this.stage = stage;
\r
250 /** Returns true if this actor is the same as or is the descendant of the specified actor. */
\r
251 public boolean isDescendantOf (Actor actor) {
\r
252 if (actor == null) throw new IllegalArgumentException("actor cannot be null.");
\r
253 Actor parent = this;
\r
255 if (parent == null) return false;
\r
256 if (parent == actor) return true;
\r
257 parent = parent.getParent();
\r
261 /** Returns true if this actor is the same as or is the ascendant of the specified actor. */
\r
262 public boolean isAscendantOf (Actor actor) {
\r
263 if (actor == null) throw new IllegalArgumentException("actor cannot be null.");
\r
265 if (actor == null) return false;
\r
266 if (actor == this) return true;
\r
267 actor = actor.getParent();
\r
271 /** Returns true if the actor's parent is not null. */
\r
272 public boolean hasParent () {
\r
273 return parent != null;
\r
276 /** Returns the parent actor, or null if not in a stage. */
\r
277 public Group getParent () {
\r
281 /** Called by the framework when an actor is added to a group.
\r
282 * @param parent May be null if the actor has been removed from the parent. */
\r
283 protected void setParent (Group parent) {
\r
284 this.parent = parent;
\r
287 public Touchable getTouchable () {
\r
291 /** Determines how touch events are distributed to this actor. Default is {@link Touchable#enabled}. */
\r
292 public void setTouchable (Touchable touchable) {
\r
293 this.touchable = touchable;
\r
296 public boolean isVisible () {
\r
300 /** If false, the actor will not be drawn and will not receive touch events. Default is true. */
\r
301 public void setVisible (boolean visible) {
\r
302 this.visible = visible;
\r
305 public float getX () {
\r
309 public void setX (float x) {
\r
313 public float getY () {
\r
317 public void setY (float y) {
\r
321 /** Sets the x and y. */
\r
322 public void setPosition (float x, float y) {
\r
327 public void translate (float x, float y) {
\r
332 public float getWidth () {
\r
336 public void setWidth (float width) {
\r
337 this.width = width;
\r
340 public float getHeight () {
\r
344 public void setHeight (float height) {
\r
345 this.height = height;
\r
348 /** Returns y plus height. */
\r
349 public float getTop () {
\r
350 return getY() + getHeight();
\r
353 /** Returns x plus width. */
\r
354 public float getRight () {
\r
355 return getX() + getWidth();
\r
358 /** Sets the width and height. */
\r
359 public void setSize (float width, float height) {
\r
364 /** Adds the specified size to the current size. */
\r
365 public void size (float size) {
\r
366 setWidth(width + size);
\r
367 setHeight(height + size);
\r
370 /** Adds the specified size to the current size. */
\r
371 public void size (float width, float height) {
\r
372 setWidth(this.width + width);
\r
373 setHeight(this.height + height);
\r
376 /** Set bounds the x, y, width, and height. */
\r
377 public void setBounds (float x, float y, float width, float height) {
\r
384 public float getOriginX () {
\r
388 public void setOriginX (float originX) {
\r
389 this.originX = originX;
\r
392 public float getOriginY () {
\r
396 public void setOriginY (float originY) {
\r
397 this.originY = originY;
\r
400 /** Sets the originx and originy. */
\r
401 public void setOrigin (float originX, float originY) {
\r
402 setOriginX(originX);
\r
403 setOriginY(originY);
\r
406 public float getScaleX () {
\r
410 public void setScaleX (float scaleX) {
\r
411 this.scaleX = scaleX;
\r
414 public float getScaleY () {
\r
418 public void setScaleY (float scaleY) {
\r
419 this.scaleY = scaleY;
\r
422 /** Sets the scalex and scaley. */
\r
423 public void setScale (float scale) {
\r
428 /** Sets the scalex and scaley. */
\r
429 public void setScale (float scaleX, float scaleY) {
\r
434 /** Adds the specified scale to the current scale. */
\r
435 public void scale (float scale) {
\r
436 setScaleX(scaleX + scale);
\r
437 setScaleY(scaleY + scale);
\r
440 /** Adds the specified scale to the current scale. */
\r
441 public void scale (float scaleX, float scaleY) {
\r
442 setScaleX(this.scaleX + scaleX);
\r
443 setScaleY(this.scaleY + scaleY);
\r
446 public float getRotation () {
\r
450 public void setRotation (float degrees) {
\r
451 this.rotation = degrees;
\r
454 /** Adds the specified rotation to the current rotation. */
\r
455 public void rotate (float amountInDegrees) {
\r
456 setRotation(rotation + amountInDegrees);
\r
459 public void setColor (Color color) {
\r
460 this.color.set(color);
\r
463 public void setColor (float r, float g, float b, float a) {
\r
464 color.set(r, g, b, a);
\r
467 /** Returns the actor's color, which is mutable. */
\r
468 public Color getColor () {
\r
472 public String getName () {
\r
476 /** Sets a name for easier identification of the actor in application code.
\r
477 * @see Group#findActor(String) */
\r
478 public void setName (String name) {
\r
482 /** Changes the z-order for this actor so it is in front of all siblings. */
\r
483 public void toFront () {
\r
484 setZIndex(Integer.MAX_VALUE);
\r
487 /** Changes the z-order for this actor so it is in back of all siblings. */
\r
488 public void toBack () {
\r
492 /** Sets the z-index of this actor. The z-index is the index into the parent's {@link Group#getChildren() children}, where a
\r
493 * lower index is below a higher index. Setting a z-index higher than the number of children will move the child to the front.
\r
494 * Setting a z-index less than zero is invalid. */
\r
495 public void setZIndex (int index) {
\r
496 if (index < 0) throw new IllegalArgumentException("ZIndex cannot be < 0.");
\r
497 Group parent = getParent();
\r
498 if (parent == null) return;
\r
499 Array<Actor> children = parent.getChildren();
\r
500 if (children.size == 1) return;
\r
501 if (!children.removeValue(this, true)) return;
\r
502 if (index >= children.size)
\r
503 children.add(this);
\r
505 children.insert(index, this);
\r
508 /** Returns the z-index of this actor.
\r
509 * @see #setZIndex(int) */
\r
510 public int getZIndex () {
\r
511 Group parent = getParent();
\r
512 if (parent == null) return -1;
\r
513 return parent.getChildren().indexOf(this, true);
\r
516 /** Calls {@link #clipBegin(float, float, float, float)} to clip this actor's bounds. */
\r
517 public boolean clipBegin () {
\r
518 return clipBegin(getX(), getY(), getWidth(), getHeight());
\r
521 /** Clips the specified screen aligned rectangle, specified relative to the transform matrix of the stage's SpriteBatch. The
\r
522 * transform matrix and the stage's camera must not have rotational components. Calling this method must be followed by a call
\r
523 * to {@link #clipEnd()} if true is returned.
\r
524 * @return false if the clipping area is zero and no drawing should occur.
\r
525 * @see ScissorStack */
\r
526 public boolean clipBegin (float x, float y, float width, float height) {
\r
527 Rectangle tableBounds = Rectangle.tmp;
\r
530 tableBounds.width = width;
\r
531 tableBounds.height = height;
\r
532 Stage stage = getStage();
\r
533 Rectangle scissorBounds = Pools.obtain(Rectangle.class);
\r
534 ScissorStack.calculateScissors(stage.getCamera(), stage.getSpriteBatch().getTransformMatrix(), tableBounds, scissorBounds);
\r
535 if (ScissorStack.pushScissors(scissorBounds)) return true;
\r
536 Pools.free(scissorBounds);
\r
540 /** Ends clipping begun by {@link #clipBegin(float, float, float, float)}. */
\r
541 public void clipEnd () {
\r
542 Pools.free(ScissorStack.popScissors());
\r
545 /** Transforms the specified point in screen coordinates to the actor's local coordinate system. */
\r
546 public Vector2 screenToLocalCoordinates (Vector2 screenCoords) {
\r
547 Stage stage = getStage();
\r
548 if (stage == null) return screenCoords;
\r
549 return stageToLocalCoordinates(stage.screenToStageCoordinates(screenCoords));
\r
552 /** Transforms the specified point in the stage's coordinates to the actor's local coordinate system. */
\r
553 public Vector2 stageToLocalCoordinates (Vector2 stageCoords) {
\r
554 if (parent == null) return stageCoords;
\r
555 parent.stageToLocalCoordinates(stageCoords);
\r
556 parentToLocalCoordinates(stageCoords);
\r
557 return stageCoords;
\r
560 /** Transforms the specified point in the actor's coordinates to be in the stage's coordinates. Note this method will ONLY work
\r
561 * for screen aligned, unrotated, unscaled actors! */
\r
562 public Vector2 localToStageCoordinates (Vector2 localCoords) {
\r
563 Actor actor = this;
\r
564 while (actor != null) {
\r
565 if (actor.getRotation() != 0 || actor.getScaleX() != 1 || actor.getScaleY() != 1)
\r
566 throw new GdxRuntimeException("Only unrotated and unscaled actors may use this method.");
\r
567 localCoords.x += actor.getX();
\r
568 localCoords.y += actor.getY();
\r
569 actor = actor.getParent();
\r
571 return localCoords;
\r
574 /** Transforms the specified point in the actor's coordinates to be in the parent's coordinates. Note this method will ONLY work
\r
575 * for screen aligned, unrotated, unscaled actors! */
\r
576 public Vector2 localToParentCoordinates (Vector2 localCoords) {
\r
577 if (getRotation() != 0 || getScaleX() != 1 || getScaleY() != 1)
\r
578 throw new GdxRuntimeException("Only unrotated and unscaled actors may use this method.");
\r
579 localCoords.x += getX();
\r
580 localCoords.y += getY();
\r
581 return localCoords;
\r
584 /** Converts coordinates for this actor to those of a parent actor. The ascendant does not need to be a direct parent. */
\r
585 public Vector2 localToAscendantCoordinates (Actor ascendant, Vector2 localCoords) {
\r
586 Actor actor = this;
\r
587 while (actor.getParent() != null) {
\r
588 actor.localToParentCoordinates(localCoords);
\r
589 actor = actor.getParent();
\r
590 if (actor == ascendant) break;
\r
592 return localCoords;
\r
595 /** Converts the coordinates given in the parent's coordinate system to this actor's coordinate system. */
\r
596 public Vector2 parentToLocalCoordinates (Vector2 parentCoords) {
\r
597 final float rotation = getRotation();
\r
598 final float scaleX = getScaleX();
\r
599 final float scaleY = getScaleY();
\r
600 final float childX = getX();
\r
601 final float childY = getY();
\r
603 if (rotation == 0) {
\r
604 if (scaleX == 1 && scaleY == 1) {
\r
605 parentCoords.x -= childX;
\r
606 parentCoords.y -= childY;
\r
608 final float originX = getOriginX();
\r
609 final float originY = getOriginY();
\r
610 if (originX == 0 && originY == 0) {
\r
611 parentCoords.x = (parentCoords.x - childX) / scaleX;
\r
612 parentCoords.y = (parentCoords.y - childY) / scaleY;
\r
614 parentCoords.x = (parentCoords.x - childX - originX) / scaleX + originX;
\r
615 parentCoords.y = (parentCoords.y - childY - originY) / scaleY + originY;
\r
619 final float cos = (float)Math.cos(rotation * MathUtils.degreesToRadians);
\r
620 final float sin = (float)Math.sin(rotation * MathUtils.degreesToRadians);
\r
622 final float originX = getOriginX();
\r
623 final float originY = getOriginY();
\r
625 if (scaleX == 1 && scaleY == 1) {
\r
626 if (originX == 0 && originY == 0) {
\r
627 float tox = parentCoords.x - childX;
\r
628 float toy = parentCoords.y - childY;
\r
630 parentCoords.x = tox * cos + toy * sin;
\r
631 parentCoords.y = tox * -sin + toy * cos;
\r
633 final float worldOriginX = childX + originX;
\r
634 final float worldOriginY = childY + originY;
\r
635 final float fx = -originX;
\r
636 final float fy = -originY;
\r
638 final float x1 = cos * fx - sin * fy + worldOriginX;
\r
639 final float y1 = sin * fx + cos * fy + worldOriginY;
\r
641 final float tox = parentCoords.x - x1;
\r
642 final float toy = parentCoords.y - y1;
\r
644 parentCoords.x = tox * cos + toy * sin;
\r
645 parentCoords.y = tox * -sin + toy * cos;
\r
648 if (originX == 0 && originY == 0) {
\r
649 final float tox = parentCoords.x - childX;
\r
650 final float toy = parentCoords.y - childY;
\r
652 parentCoords.x = (tox * cos + toy * sin) / scaleX;
\r
653 parentCoords.y = (tox * -sin + toy * cos) / scaleY;
\r
655 final float worldOriginX = childX + originX;
\r
656 final float worldOriginY = childY + originY;
\r
657 final float fx = -originX * scaleX;
\r
658 final float fy = -originY * scaleY;
\r
660 final float x1 = cos * fx - sin * fy + worldOriginX;
\r
661 final float y1 = sin * fx + cos * fy + worldOriginY;
\r
663 final float tox = parentCoords.x - x1;
\r
664 final float toy = parentCoords.y - y1;
\r
666 parentCoords.x = (tox * cos + toy * sin) / scaleX;
\r
667 parentCoords.y = (tox * -sin + toy * cos) / scaleY;
\r
671 return parentCoords;
\r
674 public String toString () {
\r
675 String name = this.name;
\r
676 if (name == null) {
\r
677 name = getClass().getName();
\r
678 int dotIndex = name.lastIndexOf('.');
\r
679 if (dotIndex != -1) name = name.substring(dotIndex + 1);
\r
681 return name + " " + x + "," + y + " " + width + "x" + height;
\r