# Module `button` - A Button library that uses OpenGL and SDL to render a window of clickable/configurable buttons

A Button library that uses OpenGL and SDL to render a window of clickable/configurable buttons. To use this library:

    #INCLUDE "button.module"

#### Maintainer:

Damian Dimmich <djd20@kent.ac.uk>

## Index

- Protocol `BUTTONCFG` - This is used for button setup
  - Tag `colour` - set the button color by specifying Red, Blue and Green values
  - Tag `disable` - disable button
  - Tag `enable` - enable button
  - Tag `name` - Change the name of the button
- Protocol `CLICK` - Sends a copy of the name of the button (when clicked)
- Process `makeRasterFont` - This initialises the font included and must be called before any of the other PROC's can be used
- Process `printString` - Print a string in an OpenGL context
- Process `printStringi` - Print a string of a given length in an OpenGL context
- Process `setup.button.window` - Sets up and configures the button network

## Declarations

### `font2.occ`:14Process `makeRasterFont`

`PROC makeRasterFont(RESULT INT fontOffset)`

This initialises the font included and must be called before any of the other PROC's can be used.

#### Parameters:

`RESULT INT` | `fontOffset` | will contain a value that is needed when calling the other PROC's. It should be passed uninitialised.

### `font2.occ`:35Process `printString`

`PROC printString(VAL []BYTE s, VAL INT fontOffset)`

Print a string in an OpenGL context. Once makeRasterFont has run, you can use this to print strings in an OpenGL context. Generally you will want to set the location you want to render the font by making a call to glRasterPos2i or similar.

#### Parameters:

`VAL []BYTE` | `s` | the string you want to render
`VAL INT` | `fontOffset` | the value that you recieved from calling makeRasterFont

### `font2.occ`:56Process `printStringi`

`PROC printStringi(VAL []BYTE s, VAL INT fontOffset, VAL INT length)`

Print a string of a given length in an OpenGL context. Once makeRasterFont has run, you can use this to print strings in an OpenGL context. This PROC is like printString but it allows you to choose how many characters in a string you want to print. Generally you will want to set the location you want to render the font by making a call to glRasterPos2i or similar.

#### Parameters:

`VAL []BYTE` | `s` | the string you want to render
`VAL INT` | `fontOffset` | the value that you recieved from calling makeRasterFont
`VAL INT` | `length` | the number of characters you want to print

### `button.occ`:314Process `setup.button.window`

`PROC setup.button.window([][]CHAN CLICK click!, [][]CHAN BUTTONCFG configure?, CHAN BYTE scr!, CHAN BYTE cntrl.quit!, VAL INT size.x, size.y)`

Sets up and configures the button network. This is the only proc that should be run in this library by a user.

#### Parameters:

`[][]CHAN CLICK` | `click` | this is the click notification channel. Buttons send down these channels when they are clicked.
`[][]CHAN BUTTONCFG` | `configure` | these are the button configuration channels - they can be used for changing channel color, text, etc..
`CHAN BYTE` | `scr` | generally one would pass the error (err) channel as a parameter here so that the library can notify the user in case graphics initialisation goes wrong.
`CHAN BYTE` | `cntrl.quit` | this channel should be checked as it carries quit signals (like when someone closes the application window)
`VAL INT` | `size.x` | the window size in the X direction (nr of pixels)
`VAL INT` | `size.y` | the window size in the Y direction (nr of pixels) to the program. This allows a clean shutdown of the network.

### `button.inc`:34Protocol `CLICK`

`PROTOCOL CLICK IS MOBILE []BYTE:`

Sends a copy of the name of the button (when clicked).

### `button.inc`:37Protocol `BUTTONCFG`

`PROTOCOL BUTTONCFG`

This is used for button setup.

### `button.inc`:39Tag `enable`

`enable`

enable button

### `button.inc`:40Tag `disable`

`disable`

disable button

### `button.inc`:41Tag `name`

`name; MOBILE []BYTE`

Change the name of the button

### `button.inc`:42Tag `colour`

`colour; REAL32; REAL32; REAL32`

set the button color by specifying Red, Blue and Green values