Manual

STALLioN Manual

Setting up a display

Before you can start writing to the screen you need to include the necessary
header file, iolib.h, and create a variable of type iodisplay. This type is
declared in the header file "o.h", and acts as as a container for all of the
information required to create a display and write to it.
Before using the newly created display it must be initialised using the
ioinitdisplay function, declared in the header file "oinitdisplay.h". Its
declaration is as follows:

int ioinitdisplay(int foreCol, int backCol, int visible, int period,
                  int bufferLength, int bufferWidth, iodisplay *display)

The first two parameters are the default foreground and background colours used
for the text in the display. See reference for a list of possible colours.
The third and fourth parameters deal with the cursor, the first of which
controlling whether it is visible or not, and the second controlling how often
it will be flashed. This is not measured in a unit of time, but rather in the
number of flushes required before the cursor is shown and then hidden. So, if
you flush the screen 10 times every second, and set the period to 5, then the
cursor will be flashed on and off every second, or, to put it another way, its
state will be toggled twice every second.
The fifth parameter is the vertical length of the display, measured in lines.
For reference, in a traditional console this would be set to 25. The sixth is
the horizontal width of the display, measured in characters. A traditional
display would have this set to 80. These widths control both the size of the
console window and the amount of space available to place characters. This means
that there is no scroll bar; scrolling is instead controlled by a function.
The last parameter is a pointer to the display that you are initialising, and is
the variable which the function changes.

Setting the current display

Once a display has been created it needs to be set to be the current display.
Every output operation will then execute solely for that display. To do this,
simply dereference the display and assign that to the variable ioCurrentDisplay.

Outputting characters

Once the display has been initialised you can start to output text. Text output
in STALLioN works by sending information for each character into a buffer and
then flushing that buffer to the screen. If the buffer is not flushed, then no
text will be shown.
Basic output is controlled by the ioputch function, which is as follows:

int ioputch(char ch)

The first parameter is the character to be outputted. Calling the function puts
the character into the buffer at the current cursor location, and sets the
foreground and background colours for that character to the defaults. If you
wish to define the colours, then use the following function:

int ioputchattrib(char ch, int foreCol, int backCol)

Simply pass the chosen colours as the second and third parameters.
Note that these functions advance the cursor position just like the standard C
library equivalent, putc.

Flushing to the screen

Before any text can be seen the buffer must be flushed to the screen. This is
as simple as calling the following function:

ioflush()

This function will output the contents of the current buffer to the screen.
Note that flushing the buffer will only output the characters which have changed
since the last flush; calling ioflush twice in a row with no output functions
inbetween will take up very little CPU time, as nothing will actually happen.
Changing every single character in the buffer and then flushing however, will
take a lot longer. (Although hopefully not enough to be noticeable!)
When flushing the display the number of flushes since the last cursor flash is
recorded, and if it is equal to the cursor period then the cursor will be
displayed. If it is equal to double the cursor period then the counter is reset
and the cursor is hidden again.

Outputting variables

There are several functions included in STALLioN which allow you to output
variables into the buffer, as if they were characters. The basic ones are as
follows:

int ioputint(int val)

int ioputfloat(float val)

As their names and parameters imply, they are used for outputting integers and
floats respectively. They function identically to ioputch, in that they begin
outputting at the cursor position and advance the cursor position when finished.
If non-default colours are required then the following alternatives can be used:

ioputintattrib(int val, int foreCol, int backCol)

ioputfloatattrib(float val, int foreCol, int backCol)

These too are identical in function to ioputchattrib, but use integers and
floats as input instead.

Outputting strings

The most low-level way of writing strings using STALLioN would be to create a
loop that cycles through every character of a string and outputs it using
ioputch. The preferred way however, is to use STALLioN's equivalent of printf,
ioprintf. It's function is identical to the printf included in "stdio.h".

int ioprintf(char *str, ...)

Use it just as you would the standard printf function.
Like the other output functions STALLioN includes a separate function for
on-the-fly colours, namely ioprintfattrib. It is as follows:

int ioprintfattrib(char *str, int foreCol, int backCol, ...)

By now this should need no extra explanation.

The cursor

The cursor appearance is determined by several controllable attributes; the
colour it turns the character it is on, the colour it turns the background of
the character it is on, how often it flashes and whether it is visible or not.
Two of these; its visibilty and how often it flashes, are set by the user when
the display is intialised, using the parameters 'visible' and 'period'. The
colour of the cursor is defaulted to a black character on a white background.
If you wish to change these values after initialisation, then the function
below should be used:

int iosetcursorattib(int visible, int period, int foreCol, int backCol)

It functions like any of the other STALLioN functions.
The cursor position is also controllable, through the use of the iosetcursorpos
function, which has the following parameters:

int iosetcursorpos(unsigned int x, unsigned int y)

Note that the cursor position is not stored internally as a Cartesian value, it
is stored as a single linear integer in the iodisplay struct, as the variable
cursorPos. If you wish to change this value, and thus control the cursor
position using linear values, please do not access the variable directly.
Instead, use this function:

int iosetcursorposlin(unsigned int pos)

iosetcursorposlin has bounds checking, and so is much preferred over manually
changing the cursor position.

Clearing the screen

Often, circumstances arise when the screen needs to be cleaned and reset. In
standard C, a true screen clear is impossible without using system calls or
platform dependent code. In STALLioN, clearing the screen is simple. Like the
rest of the STALLioN functions, one will clear the screen to the default colours
and the other will clear it to whatever colour the user wishes. They are as
follows:

int ioclear()

int ioclearattrib(int col)

Note that when clearing the screen with the default colours it is the background
colour which determines the clear colour, not the foreground.

Getting key states

STALLioN is also capable of returning the current state of keys on the keyboard.
This is achieved using the iogetkeystate function, which is as below:

int iogetkeystate(int scancode)

This function, unlike a lot of the rest of the STALLioN library, does not need
a display as a parameter; it just requires the scancode of the key you wish to
check the state of. A 1 will be returned if the specified key is pressed, a 0
if it is not. The full list of keys and their keycodes can be found in this
manual.

Getting key presses

As well as being able to record the state of various keys, STALLioN can also
return the next keypressed. This is done using the iogetch function, and
works like a non-blocking version of its namesake in the standard C library.

int iogetch()

It takes no parameters, it just returns the ASCII value of the key pressed if
there is one, and a 0 if there isn't. This is completely non-blocking and does
not interrupt or pause the program in any way.

Colours

Colours in STALLioN are controlled by using a series of integers. Each integer
is another colour. The full list of colours is as follows:

    Colour          Decimal         Hex

    Light Grey      0               0x0
    Black           1               0x1
    Red             2               0x2
    Green           3               0x3
    Blue            4               0x4
    Cyan            5               0x5
    Magenta         6               0x6
    Yellow          7               0x7
    White           16              0x10
    Dark Grey       17              0x11
    Bright Red      18              0x12
    Bright Green    19              0x13
    Bright Blue     20              0x14
    Bright Cyan     21              0x15
    Bright Magenta  22              0x16
    Bright Yellow   23              0x17

These codes are the same no matter which function you are using or whether the
colour is a background colour or a foreground colour.
Note that the colours STALLioN uses are terminal/system dependent, they are not
the same on every platform. This is because there is no standard for terminal
colours, and is unavoidable.

Aswell as the codes above, the following compiler defines can also be used:

    Light Grey      IO_LGREY
    Black           IO_BLACK
    Red             IO_RED
    Green           IO_GREEN
    Blue            IO_BLUE
    Cyan            IO_CYAN
    Magenta         IO_MAGENTA
    Yellow          IO_YELLOW
    White           IO_WHITE
    Dark Grey       IO_DGREY
    Bright Red      IO_BRED
    Bright Green    IO_BGREEN
    Bright Blue     IO_BBLUE
    Bright Cyan     IO_BCYAN
    Bright Magenta  IO_BMAGENTA
    Bright Yellow   IO_BYELLOW

Keycodes

The following is a table of all the scancodes that STALLioN can uses as keys
in the input functions. Some keys pertain to different characters on
different keyboard layouts and so this table will not always show the true
value. Such keys are appended with a langauge code to signify which character
it is in which language.

    Key     Shift       Dec     Hex

    Backspace   ----    08      0x08
    Tab         ----    09      0x09
    Enter       ----    13      0x0D
    Esc         ----    27      0x1B
    Space       ----    32      0x20
    End         ----    35      0x23
    Home        ----    36      0x24
    Left Arrow  ----    37      0x25
    Up Arrow    ----    38      0x26
    Right Arrow ----    39      0x27
    Down Arrow  ----    40      0x28
    0           ) (en)  48      0x30
    1           ! (en)  49      0x31
    2           " (en)  50      0x32
    3           £ (en)  51      0x33
    4           $ (en)  52      0x34
    5           % (en)  53      0x35
    6           ^ (en)  54      0x36
    7           & (en)  55      0x37
    8           * (en)  56      0x38
    9           ( (en)  57      0x39
    a           A       65      0x41
    b           B       66      0x42
    c           C       67      0x43
    d           D       68      0x44
    e           E       69      0x45
    f           F       70      0x46
    g           G       71      0x47
    h           H       72      0x48
    i           I       73      0x49
    j           J       74      0x4A
    k           K       75      0x4B
    l           L       76      0x4C
    m           M       77      0x4D
    n           N       78      0x4E
    o           O       79      0x4F
    p           P       80      0x50
    q           Q       81      0x51
    r           R       82      0x52
    s           S       83      0x53
    t           T       84      0x54
    u           U       85      0x55
    v           V       86      0x56
    w           W       87      0x57
    x           X       88      0x58
    y           Y       89      0x59
    z           Z       90      0x5A
    F1          ----    112     0x70
    F2          ----    113     0x71
    F3          ----    114     0x72
    F4          ----    115     0x73
    ; (en)      : (en)  186     0xBA
    = (en)      + (en)  187     0xBB
    , (en)      < (en)  188     0xBC
    - (en)      _ (en)  189     0xBD
    . (en)      > (en)  190     0xBE
    / (en)      ? (en)  191     0xBF
    ' (en)      @ (en)  192     0xC0
    [ (en)      { (en)  219     0xDB
    \ (en)      | (en)  220     0xDC
    ] (en)      } (en)  221     0xDD
    # (en)      ~ (en)  222     0xDE

Miscellaneous Functions

STALLioN also provides a simple millisecond wait function, to aid in cursor
period synchronisation and non-blocking input control. The function is called
iowait, and is as follows:

int iowait(unsigned int milliseconds)

It simply causes the program to sleep for the specified time, and returns 0
when done.