Standard+Object+Methods

Methods for standard objects in an Alice Project
 * METHODS FOR STANDARD OBJECTS**
 * Scene
 * //Add Listener// procedures (events)
 * Ground
 * Camera
 * Camera procedures

**Scene**
Every Alice project has a scene (//this//) that is an instance of the **Scene** class and contains two other standard objects: the ground or water surface (an instance of the **Ground** class), and the //camera// (an instance of the **Camera** class), as shown. Each of these objects has their own procedures, functions, and properties, as defined in their respective classes.



**The standard components of every Alice project**

The **Scene** class has a few procedures, functions and property methods that are exactly the same as in other classes, as shown in the next three figures. See previous descriptions of these procedures, functions, and properties earlier in this section.



**Procedural methods in common with other classes**



**Functional methods in common with other classes**



**Properties methods in common with other classes**

The scene is truly the “universe” of an Alice 3 project because it provides the stage, the actors, and the scenery for animation. For this reason, a scene object has need of many special methods that perform unique operations for creating the scene and animating the characters in the story or game. Unique procedures that are used for setting up a scene and managing the animation are shown.



**Unique procedural methods defined in Scene**

The Alice environment automatically calls the //performGeneratedSetUp, performCustomSetup,// and //initializeEventListeners// procedures (in order) when the user clicks on the //**Run**// button. The //performGeneratedSetUp// procedure contains instructions that were automatically “recorded” as objects were created and arranged in the Scene editor. When //performGeneratedSetUp// is executed, these instructions are used by the Alice system to re-create the scene in the runtime window. The //performCustomSetup// procedure contains instructions that may have been written to adjust the scene in a way not available in the Scene editor. The //initializeEventListeners// procedure contains instructions to start listeners for events such as key presses and mouse clicks while the animation is running. (Specific events and listeners are described below in the Scene Listeners section.) After these three procedures are executed, the scene’s //myFirstMethod// is called and the animation code in the project is executed. Th following table provides further information regarding these unique procedural methods.

**Procedures for**//**thi**//**s scene**
 * **Procedure** || **Argument(s)**  ||  **Description**  ||
 * **performCustomSetup** ||  || Allows the programmer to make adjustments to the starting scene; adjustments that could not be easily made in the Scene Editor. Add program statements to this procedure as is done in any method in Alice. However, all statements here will be executed after the//**Run…**//button is clicked, but before the runtime window is displayed ||
 * **performGeneratedSetup** ||  || When the//**Run…**//button is clicked, Alice inspects the scene built in the Scene Editor and generates the appropriate code necessary to display the scene created by the user in the runtime window.**NOTE: the programmer should not attempt to add or modify code in this procedure, as it is always rewritten whenever the**//**Run…**//**button is clicked.** ||
 * **initializeEventListeners** ||  || This procedure of the**Scene**class is the preferred location in an Alice project for the implementation of event listeners. When the//**Run…**//button is clicked, Alice inspects this procedure and generates the appropriate code necessary to implement the listeners for the project. See section below on listener procedures ||
 * **handleActiveChanged** || //isActive, activationCount//  || TO BE IMPLEMENTED ||
 * **myFirstMethod** ||  || This is where an Alice animation starts, once the runtime window is displayed. Normally this is the method where the programmer creates program statements that control the overall execution of the animation. (A possible exception is**performCustomSetUp,**as described above). ||

This//(scene’s)// unique properties:



**Properties methods for Scene class**

The //setters// and //getters// of the **Scene** class are used to adjust the sky color, the lighting, and the amount of fog in a scene as an animation program is running, as summarized in the next table. These methods are useful for changing the appearance of the scene while the animation is being performed (not for setting up the scene in the Scene editor). For example, to change the scene from a daytime to a nighttime setting, the color of the sky could be made darker and the light in the scene could be decreased.

**Properties setters and getters for Scene class**
 * **Procedure** |||||| **Argument(s)** || **Description** ||
 * **setAtmosphereColor** |||||| //color// || Sets the//color//of the sky in//this//scene ||
 * **setAmbientLightColor** |||||| //color// || Sets the//color//of the primary light source in//this//scene. Think of it as the color of sunlight in an outdoor scene ||
 * **setFogDensity** |||||| //DecimalNumber// || Used to set the//density//of the fog in//this//scene by setting the//density//value in the range of values from**0.0**(no fog) to**1.0**(no visibility of objects within the fog). ||
 * **setFromAboveLightColor** |||||| //color// || Sets the//color//of a secondary light source from above in//this//scene ||
 * **setFromBelowLightColor** |||||| //color// || Sets the//color//of a secondary light source from below in//this//scene ||
 * **Function** || **Return Type** |||| **Description** ||
 * **getAtmosphereColor** || //color// |||| Returns the//color//of the sky in//this//scene ||
 * **getAmbientLightColor** || //color// |||| Returns the//color//of the primary light source in//this//scene; tyou might think of it as the color of sunlight in an outdoor scene ||
 * **getFogDensity** || //DecimalNumber// |||| Returns the value of the density of the fog in//this//scene by getting the//density//value with a range of values from**0.0**(no fog) to**1.0**(no visibility of objects within the fog). ||
 * **getFromAboveLightColor** || //color// |||| Returns the//color//of a secondary light source from above in//this//scene ||
 * **getFromBelowLightColor** || //color// |||| Returns the//color//of a secondary light source from below in//this//scene ||
 * **getFromBelowLightColor** || //color// |||| Returns the//color//of a secondary light source from below in//this//scene ||

//**addListener procedures**//
Listeners are used for creating interactive programs, especially games. **Interactive** means that the user is expected to use the keyboard, mouse, or some other input device to control the actions that occur as the program is running.

A listener is an object that, as a program is running, “listens” for a targeted event and responds to that event when it occurs. For example, a **mouse-click on object** listener will listen for a user to mouse-click on an object in the scene. When the mouse-click on an object occurs, we say the “targeted event has been triggered.” When the event is triggered, the listener executes specified instruction statements in response.

In Alice, to create an interactive program, a Listener object must be added to the scene. A listener object is added to the scene by calling an //addListener// procedure, where //Listener// is a targeted event. For example, //addDefaultModeManipulation// creates a listener object that targets a mouse-click on any object in the scene and responds by allowing the user to drag that object around the scene while the animation is running.

This figure shows a list of //addListener// procedural methods. The table summarizes details about the addListener methods, in terms of what event is targeted and how the listener responds.

**addListener procedural methods**

**addListener target and response**
 * **Procedure** || **Argument(s)** || **Description** ||
 * **adddefaultModelManipulation** ||  || Allows the use the mouse to reposition an object in the virtual world as a program is executing. Ctrl-click turns the object, shift-click raises and lowers the object ||
 * **addSceneActivationListener** || //Scene// || UNDER DEVELOPMENT ||
 * **addKeyPressListener** || //Key// || responds to keyboard input from the user. Able to differentiate between Letter, Number, and Arrow keys ||
 * **addArrowKeyPressListener** || //Key// || responds to keyboard input from the user, specifically for Arrow keys (UP, DOWN, LEFT, RIGHT) ||
 * **addNumberKeyPressListener** || //Key// || responds to keyboard input from the user, specifically for Number keys (0..9) ||
 * **addObjectMoverFor** || //Entity// || The parameter object will be moved FORWARD, BACKWARD, LEFT, and RIGHT, based on its own orientation, when the user presses the UP, DOWN, LEFT, and RIGHT arrow keys respectively ||
 * **addPointOfViewChangeListener** || //transformationListener, shouldListenTo// || UNDER DEVELOPMENT ||
 * **addCollisionStartListener** || //collisionListener, Group1, Group2// || UNDER DEVELOPMENT ||
 * **addCollisionEndListener** || //collisionListener, Group1, Group2// || UNDER DEVELOPMENT ||
 * **addProximityEnterListener** || //proximityListener, Group1, Group2, distance// || UNDER DEVELOPMENT ||
 * **addProximityExitListener** || //proximityListener, Group1, Group2, distance// || UNDER DEVELOPMENT ||
 * **addOcclusionStartListener** || //occlusionEventListener, Group1, Group2// || UNDER DEVELOPMENT ||
 * **addOcclusionEndListener** || //occlusionEventListener, Group1, Group2// || UNDER DEVELOPMENT ||
 * **addMouseClickOnScreenListener** || //???// || responds to mouse click input from the user, anywhere on the screen ||
 * **addMouseClickOnObjectListener** || //???// || responds to mouse click input from the user, on the specified object ||
 * **addTimeListener** || //???// || UNDER DEVELOPMENT ||
 * **addViewEnterListener** || ???, ??? || UNDER DEVELOPMENT ||
 * **addViewExitListener** || //???, ???// || UNDER DEVELOPMENT ||

**Ground**
The Ground class has only a limited number of procedural, functional, and property methods, all of which behave exactly the same as those defined by other classes. The following three figures show the methods for the Ground class. These methods were summarized previously.

**Procedural methods for Ground class**

**Functional method for Ground class**

**Specialized property methods for Ground class**

**Camera**
The camera has many procedural methods that behave exactly the same as those defined by other classes, as shown in in this figure and summarized previously.

//camera procedures//
.  **Camera's procedural methods in common with other classes**

One of the procedural methods shown above in Figure A.29, is defined only for the camera: //moveAndOrientToAGoodVantagePointOf//, as described below.

**Unique Procedural method for Camera class**
 * **Procedure** || **Argument(s)** || **Description** ||
 * **moveAndOrientToAGoodVantagePointOf** || //entity// || Animates the reposition and reorientation of the//camera//from its current position to the vantage point of the entity ||

The Camera class also has only a limited number of functional, and property methods, all of which behave exactly the same as those defined by other classes. The following figures show the functional and property methods for the Camera class. These methods were summarized previously.

**Camera functional methods**

**Camera property methods**