<Start> <Intro> <Install> <Legal> <Screen> <Buffer> <Sprite> <Input> <Misc> <Debug> <Utes> <Author>
Input Functions
Overview
Input functions are meant to provide a way for your programs to receive input from the user in a fairly consistent manner across platforms. Three
different devices are supported: The keyboard, mouse and joystick.
Once you initialise each device, you can read them using provided functions. Note that if you call an input function and the device has not been
initialised, no action is taken. You should only initialise an input device once the screen has been initialised, as some input devices require this to
be the case.
Mouse
Functions are available to initialise the mouse and read its button state and position in screen co-ordinates. To provide compatibility for the
lowest common system, only one mouse button may be checked.
Your programs can check if the current target provides mouse support by checking the constant MOUSE_AVAILABLE. If this is 0 then no
mouse support is available. Any non-zero value for this constant means that the target has support for a mouse. This does not mean that a mouse
is actually installed on the machine, just that if one is installed, the mouse functions can be used to get input from it.
int mouse_present(void);
This function initialises the mouse if one is present, and returns MOUSE_PRESENT if there is a mouse available and initialised. If this routine
returns MOUSE_ABSENT, it means the computer the program is running on does not have a mouse attached (or it isn't functioning or
recognised). You should always have the screen initialised before calling this function.
void mouse_closedown(void);
This function clears up after the mouse and should always be called before your program exits and before the screen mode is restored. To use the
mouse after calling this function you must call mouse_present() again.
void mouse_show_pointer(void);
void mouse_hide_pointer(void);
These two functions are designed to allow the mouse pointer to be hidden. On some systems this may not be possible. The principle function of
these routines is to allow drawing to the screen to take place without being disturbed by the mouse cursor. If your system supports this in
hardware then these functions will implemented as stubs. If the mouse is initialised and the pointer is showing then you should always hide the
mouse cursor before drawing to the screen, and show the pointer once drawing is completed. If you don't do this, drawing may be corrupted on
some targets.
void mouse_get_status(int *x_pos,int *y_pos,int *b_status);
This function stores the status of the mouse in the integers passed. x_pos and y_pos are filled with the current x and y position of the mouse in
pixels, relative to the top left of the screen. b_status is filled with the status of the mouse button. The value returned in b_status can be read as 0
(no button pressed) or 1 (button pressed) by using the macro BUTTON_DOWN(status).
void mouse_set_status(int x,int y);
This function is intended to allow you to position the mouse pointer on the screen at the given x and y co-ordinates.
Developers Note: I'm not sure if this is possible on some future intended targets, so approach this function with caution (don't absolutely depend on it working).
Keyboard
The keyboard routines in JLib are intended to provide the user with more control over reading keys than the getc() approach. Two modes of
keyboard operation are supported; The standard getc() type method where a key is returned if one has been hit, otherwise the program waits for a
key press, and a more direct method of determining if a particular key is being pressed or not at a given moment in time.
If the target supports JLib style keyboard input then the constant KEYBOARD_AVAILABLE will be non zero. Note that C standard library keyboard functions are not likely to work while the keyboard is being used by JLib (there is often a fair amount of fiddling needed to get the keyboard into a raw mode) and so functions such as getc() and fgetc(stdin) should be avoided while the JLib keyboard routines are being used.
Character input is buffered, with the size of the buffer implementation dependent (currently 256 characters on all targets that support the keyboard). If the buffer is filled by the user pressing keys and the keyboard device not being read, then the buffer will be overwritten again starting from the 1st element. Keys are referred to by constants beginning with KEY_. The keys that can be checked for are given in <jlib.h>.
Extended keys such as Control, Alt, and arrow keys (or their equivalents) are buffered along with normal characters entered. If one or more
extended keys are pressed when a normal key is pressed, then the extended keys are buffered along with the normal key. This allows your
applications to check the buffer for Alt-Key combinations, or read cursor input that has been buffered. Note that although extended keys are
buffered, to read them from the buffer you must use the _ext_key_ functions. The functions kb_key_hit() and kb_get_next_key() ignore
extended keys totally, skipping over them if they are found in the keyboard buffer.
void kb_init(void);
Initialise the keyboard device ready to begin reading key values. This function should be called before using any other keyboard functions and
after the screen is initialised with screen_set_video_mode(). This function does not return a success code because if your keyboard is not
functioning it is unlikely that you could even run any programs at all. The keyboard state is cleared when the keyboard is initialised, i.e. no key
presses made before initialisation will be available.
void kb_closedown(void);
This function returns the keyboard to its former state whereby it is safe to use C standard library keyboard functions, and should be called before
the screen state is restored by your program.
int kb_keydown(int key);
Returns non zero if the given key is pressed down at the moment this function is called.
int kb_key_hit(void);
Returns non zero if any non-extended key has been hit or released since the last time the keyboard was cleared or it was initialised. This function
does not remove any keys from the keyboard buffer. A non-extended key is any letter, digit or printable character, tab , enter or space.
int kb_ext_key_hit(void);
Returns non zero if any key or extended key has been hit or released since the last time the keyboard was cleared or it was initialised. Use this function to allow checking for keys suck as Control or cursor keys. This function does not remove any keys from the keyboard buffer.
char kb_get_next_key(void);
Returns the next key waiting in the input buffer, or if the buffer is empty, waits for a key to be hit and returns it. This function behaves very
similarly to getc() or fgetc(stdin).
USHORT kb_get_next_ext_key(void);
Returns the next key waiting in the input buffer, or if the buffer is empty, waits for a key to be hit and returns it. The lower 8 bits of the value
returned contain the character hit, while the upper 8 bits contain the extended keys pressed with the character. If no non-extended key has been
hit, this function will wait until one has been pressed and then return it along with any extended keys pressed since. The exception to this is
cursor keys, which are returned as soon as they are encountered in the buffer.
This function flushes the keyboard buffer, similarly to fflush(stdin).
Joystick
Although the support code (prototypes) are written, no actual code yet exists for joysticks. Should be coming some time. Once the code arrives,
you will be able to read the joystick as follows: Your programs can see whether joystick support is enabled for a given target by reading the
constant JOYSTICK_AVAILABLE which will be defined if joystick support is available for the target. Note that even though a target supports
joysticks, a given computer may not have any attached to it. Each joystick has only two buttons which may be read, to cater for the lowest
common denominator. Joysticks are treated like digital sticks, so you can read a direction value, but no magnitude.
int joystick_count(void);
This function returns the number of joysticks connected to the computer. Each stick is identified by a number starting from 1. The number
returned is the maximum value that you may pass to the other joystick functions. If 0 is returned you may not use any joystick functions.
int joystick_init(int which);
This function initialises the joystick identified by the number which. If this call returns 0 then an error occurred initialising the joystick and it
should not be used.
void joystick_closedown(int which);
When you are finished reading values from the joystick you should shut it down with this function.
void joystick_get_status(int which,int *x_axis,int *y_axis,int *b_status);
This function will return (not very useful) raw information about the joystick position. You may use this raw information on a target by target basis, or you may have the library convert the raw data into a direction for you.
The button status of a stick can be found with the macros:
FIRE_1_DOWN(stick, status)
FIRE_2_DOWN(stick, status)
int joystick_get_direction(int x_axis,int y_axis);
Passing the raw values x_axis and y_axis from the function call to joystick_get_status() will return a more usable value as defined in <jlib.h>,
such as JOY_NORTH, JOY_NORTHEAST etc. This will only work if the joystick has previously been calibrated.
void joystick_calibrate(int which,int l,int r,int t,int b,int x_cen,int y_cen);
This function is used to calibrate the joystick in order to allow JLib to convert joystick values to directions. You pass this function the stick number which, the raw values received when the stick is held to the very left l, right r, top t, and bottom b, and x and y centres. It is anticipated that you will ask the user to do this once at the start of your joystick using application, record the results and use this function to calibrate the joystick.
<Start> <Intro> <Install> <Legal> <Screen> <Buffer> <Sprite> <Input> <Misc> <Debug> <Utes> <Author>