Add docs for screen switching.

arcade/application.py

@@ -632,11 +632,16 @@ def open_window(width: int, height: int, window_title: str, resizable: bool = Fa
 
 class View:
     """
-    TODO:Thoughts:
-    - is there a need for a close()/on_close() method?
+    Support different views/screens in a window.
     """
-    def __init__(self):
-        self.window = None
+    def __init__(self,
+                 window: Window = None):
+
+        if window is None:
+            self.window = arcade.get_window()
+        else:
+            self.window = window
+
         self.button_list: List[TextButton] = []
         self.dialogue_box_list: List[DialogueBox] = []
         self.text_list: List[TextLabel] = []

arcade/examples/sprite_collect_coins.py

@@ -11,7 +11,6 @@
 
 import random
 import arcade
-import os
 
 # --- Constants ---
 SPRITE_SCALING_PLAYER = 0.5
@@ -31,13 +30,6 @@ def __init__(self):
         # Call the parent class initializer
         super().__init__(SCREEN_WIDTH, SCREEN_HEIGHT, SCREEN_TITLE)
 
-        # Set the working directory (where we expect to find files) to the same
-        # directory this .py file is in. You can leave this out of your own
-        # code, but it is needed to easily run the examples using "python -m"
-        # as mentioned at the top of this program.
-        file_path = os.path.dirname(os.path.abspath(__file__))
-        os.chdir(file_path)
-
         # Variables that will hold sprite lists
         self.player_list = None
         self.coin_list = None

doc/enhancement_list.rst

@@ -82,7 +82,6 @@ Documentation
 * `Issue 452 <https://github.com/pvcraven/arcade/issues/452>`_
   Documentation Request - explain how delta_time works to help learners fully
   understand both how and why.
-* Explain the 'views' setup for doing instruction screens and more.
 * Show how to make into a redistributable/installable/exe
 * `Issue 671 <https://github.com/pvcraven/arcade/issues/671>`_
   Documentation Request - Add drag and drop examples. Tiles, cards, moving inventory

doc/examples/index.rst

@@ -409,6 +409,8 @@ Procedural Generation
 User Interface
 --------------
 
+.. _view-examples:
+
 Instruction Screens and Game Over Screens
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 

doc/examples/platform_tutorial/index.rst

@@ -419,7 +419,6 @@ Explore On Your Own
 * Practice creating your own layout with different tiles.
 * Add background images. See :ref:`sprite_collect_coins_background`
 * Add moving platforms. See :ref:`sprite_moving_platforms`
-* Add ramps. See :ref:`sprite_ramps`
 * Change the character image based on the direction she is facing.
   See :ref:`sprite_face_left_or_right`
 * Add instruction and game over screens.

doc/examples/view_instructions_and_game_over.rst

@@ -5,6 +5,7 @@
 Using Views for Instruction and Game Over Screens
 =================================================
 
+You might also want to check out :ref:`view-tutorial`.
 
 .. literalinclude:: ../../arcade/examples/view_instructions_and_game_over.py
     :caption: view_instructions_and_game_over.py

doc/examples/view_pause_screen.rst

@@ -5,6 +5,7 @@
 Using Views for a Pause Screen
 ==============================
 
+You might also want to check out :ref:`view-tutorial`.
 
 .. literalinclude:: ../../arcade/examples/view_pause_screen.py
     :caption: view_pause_screen.py

doc/examples/view_screens_minimal.rst

@@ -5,6 +5,7 @@
 Minimal Views Example
 =====================
 
+You might also want to check out :ref:`view-tutorial`.
 
 .. literalinclude:: ../../arcade/examples/view_screens_minimal.py
     :caption: view_screens_minimal.py

doc/tutorials/views/01_views.py

@@ -0,0 +1,109 @@
+import random
+import arcade
+
+# --- Constants ---
+SPRITE_SCALING_PLAYER = 0.5
+SPRITE_SCALING_COIN = .25
+COIN_COUNT = 50
+
+SCREEN_WIDTH = 800
+SCREEN_HEIGHT = 600
+SCREEN_TITLE = "Implement Views Example"
+
+
+class MyGame(arcade.Window):
+    """ Our custom Window Class"""
+
+    def __init__(self):
+        """ Initializer """
+        # Call the parent class initializer
+        super().__init__(SCREEN_WIDTH, SCREEN_HEIGHT, SCREEN_TITLE)
+
+        # Variables that will hold sprite lists
+        self.player_list = None
+        self.coin_list = None
+
+        # Set up the player info
+        self.player_sprite = None
+        self.score = 0
+
+        # Don't show the mouse cursor
+        self.set_mouse_visible(False)
+
+        arcade.set_background_color(arcade.color.AMAZON)
+
+    def setup(self):
+        """ Set up the game and initialize the variables. """
+
+        # Sprite lists
+        self.player_list = arcade.SpriteList()
+        self.coin_list = arcade.SpriteList()
+
+        # Score
+        self.score = 0
+
+        # Set up the player
+        # Character image from kenney.nl
+        self.player_sprite = arcade.Sprite(":resources:images/animated_characters/female_person/femalePerson_idle.png",
+                                           SPRITE_SCALING_PLAYER)
+        self.player_sprite.center_x = 50
+        self.player_sprite.center_y = 50
+        self.player_list.append(self.player_sprite)
+
+        # Create the coins
+        for i in range(COIN_COUNT):
+
+            # Create the coin instance
+            # Coin image from kenney.nl
+            coin = arcade.Sprite(":resources:images/items/coinGold.png",
+                                 SPRITE_SCALING_COIN)
+
+            # Position the coin
+            coin.center_x = random.randrange(SCREEN_WIDTH)
+            coin.center_y = random.randrange(SCREEN_HEIGHT)
+
+            # Add the coin to the lists
+            self.coin_list.append(coin)
+
+    def on_draw(self):
+        """ Draw everything """
+        arcade.start_render()
+        self.coin_list.draw()
+        self.player_list.draw()
+
+        # Put the text on the screen.
+        output = f"Score: {self.score}"
+        arcade.draw_text(output, 10, 20, arcade.color.WHITE, 14)
+
+    def on_mouse_motion(self, x, y, dx, dy):
+        """ Handle Mouse Motion """
+
+        # Move the center of the player sprite to match the mouse x, y
+        self.player_sprite.center_x = x
+        self.player_sprite.center_y = y
+
+    def on_update(self, delta_time):
+        """ Movement and game logic """
+
+        # Call update on all sprites (The sprites don't do much in this
+        # example though.)
+        self.coin_list.update()
+
+        # Generate a list of all sprites that collided with the player.
+        coins_hit_list = arcade.check_for_collision_with_list(self.player_sprite, self.coin_list)
+
+        # Loop through each colliding sprite, remove it, and add to the score.
+        for coin in coins_hit_list:
+            coin.remove_from_sprite_lists()
+            self.score += 1
+
+
+def main():
+    """ Main method """
+    window = MyGame()
+    window.setup()
+    arcade.run()
+
+
+if __name__ == "__main__":
+    main()

doc/tutorials/views/01_views.rst

@@ -0,0 +1,10 @@
+:orphan:
+
+.. _01_views:
+
+01_views.py Full Listing
+------------------------
+
+.. literalinclude:: 01_views.py
+    :caption: 01_views.py
+    :linenos:

doc/tutorials/views/02_views.py

@@ -0,0 +1,112 @@
+import random
+import arcade
+
+# --- Constants ---
+SPRITE_SCALING_PLAYER = 0.5
+SPRITE_SCALING_COIN = .25
+COIN_COUNT = 50
+
+SCREEN_WIDTH = 800
+SCREEN_HEIGHT = 600
+SCREEN_TITLE = "Implement Views Example"
+
+
+class GameView(arcade.View):
+    """ Our custom Window Class"""
+
+    def __init__(self):
+        """ Initializer """
+        # Call the parent class initializer
+        super().__init__()
+
+        # Variables that will hold sprite lists
+        self.player_list = None
+        self.coin_list = None
+
+        # Set up the player info
+        self.player_sprite = None
+        self.score = 0
+
+        # Don't show the mouse cursor
+        self.window.set_mouse_visible(False)
+
+        arcade.set_background_color(arcade.color.AMAZON)
+
+    def setup(self):
+        """ Set up the game and initialize the variables. """
+
+        # Sprite lists
+        self.player_list = arcade.SpriteList()
+        self.coin_list = arcade.SpriteList()
+
+        # Score
+        self.score = 0
+
+        # Set up the player
+        # Character image from kenney.nl
+        self.player_sprite = arcade.Sprite(":resources:images/animated_characters/female_person/femalePerson_idle.png",
+                                           SPRITE_SCALING_PLAYER)
+        self.player_sprite.center_x = 50
+        self.player_sprite.center_y = 50
+        self.player_list.append(self.player_sprite)
+
+        # Create the coins
+        for i in range(COIN_COUNT):
+
+            # Create the coin instance
+            # Coin image from kenney.nl
+            coin = arcade.Sprite(":resources:images/items/coinGold.png",
+                                 SPRITE_SCALING_COIN)
+
+            # Position the coin
+            coin.center_x = random.randrange(SCREEN_WIDTH)
+            coin.center_y = random.randrange(SCREEN_HEIGHT)
+
+            # Add the coin to the lists
+            self.coin_list.append(coin)
+
+    def on_draw(self):
+        """ Draw everything """
+        arcade.start_render()
+        self.coin_list.draw()
+        self.player_list.draw()
+
+        # Put the text on the screen.
+        output = f"Score: {self.score}"
+        arcade.draw_text(output, 10, 20, arcade.color.WHITE, 14)
+
+    def on_mouse_motion(self, x, y, dx, dy):
+        """ Handle Mouse Motion """
+
+        # Move the center of the player sprite to match the mouse x, y
+        self.player_sprite.center_x = x
+        self.player_sprite.center_y = y
+
+    def on_update(self, delta_time):
+        """ Movement and game logic """
+
+        # Call update on all sprites (The sprites don't do much in this
+        # example though.)
+        self.coin_list.update()
+
+        # Generate a list of all sprites that collided with the player.
+        coins_hit_list = arcade.check_for_collision_with_list(self.player_sprite, self.coin_list)
+
+        # Loop through each colliding sprite, remove it, and add to the score.
+        for coin in coins_hit_list:
+            coin.remove_from_sprite_lists()
+            self.score += 1
+
+
+def main():
+    """ Main method """
+
+    window = arcade.Window(SCREEN_WIDTH, SCREEN_HEIGHT, SCREEN_TITLE)
+    start_view = GameView()
+    window.show_view(start_view)
+    start_view.setup()
+    arcade.run()
+
+
+if __name__ == "__main__":
+    main()

doc/tutorials/views/02_views.rst

@@ -0,0 +1,10 @@
+:orphan:
+
+.. _02_views:
+
+02_views.py Full Listing
+------------------------
+
+.. literalinclude:: 02_views.py
+    :caption: 02_views.py
+    :linenos:

doc/tutorials/views/02_views_diff.rst

@@ -0,0 +1,10 @@
+:orphan:
+
+.. _02_views_diff:
+
+02_views.py Diff
+----------------
+
+.. literalinclude:: 02_views.py
+    :caption: 02_views.py
+    :diff: 01_views.py