PEBLEnvironment - System and Environment¶

This module contains functions for system interaction, timing, input/output, and environment management.

ClearEventLoop()¶

Clears all trigger events from event loop

Description:

Clears the event loop. This function is currently experimental, and its usage may change in future versions of PEBL.

Usage:

## shows a way to generate custom WaitForMouseButton
RegisterEvent("<MOUSE_BUTTON_PRESS>",1,1,"<EQUAL>","", [])
out <-   StartEventLoop()
ClearEventLoop()

See Also:

RegisterEvent(), StartEventLoop()

CallFunction()¶

Calls a PEBL function by name with a list of arguments

Description:

Calls a PEBL function dynamically using its name as a string and a list of arguments. This is useful for implementing callbacks, event handlers, or calling functions whose names are determined at runtime.

Usage:

CallFunction(<function_name>, <argument_list>)

Example:

## Call a function by name
result <- CallFunction("Max", [1, 5, 3, 2])
Print(result)  # == 5

## Use for callbacks
myCallback <- "ProcessResponse"
CallFunction(myCallback, [response, rt])

CheckProcessStatus()¶

Checks if a background process is still running

Description:

Checks the status of a background process launched with SystemCall(). Takes a process ID (PID) as an argument and returns 1 if the process is still running, 0 if it has finished, or -1 if there was an error checking the status. This is only available on Unix/Linux systems and requires the process to have been launched from within PEBL.

Usage:

CheckProcessStatus(<pid>)

Example:

##Launch a background process (Unix only)
pid <- SystemCall("sleep 5 &")

##Check if it's still running
status <- CheckProcessStatus(pid)
if(status == 1)
{
   Print("Process still running")
} elseif(status == 0) {
   Print("Process finished")
} else {
   Print("Error checking process")
}

See Also:

SystemCall(), GetSystemType()

DeleteFile()¶

Deletes a file

Description:

Deletes a file from the file system.

Usage:

DeleteFile( <filename>)

Example:

tmpfile <- FileOpenWrite("tmp.txt")
FilePrint(tmpfile,Random())
FileClose(tmpfile)
text <- FileReadText("tmp.txt")
DeleteFile("tmp.txt")

ExitQuietly()¶

Description:

Stops PEBL and prints <message> to stderr. Unlike SignalFatalError, it will NOT pop-up a window with the error message. Useful exiting a study or application without causing a popup error message.

Usage:

ExitQuietly(<message>)

Example:

If(response == "exit")
     {
        ExitQuietly("Exiting study.")
     }
     ##Prints out error message and
     ##line/filename of function

See Also:

MessageBox, Print(), SignalFatalError()

FileExists()¶

Checks whether a file exists

Description:

Checks whether a file exists. Returns 1 if it exists, 0 otherwise.

Usage:

FileExists(<path>)

Example:

filename <- "data-"+gSubNum+".csv"
 exists <-  FileExists(filename)
  if(exists)
   {
    MessageBox("Subject file already exists. "+
    " Please try a new one.",gWin)
    SignalFatalError("filename already used")
   }

GetCurrentScreenResolution()¶

Description:

Returns an list of [width,height] specifying what the current computer screen resolution is. This is used within the pebl launcher in order to use the current resolution to run the experiment.

Usage:

res <- GetCurrentScreenResolution()

Example:

define Start(p)
{
   ## For testing, let's make the screen resolution a bit smaller than the
   ## current one so that it doesn't get hidden by the bottom task bar
   ##
   res <- GetCurrentScreenResolution()
   gVideoWidth <- First(res)-100
   gVideoHeight <- Second(res)-100
   gWin <- MakeWindow()
   MessageBox("Window slightly smaller than screen",gWin)
}

See Also:

GetVideoModes()

GetDirectoryListing()¶

Returns a list of all the files/subdirectories in a path

Description:

Returns a list of files and directories in a particular directory/folder.

Usage:

list <- GetDirectoryListing(<path>)

Example:

files <-  GetDirectoryListing("./")

GetDrivers()¶

Gets a list of possible video drivers

Description:

Gets a list of video drivers on the current platform. This is usually one of opengl, opengles, software, and directx, different ones of which are available on different platforms. This is most useful for building launchers, although it could be used within a script before MakeWindow is called to choose the best available driver.

Usage:

drivers <- GetDrivers()

See Also:

GetCurrentScreenResolution(), gVideoWidth(), gVideoHeight(), GetVideoModes()

GetExecutableName()¶

Returns the name/path of the PEBL executable

Description:

This function signals a fatal error directing users to use the global variable gExecutableName instead. The executable name is set at program startup and stored in this global variable.

Usage:

name <- gExecutableName  ##Use this global variable instead

GetHomeDirectory()¶

Returns the user’s home directory path

Description:

Returns the path to the current user’s home directory. This is platform-specific and will return different values on Windows, Linux, and Mac OS.

Usage:

GetHomeDirectory()

Example:

homedir <- GetHomeDirectory()
Print("User home directory: " + homedir)

GetJoystickAxisState()¶

Gets the state of a joystick axis

Description:

This gets the state of a particular joystick axis. You need to specify a joystick object, which is created with OpenJoystick(). You also need to specify the axis. You can determine how many axes a joystick has with the GetNumJoystickAxes() function. The function returns a value between 1 and 32768.

See Also:

GetNumJoysticks(), OpenJoystick(), GetNumJoystickAxes() GetNumJoystickBalls(), GetNumJoystickButtons(), GetNumJoystickHats() GetJoystickAxisState(), GetJoystickHatState(), GetJoystickButtonState()

GetJoystickBallState()¶

Gets the state of a joystick ball

Description:

Not implemented.

See Also:

GetNumJoysticks(), OpenJoystick(), GetNumJoystickAxes() GetNumJoystickBalls(), GetNumJoystickButtons(), GetNumJoystickHats() GetJoystickAxisState(), GetJoystickHatState(), GetJoystickButtonState()

GetJoystickButtonState()¶

Description:

This gets the state of a particular joystick button. You need to specify a joystick object, which is created with OpenJoystick(). You also need to specify the button. You can determine how many buttons a joystick has with the GetNumJoystickButtons() function. The function returns either 0 (for unpressed) or 1 (for pressed).

See Also:

GetNumJoysticks(), OpenJoystick(), GetNumJoystickAxes() GetNumJoystickBalls(), GetNumJoystickButtons(), GetNumJoystickHats() GetJoystickAxisState(), GetJoystickHatState(), GetJoystickButtonState()

GetJoystickHatState()¶

Gets the state of a joystick hat

Description:

GetJoystickHatState(js,1) This gets the state of a particular joystick hat. You need to specify a joystick object, which is created with OpenJoystick(). You also need to specify the hat id. You can determine how many hats a joystick has with the GetNumJoystickHats() function. The function returns a value between 0 and 15, which is the sum of values specifying whether each primary NSEW direction is pressed. The coding is: 0=no buttons; 1=N, 2=E, 4=S, 8=W. Thus, if 1 is returned, the north hat button is pressed. If 3 is returned, NorthEast. If 12 is returned, SW, and so on.

See Also:

GetNumJoysticks(), OpenJoystick(), GetNumJoystickAxes() GetNumJoystickBalls(), GetNumJoystickButtons(), GetNumJoystickHats() GetJoystickAxisState(), GetJoystickHatState(), GetJoystickButtonState()

GetMouseCursorPosition()¶

Description:

Gets the current x,y coordinates of the mouse pointer.

Usage:

GetMouseCursorPosition()

Example:

pos <- GetMouseCursorPosition()

GetMouseState()¶

Gets [x,y,b1,b2,b3] list of mouse state, including button states

Description:

Gets the current x,y coordinates of the mouse pointer, plus the current state of the buttons. Returns a 5-element list, with the first two indicating x,y position, the third is either 0 or 1 depending on if the left mouse is clicked, the fourth 0 or 2 depending on whether the middle mouse is clicked, and the fifth either 0 or 4 depending on whether the right mouse is clicked.

Example:

define Start(p)
{

  win <- MakeWindow()
  i <- 1
  while(i < 100)
  {
    Draw()
    Print(GetMouseState())

    Wait(100)
    i <- i + 1

  }
##Returns look like:
[417, 276, 0, 0, 0]
[495, 286, 0, 0, 0]
[460, 299, 0, 0, 0]
[428, 217, 0, 0, 0]
[446, 202, 0, 0, 4]
[446, 202, 1, 0, 0]
[446, 202, 1, 0, 0]
[446, 202, 0, 2, 0]

GetNumJoystickAxes()¶

Counts how many axes on a joystick

Description:

This gets the number of axes on a joystick. You need to specify a joystick object, which is created with OpenJoystick().

See Also:

GetNumJoysticks(), OpenJoystick(), GetNumJoystickAxes() GetNumJoystickBalls(), GetNumJoystickButtons(), GetNumJoystickHats() GetJoystickAxisState(), GetJoystickHatState(), GetJoystickButtonState()

GetNumJoystickBalls()¶

Counts how many balls on a joystick

Description:

This gets the number of joystick balls available on a particular joystick. You need to specify a joystick object, which is created with OpenJoystick().

See Also:

GetNumJoysticks(), OpenJoystick(), GetNumJoystickAxes() GetNumJoystickBalls(), GetNumJoystickButtons(), GetNumJoystickHats() GetJoystickAxisState(), GetJoystickHatState(), GetJoystickButtonState()

GetNumJoystickButtons()¶

Description:

This gets the number of joystick buttons available on a particular joystick. You need to specify a joystick object, which is created with OpenJoystick().

See Also:

GetNumJoysticks(), OpenJoystick(), GetNumJoystickAxes() GetNumJoystickBalls(), GetNumJoystickButtons(), GetNumJoystickHats() GetJoystickAxisState(), GetJoystickHatState(), GetJoystickButtonState()

GetNumJoystickHats()¶

Counts how many hats on a joystick

Description:

This gets the number of hats available on a particular joystick. You need to specify a joystick object, which is created with OpenJoystick().

See Also:

GetNumJoysticks(), OpenJoystick(), GetNumJoystickAxes() GetNumJoystickBalls(), GetNumJoystickButtons(), GetNumJoystickHats() GetJoystickAxisState(), GetJoystickHatState(), GetJoystickButtonState()

GetNumJoysticks()¶

Determines how many joysticks are available

Description:

This gets the number of joysticks available on a system. It returns an integer, which if greater than you can open a joystick using the OpenJoystick() function..

See Also:

GetNumJoysticks(), OpenJoystick(), GetNumJoystickAxes() GetNumJoystickBalls(), GetNumJoystickButtons(), GetNumJoystickHats() GetJoystickAxisState(), GetJoystickHatState(), GetJoystickButtonState()

GetPEBLVersion()¶

Returns a string indicating which version of PEBL you are using

Description:

Returns a string describing which version of PEBL you are running.

Usage:

GetPEBLVersion()

Example:

Print(GetPEBLVersion())

See Also:

TimeStamp()

GetSystemType()¶

Identifies the type of operating system being used.

Description:

Returns a string identify what type of computer system you are using. It will return either: OSX, LINUX, or WINDOWS.

Usage:

GetSystemType()

Example:

## Put this at the beginning of an experiment,
## after a window gWin has been defined.
   if(GetSystemType() == "WINDOWS")
    {
      SignalFatalError("Experiment untested on windows")
    }

See Also:

SystemCall()

GetTextBoxCursorFromClick()¶

Description:

Returns the position (in characters) corresponding to a x,y click on a text box. The X,Y position must be relative to the x,y position of the box, not absolute. Once obtained, the cursor position can be set with SetCursorPosition().

Usage:

GetTextBoxCursorFromClick(<widget>,<x>,<y>)

GetTime()¶

Gets a number, in milliseconds, representing the time since the PEBL program began running.

Description:

Gets time, in milliseconds, from when PEBL was initialized. Do not use as a seed for the RNG, because it will tend to be about the same on each run. Instead, use RandomizeTimer().

Usage:

GetTime()

Example:

a <- GetTime()
WaitForKeyDown("A")
b <- GetTime()
Print("Response time is: " + (b - a))

See Also:

TimeStamp()

GetTimeOfDay()¶

Returns the current time in seconds since Unix epoch

Description:

Returns the current time of day in seconds since the Unix epoch (January 1, 1970). This provides an absolute timestamp useful for logging when events occurred in real-world time.

Usage:

GetTimeOfDay()

Example:

timestamp <- GetTimeOfDay()
Print("Current Unix timestamp: " + timestamp)

See Also:

GetTime(), TimeStamp()

GetVideoModes()¶

Gets list of available screen resolutions

Description:

Gets a list of useable video modes (in width/height pixel pairs), as supplied by the video driver, for a specified screen. Screen is specified as an integer, with 0 being the default screen. If no screen is specified, screen 0 is used.

Usage:

modes <- GetVideoModes()

Example:

Print(GetVideoModes)
##Might return:
[[1440, 900]
, [1360, 768]
, [1152, 864]
, [1024, 768]
, [960, 600]
, [960, 540]
, [840, 525]
, [832, 624]
, [800, 600]
, [800, 512]
, [720, 450]
, [720, 400]
, [700, 525]
]

See Also:

GetCurrentScreenResolution(), gVideoWidth(), gVideoHeight(), GetDrivers()

GetWorkingDirectory()¶

Returns the current working directory

Description:

Returns the current working directory path. This is the directory from which PEBL is currently executing and where relative file paths are resolved.

Usage:

GetWorkingDirectory()

Example:

cwd <- GetWorkingDirectory()
Print("Current directory: " + cwd)

IsAnyKeyDown()¶

Determines whether any key is down.

Description:

IsAnyKeyDown()

Usage:

IsAnyKeyDown()

IsAudioOut()¶

Description:

Tests whether <variant> is a AudioOut stream.

Usage:

IsAudioOut(<variant>)

Example:

if(IsAudioOut(x))
{
 Play(x)
}

IsCanvas()¶

Description:

Tests whether <variant> is a Canvas widget.

Usage:

IsCanvas(<variant>)

Example:

if(IsCanvas(x)
{
   SetPixel(x,10,10,MakeColor("red"))
}

IsColor()¶

Description:

Tests whether <variant> is a Color.

Usage:

IsColor(<variant>)

Example:

if(IsColor(x)
{
 gWin <- MakeWindow(x)
}

IsCustomObject()¶

Tests whether object is a custom object.

Description:

Tests whether <variant> is a Custom object (created with MakeCustomObject.) Return 1 if so, 0 if not.

Usage:

IsCustomObject(<obj>)

Example:

if(IsCustomObject(obj)
{
   MoveObject(obj,x,y)
} else {
   Move(obj,x,y)
}

IsDirectory()¶

Checks whether a file is a directory

Description:

Determines whether a named path is a directory. Returns 1 if it exists and is a directory, and 0 otherwise.

Usage:

IsDirectory(<path>)

Example:

filename <- "data-"+gSubNum+".csv"
 exists <-  FileExists(filename)
  if(exists)
   {
    out <-    IsDirectory(filename)
    Print(out)
   }

IsFileStream()¶

Description:

Tests whether <variant> is a FileStream object.

Usage:

IsFileStream(<variant>)

Example:

if(IsFileStream(x))
{
 Print(FileReadWord(x)
}

IsFloat()¶

Description:

Tests whether <variant> is a floating-point value. Note that floating-point can represent integers with great precision, so that a number appearing as an integer can still be a float.

Usage:

IsFloat(<variant>)

Example:

x <- 44
y <- 23.5
z <- 6.5
test <- x + y + z

IsFloat(x)           # false
IsFloat(y)           # true
IsFloat(z)           # true
IsFloat(test)        # true

IsFont()¶

Description:

Tests whether <variant> is a Font object.

Usage:

IsFont(<variant>)

Example:

if(IsFont(x))
{
 y <- MakeLabel("stimulus", x)
}

IsImage()¶

Description:

Tests whether <variant> is an Image.

Usage:

IsImage(<variant>)

Example:

if(IsImage(x))
{
 AddObject(gWin, x)
}

IsInteger()¶

Description:

Tests whether <variant> is an integer type. Note: a number represented internally as a floating-point type whose is an integer will return false. Floating-point numbers can be converted to internally- represented integers with the ToInteger() or Round() commands.

Usage:

IsInteger(<variant>)

Example:

x <- 44
y <- 23.5
z <- 6.5
test <- x + y + z

IsInteger(x)         # true
IsInteger(y)         # false
IsInteger(z)         # false
IsInteger(test)              # false

IsKeyDown()¶

Description:

See Also:

IsKeyUp()

IsKeyUp()¶

Description:

See Also:

IsKeyDown()

IsLabel()¶

Description:

Tests whether <variant> is a text Label object.

Usage:

IsLabel(<variant>)

Example:

if(IsLabel(x)
{
 text <- GetText(x)
}

IsList()¶

Description:

Tests whether <variant> is a PEBL list.

Usage:

IsList(<variant>)

Example:

if(IsList(x))
{
 loop(item, x)
 {
  Print(item)
 }
}

IsNumber()¶

Description:

Tests whether <variant> is a number, either a floating-point or an integer.

Usage:

IsNumber(<variant>)

Example:

if(IsNumber(x))
{
 Print(Sequence(x, x+10, 1))
}

IsShape()¶

Description:

Tests whether <variant> is a drawable shape, such as a circle, square rectangle, line, bezier curve, or polygon.

Usage:

IsShape(<variant>)

Example:

if(IsShape(x))
{
  Move(x,300,300)
}

IsString()¶

Description:

Tests whether <variant> is a text string.

Usage:

IsString(<variant>)

Example:

if(IsString(x))
{
 tb <- MakeTextBox(x, 100, 100)
}

IsText()¶

Description:

Tests whether <variant> is a text string. Same as IsString().

Usage:

IsString(<variant>)

Example:

if(IsText(x))
{
 tb <- MakeTextBox(x, 100, 100)
}

IsTextBox()¶

Description:

Tests whether <variant> is a TextBox Object

Usage:

IsTextBox(<variant>)

Example:

if(IsTextBox(x))
{
 Print(GetText(x))
}

IsWidget()¶

Description:

Tests whether <variant> is any kind of a widget object (image, label, or textbox).

Usage:

IsWidget(<variant>)

Example:

if(IsWidget(x))
{
 Move(x, 200,300)
}

IsWindow()¶

Description:

Tests whether <variant> is a window.

Usage:

IsWindow(<variant>)

Example:

if(IsWindow(x))
{
  AddObject(y,x)
}

LaunchFile()¶

Launches a file using platform-specific handlers

Description:

Launch a specified file or URI with a platform-specific handler.

Usage:

LaunchFile("filename")

See Also:

SystemCall()

MakeDirectory()¶

Creates a directory in path

Description:

Creates a directory with a particular name. It will have no effect of the directory already exists.

Usage:

FileExists(<path>)

Example:

#create data subdirectory + subject-specific directory
 MakeDirectory("data")
 MakeDirectory("data/"+gsubnum)
 filename <- "data/"+gsubnum+"/output.csv"

OpenJoystick()¶

Gets a joystick object

Description:

This opens an available joystick, as specified by its index. The returned object can then be used in to access the state of the joystick. It takes an integer argument, and for the most part, if you have a single joystick attached to your system, you will use OpenJoystick(1). If you want to use a second joystick, use OpenJoystick(2), and so on.

See Also:

GetNumJoysticks(), OpenJoystick(), GetNumJoystickAxes() GetNumJoystickBalls(), GetNumJoystickButtons(), GetNumJoystickHats() GetJoystickAxisState(), GetJoystickHatState(), GetJoystickButtonState()

PlayMovie()¶

*(CURRENTLY NOT WORKING)* Plays a movie until its end

Description:

Plays the movie (or other multimedia file) loaded via either the LoadMovie or LoadAudioFile function. Note that this functionality uses a different underlying system than the sound playing functions PlayBackground and PlayForeground, and they are not interchangeable.

Usage:

PlayMovie(movie)

Example:

movie <- LoadMovie("movie.avi",gWin,640,480)
   PrintProperties(movie)
   Move(movie,20,20)
   movie.volume <- .1
   status <- EasyLabel("Demo Movie Player",300,25,gWin,22)
   Draw()
   PlayMovie(movie)

RegisterEvent()¶

Registers events to trigger based on particular conditions

Description:

Adds an event to the event loop. This function is currently experimental, and its usage may change in future versions of PEBL.

Usage:

## shows a way to generate custom WaitForMouseButton
RegisterEvent("<MOUSE_BUTTON_PRESS>",1,1,"<EQUAL>","", [])
out <-   StartEventLoop()
ClearEventLoop()

See Also:

ClearEventLoop(), StartEventLoop()

SetMouseCursorPosition()¶

Description:

Sets the current x,y coordinates of the mouse pointer, ‘warping’ the mouse to that location immediately

Usage:

SetMouseCursorPosition(<x>,<y>)

Example:

##Set mouse to center of screen:
  SetMouseCursorPosition(gVideoWidth/2,
                         gVideoHeight/2)

SetWorkingDirectory()¶

Changes the current working directory

Description:

Changes the current working directory to the specified path. This affects how relative file paths are resolved in subsequent file operations.

Usage:

SetWorkingDirectory(<path>)

Example:

SetWorkingDirectory("./data")
Print(GetWorkingDirectory())  ##Shows new directory

##Now relative paths work from ./data
file <- FileOpenRead("output.csv")

ShowCursor()¶

Hides or show mouse cursor.

Description:

Hides or shows the mouse cursor. Currently, the mouse is not used, but on some systems in some configurations, the mouse cursor shows up. Calling ShowCursor(0) will turn off the cursor, and ShowCursor(1) will turn it back on. Be sure to turn it on at the end of the experiment, or you may actually lose the cursor for good.

Usage:

ShowCursor(<value>)

Example:

window <- MakeWindow()
ShowCursor(0)
## Do experiment here
##

## Turn mouse back on.
ShowCursor(1)

SignalFatalError()¶

Halts execution, printing out message

Description:

Stops PEBL and prints <message> to stderr. In addition, when possible, it will pop-up a window with the error message. Useful for type-checking in user-defined functions. If you want to end an experiment directly, use ExitQuietly instead.

Usage:

SignalFatalError(<message>)

Example:

If(not IsList(x))
{
 SignalFatalError("Tried to frobnicate a List.")
}
##Prints out error message and
##line/filename of function

See Also:

Print(), ExitQuietly()

StartEventLoop()¶

Starts the event loop

Description:

Starts the event loop with currently-registered events. This function is currently experimental, and its usage may change in future versions of PEBL.

Usage:

## shows a way to generate custom WaitForMouseButton
RegisterEvent("<MOUSE_BUTTON_PRESS>",1,1,"<EQUAL>","", [])
out <-   StartEventLoop()
ClearEventLoop()

See Also:

RegisterEvent(), ClearEventLoop()

SystemCall()¶

Executes command in operating system

Description:

Calls/runs another operating system command. Can also be used to launch another PEBL program. Useful to check GetSystemType() before running. Note that the output of a command-line argument is generally not passed back into PEBL; just the function’s return code, which is usually 0 on success or some other number on failure (depending upon the type of failure). Some uses might include:

Usage:

SystemCall("text-of-command")
SystemCall("text-of-command","command-line-options")

Example:

if(GetSystemType() == "WINDOWS")
     {
       x <- SystemCall("dir input.txt")
     } else {
       x <- SystemCall("ls input.txt")
     }
      if(x <> 0)
      {
         SignalFatalError("Expected file ["+
               "input.txt] does not exist")
      }

See Also:

GetSystemType()

SystemCallUpdate()¶

Executes an OS command with real-time output updates

Description:

Calls an operating system command similar to SystemCall(), but with support for receiving output updates during execution. This is useful for long-running commands where you want to see progress.

Usage:

SystemCallUpdate(<command>)
SystemCallUpdate(<command>, <arguments>)

Example:

##Run a command with arguments
result <- SystemCallUpdate("ls", "-la")

See Also:

SystemCall(), GetSystemType()

TimeStamp()¶

Returns a string containing the current date and time

Description:

Returns a string containing the date-and-time, formatted according to local conventions. Should be used for documenting the time-of-day and date an experiment was run, but not for keeping track of timing accuracy. For that, use GetTime().

Usage:

TimeStamp()

Example:

a <- TimeStamp()
Print(a)

See Also:

GetTime()

TranslateKeyCode()¶

Converts a keycode to a key name

Description:

Translates a code corresponding to a keyboard key into a keyboard value. This code is returned by some event/device polling functions.

TranslateString()¶

Converts a key name string to its keycode

Description:

Translates a string representation of a key (like “a”, “space”, “return”) into its corresponding internal keycode value. This is useful for programmatically working with keyboard input.

Usage:

TranslateString(<key_string>)

Example:

keycode <- TranslateString("a")
spaceCode <- TranslateString("space")
enterCode <- TranslateString("return")

VariableExists()¶

Description:

Tests whether a variable exists.

Usage:

Uppercase("variablename")

Example:

if(not VariableExists("underwear"))
     {
       underwear <- "Under there"
     }

See Also:

PropertyExists()

Wait()¶

Description:

Waits the specified number of milliseconds, then returns.

Usage:

Wait(<time>)

Example:

Wait(100)
Wait(15)

WaitForAllKeysUp()¶

Waits until all keys are in up state

Description:

Wait until all keyboard keys are in the up position. This includes numlock, capslock, etc.

WaitForKeyDown()¶

Waits until a specific key is in the down state

Description:

Waits for a specific key to be detected in the down position. Unlike WaitForKeyPress(), this tests the state of the key rather than waiting for a keypress event. Will return immediately if the key is already down when called.

Usage:

WaitForKeyDown(<key>)

Example:

WaitForKeyDown("a")
Print("The 'a' key is now down")

WaitForAnyKeyDown()¶

Waits until any key is detected in down state

Description:

Waits for any key to be detected in the down position. This includes numlock, capslock, etc, which can be locked in the down position even if they are not being held down. Will return immediately if a key is being held down before the function is called.

See Also:

WaitForAnyKeyPress()

WaitForAnyKeyDownWithTimeout()¶

Description:

Waits until any key is detected in the down position, but will return after a specified number of milliseconds. This tests for the key position on each cycle; users should prefer using WaitForAnyKeyPressWithTimout() which waits for the keypress event.

Usage:

WaitForAnyKeyDownWithTimeout(<time>)

See Also:

WaitForAnyKeyPressWithTimeout(), WaitListKeyPressWithTimeout(), WaitForAnyKeyPress(), WaitListKeyPress()

WaitForAnyKeyPress()¶

Waits until any key is pressed

Description:

Waits until any key is pressed, and returns the key pressed. This waits for the keyboard event, which is typically more reliable and less computationally taxing than waiting for the keyboard state (which updates based on those events anyway).

Usage:

WaitForKeyPress(<time>)

Example:

cont <- 1
        while(cont)
         {
         key <- WaitForAnyKEyPress()
         if(key == "x")
          {
              cont <- 0
          }
         }

See Also:

WaitForAnyKeyPressWithTimeout(), WaitListKeyPressWithTimeout(), WaitListKeyPress()

WaitForAnyKeyPressWithTimeout()¶

Description:

Waits until any key is detected in the down position, but will return after a specified number of milliseconds. This tests for the key position on each cycle; users should prefer using WaitForAnyKeyPressWithTimout() which waits for the keypress event.

Usage:

WaitForAnyKeyDownWithTimeout(<time>)

See Also:

WaitForAnyKeyPressWithTimeout(), WaitListKeyPressWithTimeout()

WaitForKeyListDown()¶

Waits until one of the keys is in down state

Description:

Returns when any one of the keys specified in the argument is down. If a key is down when called, it will return immediately.

Usage:

WaitForKeyListDown(<list-of-keys>)

Example:

WaitForKeyListDown(["a","z"])

WaitForKeyPress()¶

Description:

Waits for a keypress event that matches the specified key. Usage of this function is preferred over WaitForKeyDown(), which tests the state of the key. Returns the value of the key pressed.

Usage:

WaitForKeyPress(<key>)

WaitForKeyUp()¶

Description:

WaitForKeyRelease()¶

Waits until a specific key is released

Description:

Waits for a specific key to be released (transition from down to up state). This is useful for ensuring a key has been released before continuing, preventing accidental repeated inputs.

Usage:

WaitForKeyRelease(<key>)

Example:

WaitForKeyPress("space")
Print("Space pressed")
WaitForKeyRelease("space")
Print("Space released")

WaitForListKeyPress()¶

Description:

Returns when any one of the keys specified in the argument is pressed. Will only return on a new keyboard event, and so a previously pressed key will not trip this function, unlike WaitForKeyListDown() Returns a string indicating the value of the keypress.

Usage:

WaitForListKeyPress(<list-of-keys>)

Example:

WaitForListKeyPress(["a","z"])

WaitForListKeyPressWithTimeout()¶

Description:

Returns when any one of the keys specified in the argument is pressed, or when the timeout has elapsed; whichever comes first. Will only return on a new keyboard/timeout events, and so a previously pressed key will not trip this function, unlike WaitForKeyListDown(). The optional <style> parameter is currently unused, but may be deployed in the future for differences in how or when things should be returned. Returns the value of the pressed key. If the function terminates by exceeding the <timeout>, it will return the string "<timeout>". Note: previous to 2.0, returned a list [“<timeout>”], which may mean updating logic for tests designed in the 0.x series.

Usage:

WaitForListKeyPressWithTimeout(<list-of-keys>,
                                <timeout>,opt:<style>)

Example:

x <- WaitForListKeyPressWithTimeout(["a","z"],
                                       2000)
  if(IsList(x))
  {
     Print("Did Not Respond.")
  }

See Also:

WaitForKeyListDown(), WaitForListKeyPress(), WaitForKeyPressWithTimeout()

WaitForMouseButton()¶

Waits until any of the mouse buttons is pressed or released, and returns message indicating what happened

Description:

Waits for a mouse click event to occur. This takes no arguments, and returns a 4-tuple list, indicating:

[xpos,   ypos,   button id [1-3],   "<pressed>" or "<released>"]

Usage:

WaitForMouseButton()

Example:

## Here is how to wait for a mouse down-click

 continue <- 1
 while(continue)
 {
     x <- WaitForMouseButton()
     if(Nth(x,4)=="<pressed>")
      {
          continue <- 0
      }
 }
 Print("Clicked")

WaitForMouseButtonWithTimeout()¶

Description:

Waits for a mouse click event to occur, or a timeout to be reached. This takes a single argument: timeout delay in ms. When clicked, it returns a 4-tuple list, indicating:

[xpos,  ypos,   button id [1-3],   "<pressed>" or "<released>"]

when not click and timeout is reached, it returns a list:    ``[timeout]``

Usage:

WaitForMouseButtonWithTimeOut(10)

Example:

## Here is how to wait for a mouse down-click

 continue <- 1
 while(continue)
 {
     x <- WaitForMouseButtonWithTimeout(500)
     if(First(x)=="<timeout>")
      {
         Print("time is "+GetTime())
          continue <- 1
      } else {
          continue <- 0
      }
 }
 Print("Clicked")