Function+Methods

//Functions that provide access (a link) to an internal joint of an object//  The internal joints of an object are part of a skeletal system. For this reason, a function is called to access an individual joint within the skeletal system. These functions return a //link// to the joint (similar to a link that holds the address of a web page on the web). The Methods panel has three tabs so as to distinguish between // procedural // methods, // functional // methods, and methods related to that object's specific // properties. // This figure illustrates the three tabs in a side-by-side listing, using // penny // (an instance of ** Penguin ** ) as an example.
 * FUNCTIONAL METHODS**
 * Functional Methods **
 * Functions that provide access to the internal joints of an object
 * Getters: Functions that provide access to the dimensional values of an object
 * Other functions
 * Functions for user input

**Side-by-side listing of built-in procedural, functional, and property methods**

****Important concepts:****
 * //Procedural methods// describe actions that may be performed by an object, such as move, turn, or roll. These actions often change the location and/or orientation of an object. The important thing to know about procedural methods is that they each perform an action but do not compute and return an answer to a question.
 * //Functional methods// are expressions that compute and answer a question about an object such as what is its width or height, or what is its distance from another object.
 * //Properties methods are//methods for retrieving (get) and changing (set) specific properties of an object of this class. These specific properties, such as paint, opacity, name, and vehicle, are used in animation rendering.

As an example, some of the functions to access the individual joints of an alien object are illustrated, accompanied by an X-ray view of the alien’s internal joints. (NOTE: Due to page space limitations, not all the alien’s joint access functions are listed here.)

**Functions that link to an internal joint of an object**

The link returned by calling one of these functions provides access to the specified joint of the object, for example, if we wanted a ball to move to the alien’s right hand in a game of catch with another alien, we could write the instruction statement:

**ball.moveTo** //target:// **alien.getRightHand**

It should be noted that these functions are dependent upon the design in the 3D Model for which the object is constructed. For example, the X-ray view of the alien and hare shows that each has the same core set of biped joints but the hare also has a set of joints in its ears that are specific to the **Hare** class (not available to other bipeds).



**X-ray view of alien and hare internal joints**

These commonalities and differences are reflected in the functional methods that get access to an internal joint. Functions that return a link to a biped’s common joints are defined in the **SBiped** class, as shown. The tiles are labeled “objectName,” which could be any biped object.



**Common functional methods for biped joints**

However, the hare has additional joints in its ears and tail. Functions to access these additional joints are provided immediately above those defined for bipeds, as shown.



**Functions to access the joints in the hare’s ears and tail**

//Getters: Functions that return the dimension values of an object// The term “getter” is used to describe a function that returns the current value of a property. In Alice the three dimension (width, height, and depth) properties are of special importance and have their own getter functions. These getter functions for the alien are shown in the figure. The table summarizes these functions.



**Functions that return dimension property values**

**Functions that return dimension value**


 * **Function** ||<  **Return type**  ||<  **Description**  ||
 * **getWidth** || //DecimalNumber//  || Returns the width (left to right) ||
 * **getHeight** || //DecimalNumber//  || Returns the height (bottom to top) ||
 * **getDepth** || //DecimalNumber//  || Returns the depth (front to back) ||

//Other functions//  Some functions do not neatly fit into the descriptive categories of the preceding paragraphs. We have collected these functions into a category called “Other.” Other functions are shown in the figure and summarized in the table.



**Other functional methods**

**Other functional methods**


 * **Function** || **Return type**  ||  **Arguments**  ||  **Description**  ||
 * **isFacing** || //Boolean//  ||  //Model//  || Returns**true**if//this//object is facing the//other//(a 3D Model object) or else returns**false** ||
 * **getDistanceTo** || //DecimalNumber//  ||  //Model//  || Returns the distance from the center point of//this//object to the center point of the//other//(a 3D Model object) ||
 * **getVantagePoint** || //???//  ||  //entity//  || TO BE IMPLEMENTED. Returns the point of view of//this//object ||
 * **isCollidingWith** || //Boolean//  ||  //Model//  || returns true if the bounding box of//this//object intersects in any with the bounding box of the other ( 3D Model object), false otherwise ||
 * **toString** || //TextString//  ||   || NOTE: THIS DOES NOT RETURN THE IDENTIFIER NAME OF THIS OBJECT IN PROGRAM CODE, but the internal identifier used by Alice in the virtual machine ||

**Functions for User Input**  Functions that ask the user to use the keyboard or mouse to enter a value (of a specific type) are provided for all objects in an Alice scene. The value entered by the user is returned by the function, to be stored in a variable or used as an argument in a call to another procedure or function. Functions for User Input are shown.



**Functions for User Input**

When a user input function is called, at runtime, a dialog box is displayed containing a prompt to ask the user to enter a value of a specific type. Of course, Alice does not automatically know what prompt to use in the dialog box. The programmer supplies a prompt that will be displayed. The prompt is the argument to the function within an instruction statement.

An important part of calling a function to get user input is that the value the user enters is expected to be of a specific type. For example, the value the user enters when the //getIntegerFromUser// function is called must be a whole number, not a number containing a decimal or a fraction. Likewise, a variable or a parameter that receives the returned value must be a compatible type with the type of value being returned by the function. For example, if the user enters a String of alphabetic characters, the String cannot be stored in an Integer variable. For this reason, Alice will continue to display the user input dialog box until the user enters a value of the right type.

To each row of the following table, we have attached an image depicting a sample dialog box containing a prompt appropriate as an argument for calling that function.

**User input Table**
 * **Function** || **Return type**  ||  **Argument**  || **Description** ||
 * **getBooleanFromUser** || //Boolean//  ||  //TextString//  || Displays the dialog box with the TextString argument displayed as the prompt and True and False buttons for user input. ||


 * **getStringFromUser** || //TextString//  ||  //TextString//  || Displays the dialog box with the TextString argument displayed as the prompt and a textbox for user input. ||


 * **getDoubleFromUser** || //DecimalNumber//  ||  //TextString//  || Displays the dialog box with the TextString argument displayed as the prompt and a keypad (with a decimal point) for user input. ||


 * **getIntegerFromUser** || //WholeNumber//  ||  //TextString//  || Displays the dialog box with the TextString argument displayed as the prompt and a keypad for user input. ||