May 8, 2012 at 19:57LibGDX tutorial translation - part 3 (scene2d package)
This is the third article in the libGDX tutorial translation series.
The first article is here.
The second article is here.
The scene2d package is a class for implementing a graph for a two-dimensional scene, which can be useful for managing a group of hierarchically related actors (an actor is some entity that can be drawn and which can handle input events - approx. Translator). This package provides support for handling control, drawing with the ability to rotate and scale the actors in the coordinate system relative to the parent actor. This package also provides a framework for controlling the actions of actors at certain intervals (tweening). The scene2d.ui package provides actors who can be useful in building a graphical user interface.
The Stage class has a “root” group where the application can add its actors. The Stage class has its own camera and its own sprite packer (SpriteBatch). The camera viewing area is set equal to the screen size. When the Stage class is rendered, SpriteBatch renders the root group. However, Stage implements the InputProcessor interface and sends input events to the root group.
The Group class is an actor that may contain other actors. The rotation and scaling of the Group reflects on its subsidiaries accordingly. The Group class delegates drawing and input events to the appropriate child actors. It transforms the coordinates of input events so that children receive these coordinates in their own coordinate system.
The Actor class provides basic functionality for representing a scene graph node. It has a position, size, information about the scale, rotation, parent component (origin). Also, an actor can have a name, which allows you to find it by that name and can help with debugging (you can display a hierarchy of actors with their names).
The Stage class has a viewport. You can specify it in the constructor, although it would be a good idea to set this area when the application resizes. The constructor also accepts a boolean parameter called stretch. If this parameter is set to true, the Stage class during drawing will stretch (compress) the image to the screen size if the screen size does not match the size of the Stage viewing area. If this parameter is false, the size of the Stage viewport will be trimmed to the screen resolution. If you configure the viewport in the resize () method, the value of this parameter is not significant.
The Stage class has a method called act, which takes the time that has passed since the last frame was drawn. Calling this method leads to calling the act method of other actors, which allows actors to perform certain actions at certain intervals. Calling the act method on the Stage class is optional.
Extend the abstract class Actor and implement methods for drawing, determining clicks, and handling controls in the scene graph.
When the paint method for the Stage class is called, it invokes the paint method for the root group. In turn, the root group calls drawing methods on child actors. To draw an actor, implement the draw () method:
SpriteBatch, which receives an actor already configured by the parent actor (root group) to correctly display the actor relative to the lower left corner of the root group. These are such parameters as the location of the actor, his size, information about scaling, rotation. This makes drawing the actor in the right place very easy. In the code above, the parameters x, y, width, height are public fields of the Actor class.
If the visible parameter is set to false for a specific actor, the root group will not call the draw () method on it.
The parentAlpha parameter, which is passed to the draw () method, is the color transparency value of the parent component. Given this parameter, the root group and child actors can be translucent (translucent).
The begin () method of the SpriteBatch class is already called when the draw () method of a particular actor is called. If the actor needs to draw himself in some other way, for example, using the ShapeRenderer class, the SpriteBatch class must complete and start packing sprites again (the begin () and end () methods must be called). Of course, this will lead to clearing the buffer of the sprite packer, so you need to use this feature carefully (there may be performance losses - translator comment). You can use the projection matrix and the transformation matrix from the SpriteBatch class:
When you call the hit () method on the Stage () class, it calls the hit () method on the root group. The root group calls the hit () method on the child actors. The first return value is of type Actor and will be the return result of the Stage class. (That is, we go down the hierarchy of actors, and as soon as any actor “thinks” that they clicked on him, he returns himself, and the Stage class returns this actor. - approx. Translator). To intercept clicks, implement the hit () method with the actor:
The hit () method returns the actor that was clicked, or null otherwise. The coordinates are taken relative to the coordinate system of the actor. The code above shows a typical implementation when we return an actor if we click on a point that falls into the rectangle of the actor.
To handle control, implement the touchDown (), touchDragged (), and touchUp () methods:
When the touchDown () method for the Stage class is called, the touchDown () method for the root group is called. The root group calls the hit () method on child actors. The touchDown () method is called for the first actor, which is returned by the hit () method. If the call to touchDown () for this actor returns false, this means that the actor ignores the event and the process continues for the next actor. If touchDown () returns true, the actor gains input focus. This means that it calls the touchDragged () and touchUp () methods, unless of course it ignores them. When the touchUp () method is called for an actor, which is guaranteed to happen, the actor loses input focus.
The touchDown () method for the Group class sends touchDown messages to child actors. If this method is overridden, you must call the base method super (). TouchDown (), otherwise the actors will not receive any events about pressing.
There is also one additional method for processing clicks that can be overridden, it is the touchMoved () method. It can only be called on the desktop PC and it is called when you move the mouse.
Similar to the hit () method, the coordinates that are passed to the control handler methods are given in the coordinate system of the actor.
If the touchable field is set to false for an actor, the Group class will not call methods to handle control for this actor.
To handle keyboard controls, which can only happen on a desktop PC, override the keyDown (), keyUp, and keyTyped () methods. They can only be called up when the actor receives keyboard input focus. This focus can be obtained and reset by calling the keyboardFocus () method of the Stage class.
To handle mouse scrolling, which can only happen on a desktop PC, override the scrolled () method. It will be triggered only when the actor has focus for scrolling. Setting and resetting this focus is done using the scrollFocus method of the Stage class.
Addition: a project with an example
The first article is here.
The second article is here.
scene2d
The scene2d package is a class for implementing a graph for a two-dimensional scene, which can be useful for managing a group of hierarchically related actors (an actor is some entity that can be drawn and which can handle input events - approx. Translator). This package provides support for handling control, drawing with the ability to rotate and scale the actors in the coordinate system relative to the parent actor. This package also provides a framework for controlling the actions of actors at certain intervals (tweening). The scene2d.ui package provides actors who can be useful in building a graphical user interface.
Important classes from the package
The Stage class has a “root” group where the application can add its actors. The Stage class has its own camera and its own sprite packer (SpriteBatch). The camera viewing area is set equal to the screen size. When the Stage class is rendered, SpriteBatch renders the root group. However, Stage implements the InputProcessor interface and sends input events to the root group.
The Group class is an actor that may contain other actors. The rotation and scaling of the Group reflects on its subsidiaries accordingly. The Group class delegates drawing and input events to the appropriate child actors. It transforms the coordinates of input events so that children receive these coordinates in their own coordinate system.
The Actor class provides basic functionality for representing a scene graph node. It has a position, size, information about the scale, rotation, parent component (origin). Also, an actor can have a name, which allows you to find it by that name and can help with debugging (you can display a hierarchy of actors with their names).
Stage class setup
The Stage class has a viewport. You can specify it in the constructor, although it would be a good idea to set this area when the application resizes. The constructor also accepts a boolean parameter called stretch. If this parameter is set to true, the Stage class during drawing will stretch (compress) the image to the screen size if the screen size does not match the size of the Stage viewing area. If this parameter is false, the size of the Stage viewport will be trimmed to the screen resolution. If you configure the viewport in the resize () method, the value of this parameter is not significant.
The Stage class has a method called act, which takes the time that has passed since the last frame was drawn. Calling this method leads to calling the act method of other actors, which allows actors to perform certain actions at certain intervals. Calling the act method on the Stage class is optional.
private Stage stage;
public void create () {
stage = new Stage(0, 0, true);
}
public void resize (int width, int height) {
stage.setViewport(width, height, true);
}
public void render () {
Gdx.gl.glClear(GL10.GL_COLOR_BUFFER_BIT);
stage.act(Gdx.graphics.getDeltaTime());
stage.draw();
}
public void dispose() {
stage.dispose();
}
Actors
Extend the abstract class Actor and implement methods for drawing, determining clicks, and handling controls in the scene graph.
Painting
When the paint method for the Stage class is called, it invokes the paint method for the root group. In turn, the root group calls drawing methods on child actors. To draw an actor, implement the draw () method:
TextureRegion region;
public void draw (SpriteBatch batch, float parentAlpha) {
batch.setColor(1, 1, 1, parentAlpha);
batch.draw(region, x, y, width, height);
}
SpriteBatch, which receives an actor already configured by the parent actor (root group) to correctly display the actor relative to the lower left corner of the root group. These are such parameters as the location of the actor, his size, information about scaling, rotation. This makes drawing the actor in the right place very easy. In the code above, the parameters x, y, width, height are public fields of the Actor class.
If the visible parameter is set to false for a specific actor, the root group will not call the draw () method on it.
The parentAlpha parameter, which is passed to the draw () method, is the color transparency value of the parent component. Given this parameter, the root group and child actors can be translucent (translucent).
The begin () method of the SpriteBatch class is already called when the draw () method of a particular actor is called. If the actor needs to draw himself in some other way, for example, using the ShapeRenderer class, the SpriteBatch class must complete and start packing sprites again (the begin () and end () methods must be called). Of course, this will lead to clearing the buffer of the sprite packer, so you need to use this feature carefully (there may be performance losses - translator comment). You can use the projection matrix and the transformation matrix from the SpriteBatch class:
private ShapeRenderer renderer;
public void draw (SpriteBatch batch, float parentAlpha) {
batch.end();
renderer.setProjectionMatrix(batch.getProjectionMatrix());
renderer.setTransformMatrix(batch.getTransformMatrix());
renderer.translate(x, y, 0);
renderer.begin(ShapeType.Rectangle);
renderer.rect(0, 0, width, height);
renderer.end();
batch.begin();
}
Click Definition
When you call the hit () method on the Stage () class, it calls the hit () method on the root group. The root group calls the hit () method on the child actors. The first return value is of type Actor and will be the return result of the Stage class. (That is, we go down the hierarchy of actors, and as soon as any actor “thinks” that they clicked on him, he returns himself, and the Stage class returns this actor. - approx. Translator). To intercept clicks, implement the hit () method with the actor:
public Actor hit (float x, float y) {
return x > 0 && x < width && y > 0 && y < height ? this : null;
}
The hit () method returns the actor that was clicked, or null otherwise. The coordinates are taken relative to the coordinate system of the actor. The code above shows a typical implementation when we return an actor if we click on a point that falls into the rectangle of the actor.
Touch event handling
To handle control, implement the touchDown (), touchDragged (), and touchUp () methods:
public boolean touchDown (float x, float y, int pointer) {
return true;
}
public void touchDragged (float x, float y, int pointer) {
}
public void touchUp (float x, float y, int pointer) {
}
When the touchDown () method for the Stage class is called, the touchDown () method for the root group is called. The root group calls the hit () method on child actors. The touchDown () method is called for the first actor, which is returned by the hit () method. If the call to touchDown () for this actor returns false, this means that the actor ignores the event and the process continues for the next actor. If touchDown () returns true, the actor gains input focus. This means that it calls the touchDragged () and touchUp () methods, unless of course it ignores them. When the touchUp () method is called for an actor, which is guaranteed to happen, the actor loses input focus.
The touchDown () method for the Group class sends touchDown messages to child actors. If this method is overridden, you must call the base method super (). TouchDown (), otherwise the actors will not receive any events about pressing.
There is also one additional method for processing clicks that can be overridden, it is the touchMoved () method. It can only be called on the desktop PC and it is called when you move the mouse.
Similar to the hit () method, the coordinates that are passed to the control handler methods are given in the coordinate system of the actor.
If the touchable field is set to false for an actor, the Group class will not call methods to handle control for this actor.
To handle keyboard controls, which can only happen on a desktop PC, override the keyDown (), keyUp, and keyTyped () methods. They can only be called up when the actor receives keyboard input focus. This focus can be obtained and reset by calling the keyboardFocus () method of the Stage class.
To handle mouse scrolling, which can only happen on a desktop PC, override the scrolled () method. It will be triggered only when the actor has focus for scrolling. Setting and resetting this focus is done using the scrollFocus method of the Stage class.
Addition: a project with an example