User Interface

There are some commands to interact with the user interface of PCC. Their syntax and semantics are a bit different from what you may be used to, so here's an explanation.

When a user interface command returns a value, it does so in a variable `UI.Result'. You can locally redefine that variable to have the value returned in the local variable, otherwise the result will go to the shared variable defined in `core.q'. This means, the variable may -- like all shared variables -- change when your script suspends.

An example of this principle:

  UI.Message "Choose a color:", "Question", "Red Green Blue"
  If UI.Result=1 Then Print "You chose red"

The following, however, will most likely fail:

  UI.Message "Choose a color:", "Question", "Red Green Blue"
  WaitOneTurn
  IF UI.Result=1 Then Print "Last turn, you chose red"

To make it work, define a static or local variable (which will be private to your script and be preserved when the script suspends), or copy the value of `UI.Result' to a static/local variable before suspending:

  Dim Local answer
  UI.Message "Choose a color:", "Question", "Red Green Blue"
  answer := UI.Result
  WaitOneTurn
  IF answer=1 Then Print "Last turn, you chose red"

Some dialogs are more complex than a simple command. For these, we use magic `With' statements.

  With Listbox("Title") Do
    % prepare the list box
    % run the list box
  EndWith

The `With' statement provides a natural lifetime control for the dialog, and allows you to write functions to prepare the dialog, while not needing a new variable type for dialogs.

You can not suspend (`Stop' & friends) while such a statement is active.

Internally, PCC passes around numeric command codes every time you hit a key, click a button, etc. When you bind a key to a command, PCC has to associate such a code with that textual command. Generally, you do not need to worry about this, but knowing about it might turn out to be helpful.

This mapping is done by the so-called `atom table'. This table can be explicitly accessed using the `Atom(str)' and `AtomStr(n)' functions. In addition, all keymap manipulation commands access it. `Atom' generates a unique new Id (an atom) in the range 10000 to 29999 for the specified string (usually a script command); if called again with the same string, it returns the same number. `AtomStr' does the reverse mapping.

Atoms do not survive PCC exit and re-load, that is, if you call `Atom' in the next session with the same string, you might get a different code. Since PCC 1.1.6, atoms attached to drawings (see `NewCircle' and friends) will survive. That is, a marker having `Atom("foo")' attached, will still have `Atom("foo")', although the actual numeric value might differ.

PCC tries hard to automatically update the screen for all changes you make to the game data using script commands. This does not always work out correctly. For example, renaming a ship may affect the control screen of a ship that intercepts it, because its mission now has changed implicitly from `Intercept oldname' to `Intercept newname'.

PCC does not recognize such all interdependencies (though we're getting better). To update the screen explicitly, hit [Ctrl-G] or call `UI.Update 1'.

You can change certain values from the specification files (for example, the picture number associated with a hull). These never cause a screen update, and even [Ctrl-G] might not suffice to update the screen; you should only change them from a place like `gameinit.q' or `autoexec.q'. Hence, most of them are marked "only for people who know what they're doing".

One problem of processes that (sort-of) run in parallel is that of synchronisation. When one process is trying to move a ship elsewhere (using `MoveTo', maybe), other processes (and the PCC user!) still can change the ship's waypoint. In order to prevent this, PCC 1.1.2 introduces locks.

• Only one process can have a certain lock at a time. While one process is doing a `With Lock("s1.waypoint")', no other process can execute such a block until the first process leaves this block;
• PCC's user interface will honor certain locks (see below). This is the main raison d'etre for locks;
• Locking is based on cooperation. You cannot prevent anyone from changing the waypoint (after all, the user might just stop PCC, and use another client to do the change she wants). Because this is the case, PCC's user interface will allow the user to override the lock.

PCC honors the following locks ("pNNN"/"sNNN" is the object Id, e.g. "s7" for ship #7):