SCRIPTING: Introducing E-Basic [22871]

E-Basic is a standard object-oriented programming language with over 800 commands, which has been customized to better fit the needs of real-time research. Some of the E-Basic commands were specially developed by PST to accommodate the unique requirements of behavioral research. Unlike BASIC or Pascal, which operate by executing a list of tasks, E-Basic contains distinct sets of objects that are able to perform independent functions and interact with each other to perform assigned tasks.
  

E-Basic is user-friendly, unlike other more advanced languages (e.g., C++), and is nearly identical to Visual Basic for Applications. Essentially, the only part of VBA that will not transfer to E-Basic is the forms used in VBA.

All edits to an experiment should be made via the E-Studio graphical interface using an .es3 file. In E-Studio you will be working with E-Basic script via E-Object from the toolbox. E-Basic script can be used in these objects once they are placed on procedural timelines within the experiment. E-Basic script can also be entered in the User Script or via an InLine object. The script required by an experiment is written into an E-Basic script file (.ebs3) simply by pressing the Generate button in E-Studio. Note that pressing the generate button overwrites the existing .ebs3 file.

User-written E-Basic script is generally placed in one of three places in an experiment:

1. In an InLine object to be executed at a given time during a Procedure. This is the most common placement of script. The script included in an InLine object is inserted “as-is” into the .ebs3 file. The location is determined by the placement of the InLine object in the structure of the experiment.
2. On the User Script window to declare global variables, functions sub-routines and user-defined types.
3. In an InLine Object placed at the beginning of the experiment to initialize variables. For example, global variables declared on the User Script Window must be initialized prior to their use, and it is common to do so at the beginning of the experiment.

For details about the InLine object as well as the User Script window, refer to:
SCRIPTING: Variable Declaration and Initialization [22878]
SCRIPTING: Steps for Writing E-Prime Script [22880]

Syntax
The E-Basic language is object-oriented. Each object has a list of associated properties and methods. An object appears in code using object.property or object.method, where “object” equates to the object’s name and the item after the dot (.) refers to either the object’s particular property or method.

Objects
Objects are the core components of E-Basic. An object in E-Basic is an encapsulation of data and routines into a single unit. The use of objects in E-Basic has the effect of grouping together a set of functions and data items that apply only to a specific object type.

In E-Studio, there are a variety of E-Objects including TextDisplay, Slide, List and so on. The graphical representations of those objects are accessible in E-Basic using the object.property syntax. In the example below, "Instructions" is a TextDisplay object. The statement follows the object.property syntax to set the Text property for the Instructions object.
 

Object.Properties
Objects expose data items, called properties, for programmability. Usually, properties can be both retrieved (Get) and modified (Set). Just as each E-Object in E-Studio has a set of associated properties, so do objects in script. The property of the object is referenced using the object.property syntax.  Essentially, properties store information regarding the behavior or physical appearance of the object. For instance, a TextDisplay object has a Text property, which represents the text to be displayed on the screen.

Object.Methods
Objects also expose internal routines for programmability called methods. In E-Basic, an object method can take the form of a command or a function.

Object.Commands
Commands are quite literally the action or actions that the object can perform. An object command is referenced using the object.command syntax. Commands may or may not take parameters. For example, the Clear command (i.e., object.Clear), which may be used to clear the active display, requires no parameters, while the Rectangle command associated with the Canvas object requires multiple parameters to define the position and size of the rectangle to be drawn. Note, not all commands are available to all objects.

Object.Functions
An object method which returns a value is called a function. An object function is invoked using the object.function syntax. Functions may or may not take parameters. For example, the Mean function (i.e., object.Mean) requires no parameters to return the mean of a collection of values contained within a Summation object. However, the GetPixel function associated with the Canvas object requires parameters in order to return the color value at a particular x, y coordinate position.

Getting Help
The E-Prime Command Reference is launched through the Help menu in E-Studio or by using the link to the website (https://pstnet.com/ecr).  Upon launching the E-Prime Command Reference presents the Table of Contents, Index and Search tabs.

Table of Contents
The Table of Contents tab lists all of the Help topics available within the E-Prime Command Reference. The main Help topics are displayed and can be opened to display related subtopics. The topics within the Contents list may be expanded or collapsed by expanding the 'plus' node (+). When a topic is expanded, information concerning individual subtopics may be displayed by clicking the desired item.

Index
The Index tab displays an alphabetical listing of topics and commands within E-Basic. This is typically the best way to find a specific command or function name. The Help information for a particular topic may be displayed by clicking the topic. The listing of topics in the index may be searched by either typing directly in the Search field, or by scrolling through the topics by using the scroll bar on the right side of the Index listing.

Search
The Search option allows searching for specific words or phrases within the Help topics. After typing in a word to search for in the Help topics and hitting the Enter key or clicking on the List Topics button, the topics in which the word appears are listed, as well as additional suggestions to narrow the search. The Help information for a particular topic may be displayed by clicking the topic.
 

Reading Help Topics
E-Prime Command Reference topics are presented using a standard format for all topics. Each description within the E-Prime Command Reference describes the use of the statement, function, command or object, the syntax and parameters required, any considerations specific to the topic, an example, and a listing of direct links to related topics