GUI Scripting: Number Wheel Example

From The DarkMod Wiki
Jump to navigationJump to search

This page is part of a series. See GUI Scripting Language for overview.


TDM number wheels are used for combination locks. A typical lock has 3 wheels, each with edge digits 0 to 9. The gamer frobs a particular wheel to indicate interest in it, then uses mouse actions or keystrokes to rotate it.

This example focuses on just these aspects:

  • An overlay is created to catch standard events bound to keystrokes, now re-interpreted as number-wheel rotation requests.
  • Specifically, the overlay catches them in GUI onNamedEvent handlers, and reports them to the script object as GUI:: parameters.
  • The script object is spinning in an "eachFrame" loop, looking for changes in those GUi:: parameters.

Script Object Setup

In tdm_numberwheel.script, a "numberwheel" script object is defined. Its main function body is called (via Stim/Response) when frobbed. In the function body, a custom overlay is first created (about which see GUI Scripting: Handles, which includes numberwheel among its examples). Then the code enters an "eachFrame" loop to do processing, where it remains until the gamer frobs something else.

GUI Code

The overlay (instantiated from "guis/numberwheel_handler.gui" and shown next) catches the events raised by the standard player actions to go to previous or next thing (i.e., weapon, inventory item, or inventory group). It then uses those events to (also) ask the script object to manipulate the number wheel. Note that this overlay has no visual aspect:

windowDef Desktop {
  rect      0, 0, 640, 480
  nocursor 1

  onNamedEvent prevWeapon {
    set "gui::nextPos" "1";

  onNamedEvent nextWeapon {
    set "gui::prevPos" "1";

  onNamedEvent inventoryPrevItem {
    set "gui::nextPos" "1";

  onNamedEvent inventoryNextItem {
    set "gui::prevPos" "1";

  onNamedEvent inventoryPrevGroup {
    set "gui::nextPos" "1";

  onNamedEvent inventoryNextGroup {
    set "gui::prevPos" "1";

Script Object Polling of GUI:: Parameters

Clearly, "prevPos" and "nextPos" are booleans, set to 1 when the user makes a request to go to the previous or next position on the number wheel. The .script then manages what digit is shown on the wheel. For gui:: parameters, the salient portions in the script are:

Did we get a request?

float prevPos = $player1.getGuiFloat(overlayHandle,"prevPos");
float nextPos = $player1.getGuiFloat(overlayHandle,"nextPos");

If so, process it and rotate the wheel (code not shown), then reset and wait for next request:


(There is a separate script that combines the values of each number wheel to determine if the lock should open. This is beyond the scope here.)

For More

The zoom level of the spyglass can be adjusted with the Previous and Next keys. To do so, in playertools\spyglass.gui, the same named events are caught.