The IsActivityFinished property is a property which can be set to true to tell the given Screen that it should no longer be active. Setting IsActivityFinished to true can do a number of things depending on the state of the Screen:

• If the Screen is the ScreenManager's CurrentScreen, then this method will result in the ScreenManager moving to the Screen's NextScreen.

• If the Screen is a Popup Screen, then the Screen will simply destroy itself and remove itself from its parent's mPopups list.

• If the Screen is loading another Screen asynchronously, then setting IsActivityFinished to true will destroy the current Screen and move to the asynchronously-loaded Screen.

The Screen class is a container for Entities, content (such as loaded .png files), an FlatRedBall objects (such as Sprites). Games will usually have only one screen active most of the time. [subpages depth="1"]

Introduction

The MoveToScreen method can be used to move from the current Screen to another Screen. The MoveToScreen method destroys the current Screen and all of its contained Entities, then begin loading the Screen passed to the MoveToScreen method.

MoveToScreen can be called when moving between different types of screens, such as between a TitleScreen and LevelSelectScreen. MoveToScreen should also be used to transition between levels such as moving between Level1 and Level2.

Calling MoveToScreen

MoveToScreen accepts either the type (preferred if you know it) or the name of the screen. The screen name may be fully qualified (such as "YourGame.Screens.Level2") or not fully qualified (such as "Level2"). For example, to move to Level 2, the following code would be used:

this.MoveToScreen(typeof(Level2));

Alternatively, you could pass in the name of Level2:

this.MoveToScreen("YourProject.Screens.Level2");

You can go to the level if it is not fully qualified. This works too:

this.MoveToScreen("Level2");

Resetting a Screen

The MoveToScreen function does the following (in order):

1. Destroys the current Screen

2. Creates the next screen as specified by the argument to MoveToScreen.

MoveToScreen can be used to move to the same screen rather than a different screen. This results in the current screen being destroyed then recreated, resulting in the screen being reset to its original state. For example, consider a situation where the player's character is hit by a bullet. In this case the GameScreen will reset itself:

// assuming there is a function to tell us if the player was hit by a bullet
// This also assumes that this code is written in the GameScreen and not in an entity
bool wasHitByBullet = GetIfHitByBullet();

if(wasHitByBullet)
{
   // GetType returns the GameScreen's type
   this.MoveToScreen(this.GetType());
}

MoveToScreen Destroys the Screen

When the MoveToScreen method is called, the current Screen will be destroyed and the Screen that you are moving to will be created. The things that are destroyed are:

• Any files loaded through Glue for the current Screen or any Entities added to the Screen through Glue

• Any instances of Entities that have been added to Glue

If you have added objects that should be destroyed (such as additional Entities) in your custom code, then you need to make sure to destroy these objects in your CustomInitialize. For more information on whether you need to destroy an Entity or not, and how to destroy Entities which must be destroyed manually, see the Destroying Entities article.

"The Screen that was just unloaded did not clean up after itself" Exception

For more information on this error and how to clean it up, see Cleaning Up Screens.

Passing information to new Screens

The MoveToScreen method has only one parameter - the Screen to move to. It does not accept additional parameters. For information on how to pass additional information to new Screens, see the the Proper Information Access tutorial.

Introduction

The ContentManagerName property returns the Screen's ContentManagerName. For more information on ContentManagers, see the ContentManager page.

Code Example

ContentManagerName can be used when manually loading files. For example, assuming that "Content/MyGraphic.png" is part of your project, you can load it as follows:

// Assuming "this" is a screen (the code is in the Screen's custom code:
Texture2D texture = FlatRedBallServices.Load<Texture2D>(
    "Content/MyGraphic.png", this.ContentManagerName);

Introduction

The CustomDestroy (if using Glue) and Destroy (if not using Glue) methods are called when the Screen is going to be removed from your game. This method should never be manually called - the ScreenManager will call this after the Screen's IsActivityFinished property is set to true. The purpose of the CustomDestroy/Destroy methods is to remove objects which have been manually added to your Screen. In general, any object which has been added to a FlatRedBall manager must be removed. Entities (which automatically add themselves) must be destroyed.

Code Example

The following example shows how a Sprite and Entity can be created and destroyed properly. This uses the Glue custom methods, but the idea is the same. The following are added at your Screen's class scope:

Sprite mMySprite;
MyEntityType mMyEntityInstance;

The following would be contained in CustomInitialize:

mMySprite = SpriteManager.AddSprite("redball.bmp", ContentManagerName);
mMyEntityInstance = new MyEntityType(ContentManagerName);

The following would be contained in CustomDestroy:

SpriteManager.RemoveSprite(mMySprite);
mMyEntityInstance.Destroy();

For Glue Users

Keep in mind that only objects which are instantiated or added in your custom code need to be destroyed in the CustomDestroy method. In other words, if you make an instance of an Entity in a Screen under the Objects item, you do not need to call Destroy on this object. Glue will both instantiate and destroy it automatically.

Introduction

PauseThisScreen can be used to implement pausing. In many cases, this function will effectively provide pause implementation for games.

Example Usage - Pausing With the Keyboard

The following code shows how to pause and unpause the screen using a gamepad's Start button.

void CustomInitialize()
{
    // start spinning the sprite
    SpriteInstance.RotationZVelocity = 3;
}

void CustomActivity(bool firstTimeCalled)
{
    FlatRedBall.Debugging.Debugger.Write("IsPaused: " + this.IsPaused);
    if (InputManager.Xbox360GamePads[0].ButtonPushed(Xbox360GamePad.Button.Start))
    {
        if(IsPaused)
        {
            UnpauseThisScreen();
        }
        else
        {
            PauseThisScreen();
        }
    }
}

When the game is paused, the Sprite automatically stops rotating and resumes when the game is unpaused.

Applying Movement After Pause

When a Screen is paused, the underlying engine logic does not stop. Rather, the velocity of all objects is stopped and stored in instructions. When the screen is unpaused, all velocity values are re-applied. This means that if a velocity is changed after a screen is paused, the object which has been given velocity (or acceleration) will continue to operate while everything else remains paused. Furthermore, whenever a Screen is paused, its CustomActivity continues to be called every frame even while paused. Therefore, you can perform additional logic after a pause.

Example - Applying Movement After Pause

The following code assumes an Entity named Ball. Clicking the cursor creates a new Ball which falls. Pressing the Space toggles pause. Notice that pausing the game will pause all existing entities, but new entities created after a pause will fall normally.

void CustomInitialize()
{
    FlatRedBallServices.Game.IsMouseVisible = true;
}

void CustomActivity(bool firstTimeCalled)
{
    var cursor = GuiManager.Cursor;

    if(cursor.PrimaryClick)
    {
        var position = cursor.WorldPosition.ToVector3();
        var ball = BallFactory.CreateNew(position);
        ball.YAcceleration = -50;
    }

    if(InputManager.Keyboard.KeyPushed(Microsoft.Xna.Framework.Input.Keys.Space))
    {
        if(this.IsPaused)
        {
            UnpauseThisScreen();
        }
        else
        {
            PauseThisScreen();
        }
    }
}

Example - Playing Gum Animations After Pausing

Gum animations internally create Tweeners on the TweenerManager. When the Screen is paused, all Tweeners are paused. If your game includes a Gum object which animates when the game is paused (such as a menu sliding on the screen), you can play the animation after the PauseThisScreen call and the animation will still play normally.

The following code animates a button on-screen after the game is paused.

void CustomInitialize()
{
    GumScreen.CurrentButtonPositionState = GumRuntimes.GameScreenGumRuntime.ButtonPosition.OffScreen;
}

void CustomActivity(bool firstTimeCalled)
{
    if (InputManager.Keyboard.KeyPushed(Microsoft.Xna.Framework.Input.Keys.Escape))
    {
        if (IsPaused)
        {
            UnpauseThisScreen();
            GumScreen.SlideOffAnimation.Play();
            Forms.ButtonInstance.Text = "Unpaused";
        }
        else
        {
            PauseThisScreen();
 
            // The animation must be played after the screen is paused
            // or else it gets paused too.
            GumScreen.SlideOnAnimation.Play();
            Forms.ButtonInstance.Text = "Paused";
        }
    }
}

If you have animations which should persist through pausing, see the ObjectsIgnoringPausing section below.

InstructionManager.ObjectsIgnoringPausing

Objects which do not inherit from the PositionedObject class can be added to the InstructionManager.ObjectsIgnoringPausing so they are ignored during pausing. For a detailed discussion of when to use ObjectsIgnoringPausing, see the ObjectsIgnoringPausing page.

Example - Playing Gum Animations when Paused

Calling PauseThisScreen also pauses the TweenerManager, which inturn pauses all Gum animations. Animations can be excluded from this pausing by adding the animation to the InstructionManager.ObjectsIgnoringPausing. Note that the animation must be added, not the Gum or Forms object.

The following code begins a Button's looping animation in CustomInitialize. Its animation is added to InstructionManager.ObjectsIgnoringPausing which results in the button continuing to animate even if the game is paused.

void CustomInitialize()
{
    GumScreen.ButtonInstance.GrowShrinkAnimation.Play();
    InstructionManager.ObjectsIgnoringPausing.Add(
        GumScreen.ButtonInstance.GrowShrinkAnimation);

    // Forms.ButtonInstance is the Forms wrapper for the 
    // GumScreen.ButtonInstance.
    Forms.ButtonInstance.Text = "Unpaused";
}

void CustomActivity(bool firstTimeCalled)
{
    if (InputManager.Keyboard.KeyPushed(Microsoft.Xna.Framework.Input.Keys.Escape))
    {
        if (IsPaused)
        {
            UnpauseThisScreen();
            Forms.ButtonInstance.Text = "Unpaused";
        }
        else
        {
            PauseThisScreen();
            Forms.ButtonInstance.Text = "Paused";
        }
    }
}

Notice that when the game is paused the player's movement stops but the Button continues to animate.