init()

Triggered by the application system immediately after an application launches. If an application does not implement init, the application will remain inactive after launch.

• init function ID = 1

kill()

Requests for the receiving application to terminate. The application should clean up any volatile resources.

• kill function ID = 2

listenTerm()

Causes the calling application to become an observer of the receiving terminal driver. When the terminal driver registers a typed key, it will invoke the termInput function of its observer. Each terminal driver may have at most one observer. If another application invokes listenTerm, it will become the new observer.

• listenTerm function ID = 3
• Throws missingErr if the calling application does not implement termInput.

termSize(
    s16 widthDest,
    s16 heightDest
)

Retrieves the dimensions of the terminal controlled by the receiving terminal driver. The dimensions are measured in number of characters.

• termSize function ID = 4
• widthDest = Destination for the width (signed 16-bit integer)
• heightDest = Destination for the height (signed 16-bit integer)

wrtTerm(
    s16 x,
    s16 y,
    s32 text
)

Displays text on the terminal of the receiving terminal driver. Text will wrap around to the next line after it reaches the end of the screen.

• wrtTerm function ID = 5
• x = Horizontal coordinate (signed 16-bit integer)
• y = Vertical coordinate (signed 16-bit integer)
• text = Text to write (pointer to array of signed 8-bit integers)

termInput(
    s8 key
)

Invoked by a terminal driver to notify the receiving observer when a key has been typed.

• termInput function ID = 6
• key = Typed key code (signed 8-bit integer)

Terminal key codes for visible characters have ASCII values. Other key codes include the following:

• Space = 32
• Tab = 9
• Newline = 10
• Backspace = 127
• Escape = 27
• Left = -1
• Right = -2
• Up = -3
• Down = -4
• Reverse tab = -5
• System menu = -6

startSerial(
    s8 port,
    s32 baudRate
)

Causes the receiving serial driver to open the given serial port, and assigns the calling application as an observer. When the port receives input data, the serial driver will will invoke the serialInput function on the port's observer.

• startSerial function ID = 7
• port = Serial port number (signed 8-bit integer)
• baudRate = Serial port baud rate (signed 32-bit integer)

stopSerial(
    s8 port
)

Causes the receiving serial driver to close the given serial port. The port will no longer send or receive data.

• stopSerial function ID = 8
• port = Serial port number (signed 8-bit integer)

wrtSerial(
    s8 port,
    s32 buff
)

Causes the receiving serial driver to output data over the given serial port.

• wrtSerial function ID = 9
• port = Serial port number (signed 8-bit integer)
• buff = Buffer to write (pointer)

serialInput(
    s8 port,
    s8 value
)

Invoked by a serial driver to notify the receiving observer when a serial byte has been ingested.

• serialInput function ID = 10
• port = Serial port number (signed 8-bit integer)
• value = Received serial data (signed 8-bit integer)

setGpioMode(
    s16 pin,
    s8 mode
)

Sets the I/O mode of the given GPIO pin.

• setGpioMode function ID = 11
• pin = GPIO pin number (signed 16-bit integer)
• mode = I/O mode (signed 8-bit integer)

Available I/O modes include the following:

• Digital read = 0
• Analog read = 1
• Digital write = 2
• Analog write = 3

readGpio(
    s32 dest,
    s16 pin
)

Reads a digital or analog value from the given GPIO pin.

• readGpio function ID = 12
• dest = Destination for the value (signed 32-bit integer)
• pin = GPIO pin number (signed 16-bit integer)

wrtGpio(
    s16 pin,
    s32 value
)

Writes a digital or analog value to the given GPIO pin.

• wrtGpio function ID = 13
• pin = GPIO pin number (signed 16-bit integer)
• value = Value to write (signed 32-bit integer)

newWindow(
    s32 dest,
    s32 title
)

Creates a new window which allows interaction with the user. All WheatShell implementations can display text in windows, while graphics are only supported on certain platforms. The caller of newWindow is considered to be the owner of the window. If title is null, the title of the window will be the file name of the caller. If the user presses a key while the window is focused, the shell will call windowKeyPressed on the window owner. If the window changes focus, the shell will call windowFocusChanged on the window owner. If the user requests to close the window, the shell will call reqDelWindow on the window owner.

• newWindow function ID = 14
• dest = Destination for the new window handle (pointer)
• title = Title for the window (pointer to array of signed 8-bit integers)

reqDelWindow(
    s32 window
)

Invoked by the shell to notify the receiving window owner when the user has requested to close the given window. If the window owner does not implement reqDelWindow, the shell will delete the window immediately.

• reqDelWindow function ID = 15
• window = Window handle (pointer)

delWindow(
    s32 window
)

Deletes the given window.

• delWindow function ID = 16
• window = Window handle (pointer)

displayWindowMessage(
    s8 dest,
    s32 window,
    s32 message
)

Displays a message in the given window, and waits for the user to dismiss the message. If the message is too long to fit in the window, the user can scroll up and down to view the whole message. dest will be set to 1 if the user pressed the escape key, and 0 for all other keys.

• displayWindowMessage function ID = 17
• dest = Destination for whether escape key was pressed (signed 8-bit integer)
• window = Window handle (pointer)
• message = Message to display (pointer to array of signed 8-bit integers)

promptWindowOption(
    s16 dest,
    s32 window,
    s32 message,
    s32 options
)

Displays a list of options in the given window, and waits for the user to select an option. If message is null, then no message will be displayed above the options. If the user presses the escape key, dest will be set to -1.

• promptWindowOption function ID = 18
• dest = Destination for index of selected option (signed 16-bit integer)
• window = Window handle (pointer)
• message = Message to display above options (pointer to array of signed 8-bit integers)
• options = List of strings for the options (pointer to array of pointers to array of signed 8-bit integers)

promptWindowText(
    s32 dest,
    s32 window,
    s32 message,
    s32 startText
)

Prompts the user to enter a line of text in the given window. Newlines are not supported in the text entry. If message is null, then no message will be displayed above the text entry. If startText is null, then the initial contents of the text entry will be empty. If the user presses the escape key, dest will be set to null.

• promptWindowText function ID = 19
• dest = Destination for the typed text (pointer to array of signed 8-bit integers)
• window = Window handle (pointer)
• message = Message to display above text entry (pointer to array of signed 8-bit integers)
• startText = Initial contents of text entry (pointer to array of signed 8-bit integers)

clrWindow(
    s32 window
)

Erases any text or graphics which are displayed in the given window.

• clrWindow function ID = 20
• window = Window handle (pointer)

windowTermSize(
    s16 widthDest,
    s16 heightDest,
    s32 window
)

Retrieves the width and height of the given window.

• windowTermSize function ID = 21
• widthDest = Destination for the width (signed 16-bit integer)
• heightDest = Destination for the height (signed 16-bit integer)
• window = Window handle (pointer)

readWindowTerm(
    s32 dest,
    s32 window,
    s16 x,
    s16 y,
    s32 length
)

Reads text which has been drawn using wrtWindowTerm in the given window. The character position to read will wrap around to the next line after it reaches the end of the window.

• readWindowTerm function ID = 22
• dest = Destination for the text (pointer to array of signed 8-bit integers)
• window = Window handle (pointer)
• x = Horizontal coordinate (signed 16-bit integer)
• y = Vertical coordinate (signed 16-bit integer)
• length = Length of text to read (signed 32-bit integer)

wrtWindowTerm(
    s32 window,
    s16 x,
    s16 y,
    s32 text
)

Displays text in the given window. Text will wrap around to the next line after it reaches the end of the window.

• wrtWindowTerm function ID = 23
• window = Window handle (pointer)
• x = Horizontal coordinate (signed 16-bit integer)
• y = Vertical coordinate (signed 16-bit integer)
• text = Text to write (pointer to array of signed 8-bit integers)

windowKeyPressed(
    s32 window,
    s8 key
)

Invoked by the shell to notify the receiving window owner when the user has pressed a key. This function uses the same key codes as the function termInput. The system menu key will not be passed through windowKeyPressed, and is instead used to display a menu in the shell. Note that the shell will not call windowKeyPressed while displayWindowMessage, promptWindowOption, or promptWindowText are running.

• windowKeyPressed function ID = 24
• window = Window handle (pointer)
• key = Typed key code (signed 8-bit integer)

windowFocusChanged(
    s32 window,
    s8 hasFocus
)

Invoked by the shell to notify the receiving window owner when the window has changed focus. A focused window is visible to the user and registers key presses.

• windowFocusChanged function ID = 25
• window = Window handle (pointer)
• hasFocus = Whether the window has focus (signed 8-bit integer)