User Interface

API for displaying a user interface can be found in the Scripting Reference.

The user interface is what is called "immediate mode" rather than "retained mode". This means that in order to present a consistent user interface to the user, you need to wrap a bunch of controls in a loop:

while not done do
  -- Code to print text to the screen and provide controls the
  -- user can interact with
  lsDoFrame();
  -- Code to act based on button clicks, etc. and set done if necessary.
  lsSleep(tick_delay);
  checkBreak();
end

lsDoFrame() actually displays content in the VT window while adding a short sleep prevents the loop from consuming too many system resources. The code to actually implement user actions should be after the lsDoFrame() because if not, there will be graphical glitches if the action tries to update the VT screen. Jimbly: Though it is true that you can get some graphical glitches if you're responding to things immediately, delaying the actions based on button clicks until the end of the loop a) adds some actual delay time, and b) loses a lot of the simplicity and readability of an immediate-mode user interface.

checkBreak() will exit the program if the user is pressing both shift and control. In any indefinite loop you make, this should be included to allow the user to abort your macro without waiting.

Two library functions are provided to help in the common cases of providing a user interface.

statusScreen() allows you to post a status message to the user while providing an explicit button allowing the user to quit the script. You can use this periodically in long-running tasks to make sure that the user knows what is going on and can abort the script at any time.

sleepWithStatus() allows you to pause for long periods of time while giving feedback to the user and allowing them to abort the script in the middle.