%----------------------------------------------------------------------------
\chapter{The Input Library}
%----------------------------------------------------------------------------
This library allow the user to interact with applications. Is composed by a
lower lever which must be initialized at the beginning. On top of this layer we
can find different peripherals:
\begin{itemize}
\item Keyboard;
\item Mouse;
\item Joystick;
\item Speaker;
\item Event debugger.
\end{itemize}
Each one can work independently from the others. In order to use the low lever
functions, the files \texttt{drivers/shark\_input26.h} must be included. It
contains the prototypes of the declared functions. First of all, the keyboard
needs be initialized by the calling \texttt{KEYB26\_init} primitive into the
\texttt{\_\_init\_\_} function in the initialization file or in any other point
of the application code.
\vspace{7mm}
\begin{intest}
INPUT26\_INIT\index{INPUT26\_init()}
\end{intest}
\begin{description}
\item [\textbf{int INPUT26\_init(void);}]
\item [\textbf{Description:}]It initializes the low lever input interface and
the library's internal data structures.
\item [\textbf{Return value:}] 0 if the operation is performed successfully; a
value less than 0, otherwise.
\end{description}
\vspace{7mm}
The following code shows an example of input drivers initialization for the
system:
\begin{description}
\item [Example:]
\end{description}
\begin{verbatim}
int res;
KEYB_PARMS kparms = BASE_KEYB;
MOUSE_PARMS mparms = BASE_MOUSE;
LINUXC26_register_module(TRUE);
INPUT26_init();
keyb_def_map(kparms, KEYMAP_IT);
keyb_def_ctrlC(kparms, NULL);
KEYB26_init(&kparms);
mouse_def_threshold(mparms, 5);
mouse_def_xmin(mparms, 0);
mouse_def_ymin(mparms, 0);
mouse_def_xmax(mparms, 639);
mouse_def_ymax(mparms, 479);
MOUSE26_init(&mparms);
SPEAK26_init();
JOY26_init();
...
\end{verbatim}
\vspace{7mm}
The event debugger is used to have an output of the raw data coming from an
input device for which a driver is not present. It can be stanter, stopper and
is possible to control the actual status.
\vspace{7mm}
\begin{intest}
EVBUG26\_INIT\index{EVBUG26\_init()}
\end{intest}
\begin{description}
\item [\textbf{int EVBUG26\_init(void);}]
\item [\textbf{Description:}]It initializes the event debugger interface and the
library's internal data structures.
\item [\textbf{Return value:}] 0 if the operation is performed successfully; a
value less than 0, otherwise.
\end{description}
\begin{intest}
EVBUG26\_CLOSE\index{EVBUG26\_close()}
\end{intest}
\begin{description}
\item [\texttt{int EVBUG26\_close(void);}]
\item [\textbf{Description:}]It close the event debugger interface.
\item [\textbf{Return value:}] 0 if the operation is performed successfully; -1
if the interface in not installed.
\end{description}
\begin{intest}
EVBUG26\_INSTALLED\index{EVBUG26\_installed()}
\end{intest}
\begin{description}
\item [\texttt{int EVBUG26\_installed(void);}]
\item [\textbf{Description:}]Return if the event debugger is actually installed.
\item [\textbf{Return value}:] 0 if the module is installed; 1 otherwise.
\end{description}
%----------------------------------------------------------------------------
\section{The keyboard library}
%----------------------------------------------------------------------------
In order to use the keyboard handling functions, the
\texttt{drivers/shark\_keyb26.h} header file, containing the interface
functions' prototypes, has to be included in the application program.
First of all, the keyboard needs be initialized by the calling
\texttt{KEYB26\_init} primitive into the \texttt{\_\_init\_\_} function in the
initialization file or in any other point of the application code and the input
low level driver must be already installed. A programmer can either initialize
the keyboard using the default settings or define his own parameters which are
encapsulated into a structure having \texttt{KEY\_PARMS} type. The strucuture
can be initialized with the default set of values by setting it equal to
\texttt{BASE\_KEYB}; the \texttt{keyb\_def\_...} macros can be used before
calling \texttt{KEYB26\_init} to modify each setting. Afterwards, it is possible
to read the ASCII code of any stroken key by calling the \texttt{keyb\_getch()}
function. This function requires a parameter which determines whether the task
should block until a key is hit or not. In the latter case, if no key has been
hit, the function returns 0 (behaving like \texttt{kbhit()}).
If we are interested in the key's scan code, we can call the
\texttt{keyb\_getcode()} function, which returns a struct containing either the
scan code or the ascii code and a byte containing information on the ALT, SHIFT
or CTRL key being pressed.
The following code shows an example of usage for the function:
\begin{verbatim}
KEY_EVT k;
...
if (keyb_getcode(&k, NON_BLOCK) {
if (isRightCtrl(k) || isLeftCtrl(k)) && (k.ascii == 'x')) {
/* Ctrl + `x' has been pressed */
...
}
}
...
\end{verbatim}
\noindent Finally, it is possible to define a function to be automatically
called every time a specific key (or a specific combination of keys) is pressed.
This is done by calling the \texttt{keyb\_hook()} function, which receives as
arguments a data structure containing the required combination of keys and the
function to be called.
\vspace{7mm}
\begin{intest}
KEYB26\_INIT\index{KEYB26\_init()}
\end{intest}
\begin{description}
\item [\textbf{int KEYB26\_init(KEYB\_PARMS {*}parms);}]
\item [\textbf{Description:}]It initializes the keyboard interface and the
library's internal data structures. It can be called using NULL as
\texttt{parms} to initialize the keyboard interface to default values. \\ Note
that to be proper initialized, you need also to initialize the HARTPORT
modules.
\item [\textbf{Return value:}] 0 if the operation is performed successfully; a
value less than 0, otherwise.
\end{description}
\begin{intest}
KEYB26\_CLOSE\index{KEYB26\_close()}
\end{intest}
\begin{description}
\item [\textbf{int KEYB26\_close(void);}]
\item [\textbf{Description:}]It close the keyboard interface.
\item [\textbf{Return value:}] 0 if the operation is performed successfully; -1
if the keyboard in not installed.
\end{description}
\begin{intest}
KEYB26\_INSTALLED\index{KEYB26\_installed()}
\end{intest}
\begin{description}
\item [\texttt{int KEYB26\_installed(void);}]
\item [Description:]Return if the keyboard driver is actually installed.
\item [\textbf{Return value:}] 0 if the keyboard is installed; 1 otherwise.
\end{description}
\begin{intest}
KEYB\_DEFAULT\_PARM\index{keyb\_default\_parm()}
\end{intest}
\begin{description}
\item [\textbf{void keyb\_default\_parm(KEYB\_PARMS parms);}]
\item [\textbf{Description:}] It changes the values of parms to the same vales
as the BASE\_KEYB default initializer.
\end{description}
\begin{intest}
KEYB\_DEF\_MAP\index{keyb\_def\_map()}
\end{intest}
\begin{description}
\item [\textbf{void keyb\_def\_map(KEYB\_PARMS parms, unsigned char map);}]
\item [\textbf{Description:}]It changes the default map used for the keyboard:
\texttt{map} can be \texttt{KEYMAP\_US} for an english keyboard or
\texttt{KEYMAP\_IT} for an italian keyboard. The default is english keyboard
layout.
\end{description}
\begin{intest}
KEYB\_DEF\_CTRLC\index{keyb\_def\_ctrlC()}
\end{intest}
\begin{description}
\item [\textbf{void keyb\_def\_ctrlC(KEYB\_PARMS parms, void
({*}ctrlcfunc)(KEY\_EVT {*}k));}]
\item [\textbf{Description:}] It enables the execution of a function when the
{}``ctrl\-C'' combination is pressed. By default, if this macro is not used, the
\texttt{ctrl\-C} combination results in calling \texttt{sys\_end()}. Note that a
small message is printed also on the console. The message is only visible if the
system is in text mode. If you are running a graphic application, remember to
redefine the Ctrl-C Handler!
\end{description}
\begin{intest}
KEYB\_DEF\_TASK\index{keyb\_def\_task()}
\end{intest}
\begin{description}
\item [\textbf{void keyb\_def\_task(KEYB\_PARMS parms, TASK\_MODEL {*} m);}]
\item [\textbf{Description:}] It specifies the parameters of the keyboard
server. The \texttt{TASK\_MODEL} {*} should be a valid pointer to a Task Model,
or \texttt{KEYB\_DEFAULT} if you want to specify the default behaviour. \\
This macro should be used every time the default server Task Model does not
adapt well to the configuration of the scheduling modules registered in the
system. \\
The default server Task Model is equivalent to this initialization:\\
\texttt{soft\_task\_default\_model(base\_m);}\\
\texttt{soft\_task\_def\_wcet(base\_m,2000);}\\
\texttt{soft\_task\_def\_met(base\_m,800);}\\
\texttt{soft\_task\_def\_period(base\_m,25000);}\\
\texttt{soft\_task\_def\_system(base\_m);}\\
\texttt{soft\_task\_def\_nokill(base\_m);}\\
\texttt{soft\_task\_def\_aperiodic(base\_m);}
\end{description}
\begin{intest}
KEYB\_GETCH, KEYB\_GETCHAR \index{keyb\_getch()} \index{keyb\_getchar()}
\end{intest}
\begin{description}
\item [\textbf{int keyb\_getch(BYTE wait);}]
\item [\textbf{int keyb\_getchar(void);}] (macro)
\item [\textbf{Description:}]If the keyboard queue is not empty,
\texttt{keyb\_getch()} returns the ASCII code of the pressed key. If the queue
is empty, the function's behaviour depends on the value of the \texttt{wait}
parameter: if it is \texttt{BLOCK}, then the calling task is blocked until a key
is pressed; if it is \texttt{NON\_BLOCK}, the function returns 0.
\texttt{keyb\_getchar()} is a macro for \texttt{keyb\_getch(BLOCK)}.
\item [\textbf{Return value:}] the ASCII code of the pressed key, if the buffer
is not empty; 0 otherwise.
\end{description}
\begin{intest}
KEYB\_GETCODE\index{keyb\_getcode()}
\end{intest}
\begin{description}
\item [\texttt{int}]\texttt{keyb\_getcode(KEY\_EVT
{*}k,
BYTE
wait);}
\item [\textbf{Description:}] It fetches the \texttt{KEY\_EVT} from the
keyboard's queue and copies it into the structure pointed by \texttt{k}. If the
queue is empty, the function behaves as \texttt{key\_getch()}.
\item [\textbf{Return value:}] 1 if a key was pressed, 0 otherwise.
\end{description}
\begin{intest}
KEYB\_HOOK\index{keyb\_hook()}
\end{intest}
\begin{description}
\item [\texttt{void}]\texttt{keyb\_hook(KEY\_EVT key, void ({*}hook)(KEY\_EVT
{*}keypressed), unsigned char lock);}
\item [\textbf{Description:}] Whenever the key combination specified in
\texttt{key} is pressed, the function \texttt{hook()} is invoked, getting
\texttt{key} as input parameter. If lock is set to \texttt{FALSE} after
executing the function \texttt{hook()}the key will be lost, otherwise it will be
inserted in the queue.
\end{description}
\begin{description}
\item [Example:]
\end{description}
\begin{verbatim}
#include <drivers/shark_keyb26.h>
void hook_func(KEY_EVT *keypressed) {
switch (keypressed->ascii) {
case 'w':
/* if 'CTRL-w' is pressed... */
...
break;
case 'x':
if (isLeftAlt(keypressed) || isRightAlt(keypressed)) {
/* if 'ALT-x' is pressed... */
...
} else {
/* if 'x' is pressed... */
...
}
}
}
int main(int argc,char *argv[]) {
KEY_EVT key;
/* keyboard initialization */
/* to hook 'CTRL-w' key */
key.ascii = 'w';
key.scan = KEY_W;
key.status = KEY_PRESSED;
key.flag = CNTR_BIT;
keyb_hook(key,hook_func,FALSE);
/* to hook key 'x' */
key.ascii = 'x';
key.scan = KEY_X;
key.status = KEY_PRESSED;
key.flag = 0;
keyb_hook(key,hook_func, FALSE);
/* to hook 'ALT-x' key */
key.flag = ALTL_BIT | ALTR_BIT;
keyb_hook(key,hook_func, FALSE);
...
}
\end{verbatim}
\begin{intest}
KEYB\_DISABLE\index{keyb\_disable()}
\end{intest}
\begin{description}
\item [\textbf{void keyb\_disable(void);}]
\item [\textbf{Description:}] Throw away the data arriving from the hardware
instead of processing them inside the driver.
\end{description}
\begin{intest}
KEYB\_ENABLE\index{keyb\_enable()}
\end{intest}
\begin{description}
\item [\textbf{void keyb\_enable(void);}]
\item [\textbf{Description:}] Allow the driver to receive data from the
hardware.
\end{description}
\begin{intest}
KEYB\_SET\_MAP\index{keyb\_set\_map()}
\end{intest}
\begin{description}
\item [\textbf{int keyb\_set\_map(unsigned char map);}]
\item [\textbf{Description:}] It changes the default map used for the keyboard:
\texttt{map} can be \texttt{KEYMAP\_US} for an english keyboard or
\texttt{KEYMAP\_IT} for an italian keyboard.
\item [\textbf{Return value:}] the keyboard map identifier effectively applied.
\end{description}
\begin{intest}
KEYB\_GET\_MAP\index{keyb\_get\_map()}
\end{intest}
\begin{description}
\item [\texttt{int}]\texttt{keyb\_get\_map(void);}
\item [\textbf{Description:}] Return the identifier of the keyboard map actually
in use.
\end{description}
\begin{intest}
KEY\_EVT\index{KEY\_EVT, structure}
\end{intest}
\begin{description}
\item [\textbf{Description:}] it is a data structure containing the following
fields:
\begin{description}
\item [ascii:]ascii code of the key;
\item [scan:]scan code of the key;
\item [status:]the key can be pressed, repeated or released. When used to set an
hook more than one status can be selected. The \texttt{status} field can be
accessed by one of the following macros, whose usage is self-explaining:
\begin{itemize}
\item isPressed(\&k)
\item isRepeated(\&k)
\item isReleased(\&k)
\end{itemize}
\item [flag:]codes of the ALT, SHIFT and CTRL keys. \\
The \texttt{flag} field can be accessed by one of the following macros, whose
usage is self-explaining:
\begin{itemize}
\item isScanCode(\&k), decides whether the hit key has an ASCII code or not;
\item isLeftShift(\&k)
\item isRightShift(\&k)
\item isLeftAlt(\&k)
\item isRightAlt(\&k)
\item isLeftCtrl(\&k)
\item isRightCtrl(\&k)
\end{itemize}
\end{description}
\end{description}
%----------------------------------------------------------------------------
\section{The mouse library}
%----------------------------------------------------------------------------
To use the mouse into an application program, the user must call the
\texttt{MOUSE26\_init} function. Then, all mouse functions are available until a
call to the \texttt{MOUSE26\_close} function. The initialization of the mouse
library is performed by \texttt{MOUSE26\_init}, which requires a parameter of
\texttt{MOUSE\_PARMS} type to initialize the mouse. The following example shows
a possible mouse initialization:
\begin{verbatim}
int main(int argc,char *argv[]) {
int result;
MOUSE_PARMS params = BASE_MOUSE;
result = MOUSE26_init(¶ms);
if (result!=0) {
// the mouse can't be initialized
}
// other mouse functions
MOUSE26_close();
}
\end{verbatim}
The \texttt{MOUSE26\_close} function is not required but can be used to release
all the hardware resources that the library acquires. The NULL constant can be
passed to the \texttt{MOUSE26\_init()} function for a default initialization.
The \texttt{params} variable can be used to change the default setting of the
initialization procedure using some macros, whose names start with
\texttt{mouse\_def\_}. All the mouse functions can be found in the include file
\texttt{drivers/shark\_mouse26.h}.
\vspace{7mm}
\begin{intest}
MOUSE26\_INIT\index{MOUSE26\_init()}
\end{intest}
\begin{description}
\item [\texttt{int}]\texttt{MOUSE26\_init(KEYB\_PARMS
{*}parms);}
\item [\textbf{Description:}] It initializes the mouse interface and the
library's internal data structures. It can be called using NULL as
\texttt{parms} to initialize the mouse interface to default values.
\item [\textbf{Return value:}] 0 if the operation is performed successfully; a
value less than 0, otherwise.
\end{description}
\begin{intest}
MOUSE26\_CLOSE\index{MOUSE26\_close()}
\end{intest}
\begin{description}
\item [\texttt{int}]\texttt{MOUSE26\_close(void);}
\item [\textbf{Description:}] It
close
the
mouse
interface.
\item [\textbf{Return value:}]
0
if
the
operation
is
performed
successfully;
-1
if
the
mouse
in
not
installed.
\end{description}
\begin{intest}
MOUSE26\_INSTALLED\index{MOUSE26\_installed()}
\end{intest}
\begin{description}
\item [\texttt{int}]\texttt{MOUSE26\_installed(void);}
\item [\textbf{Description:}] Return
if
the
mouse
driver
is
actually
installed.
\item [\textbf{Return value:}]
0
if
the
mouse
is
installed;
1
otherwise.
\end{description}
\begin{intest}
MOUSE\_DEFAULT\_PARM\index{mouse\_default\_parm()}
\end{intest}
\begin{description}
\item [\texttt{void}]\texttt{mouse\_default\_parm(KEYB\_PARMS
parms);}
\item [\textbf{Description:}] It
changes
the
values
of
parms
to
the
same
vales
as
the
BASE\_MOUSE
default
initializer.
\end{description}
\begin{intest}
MOUSE\_DEF\_THRESHOLD\index{mousedef\_def\_threshold()}
\end{intest}
\begin{description}
\item [\texttt{void}]\texttt{mouse\_def\_threshold(MOUSE\_PARMS
parms,
int
thr);}
\item [\textbf{Description:}] It
changes
the
default
threshold
(i.e.,
the
mouse
sensitivity)
value
used
in
the
mouse
driver.
Is
a
scaling
factor
between
the
hardware
position
increment
and
the
logical
increment
in
the
mouse
position.
The
higher
the
value,
the
lower
the
sensitivity.
The
default
is
10.
\end{description}
\begin{intest}
MOUSE\_DEF\_X0,
MOUSE\_DEF\_Y0,
MOUSE\_DEF\_Z0\index{mousedef\_def\_x0()} \index{mousedef\_def\_y0()}
\index{mousedef\_def\_z0()}
\end{intest}
\begin{description}
\item [\texttt{void}]\texttt{mouse\_def\_x0(MOUSE\_PARMS
parms,
int
xvalue);}
\item [\texttt{void}]\texttt{mouse\_def\_y0(MOUSE\_PARMS
parms,
int
yvalue);}
\item [\texttt{void}]\texttt{mouse\_def\_z0(MOUSE\_PARMS
parms,
int
zvalue);}
\item [\textbf{Description:}] These
functions
change
the
initial
value
of
the
mouse
position.
The
default
vilue
for
each
parameter
is
0
if
permitted
by
mouse
position
bounds.
\end{description}
\begin{intest}
MOUSE\_DEF\_XMIN,
MOUSE\_DEF\_XMAX\index{mousedef\_def\_xmin()} \index{mousedef\_def\_xmax()}
\end{intest}
\begin{description}
\item [\texttt{void}]\texttt{mouse\_def\_xmin(MOUSE\_PARMS
parms,
int
minvalue);}
\item [\texttt{void}]\texttt{mouse\_def\_xmax(MOUSE\_PARMS
parms,
int
maxvalue);}
\item [\textbf{Description:}] It
changes
the
minimum
and
maximum
allowed
value
for
the
x
coordinate.
\end{description}
\begin{intest}
MOUSE\_DEF\_YMIN,
MOUSE\_DEF\_YMAX\index{mousedef\_def\_ymin()} \index{mousedef\_def\_ymax()}
\end{intest}
\begin{description}
\item [\texttt{void}]\texttt{mouse\_def\_ymin(MOUSE\_PARMS
parms,
int
minvalue);}
\item [\texttt{void}]\texttt{mouse\_def\_ymax(MOUSE\_PARMS
parms,
int
maxvalue);}
\item [\textbf{Description:}] It
changes
the
minimum
and
maximum
allowed
value
for
the
y
coordinate.
\end{description}
\begin{intest}
MOUSE\_DEF\_TASK\index{mouse\_def\_task()}
\end{intest}
\begin{description}
\item [\texttt{void}]\texttt{mouse\_def\_task(MOUSE\_PARMS
parms,
TASK\_MODEL
{*}
m);}
\item [\textbf{Description:}] This
macro
defines
the
parameters
for
the
mouse
handling
task.
The
\texttt{TASK\_MODEL}
{*}
should
be
a
valid
pointer
to
a
Task
Model,
or
\texttt{MOUSE\_DEFAULT}
if
you
want
to
specify
the
default
behaviour.
\\
This
macro
should
be
used
every
time
the
default
Task
Model
does
not
adapt
well
to
the
configuration
of
the
scheduling
modules
registered
in
the
system.
\\
The
default
Task
Model
is
equivalent
to
this
initialization:\\
\texttt{soft\_task\_default\_model(base\_m);
}~\\
\texttt{soft\_task\_def\_wcet(base\_m,2000);
}~\\
\texttt{soft\_task\_def\_met(base\_m,500);
}~\\
\texttt{soft\_task\_def\_period(base\_m,8000);
}~\\
\texttt{soft\_task\_def\_system(base\_m);
}~\\
\texttt{soft\_task\_def\_nokill(base\_m);
}~\\
\texttt{soft\_task\_def\_aperiodic(base\_m);}
\end{description}
\begin{intest}
MOUSE\_ENABLE\index{mouse\_enable()}
\end{intest}
\begin{description}
\item [\texttt{void}]\texttt{mouse\_enable(void);}
\item [\textbf{Description:}] Allow
the
driver
to
receive
data
from
the
hardware.
\end{description}
\begin{intest}
MOUSE\_DISABLE\index{mouse\_disable()}
\end{intest}
\begin{description}
\item [\texttt{void}]\texttt{mouse\_disable(void);}
\item [\textbf{Description:}] This
function
disable
the
mouse;
the
driver
stop
to
respond
to
the
data
arriving
from
the
hardware.
\end{description}
\begin{intest}
MOUSE\_SETPOSITION\index{mouse\_setstatus()}
\end{intest}
\begin{description}
\item [\texttt{void}]\texttt{mouse\_setposition(int
x,
int
y,
int
z);}
\item [\textbf{Description:}] Set
values
for
axes
and
wheel.
Values
for
x
and
y
axis
are
compared
against
bounds
for
the
allowed
zone.
\end{description}
\begin{intest}
MOUSE\_GETPOSITION\index{mouse\_getstatus()}
\end{intest}
\begin{description}
\item [\texttt{void}]\texttt{mouse\_getposition(int
{*}x,
int
{*}y,
int
{*}z,
unsigned
long
{*}buttons);}
\item [\textbf{Description:}] Get
values
for
axes,
wheel
and
buttons.
In
the
\texttt{buttons}
variable
each
bit
rappresent
the
status
of
a
button.
\end{description}
\begin{intest}
MOUSE\_SETLIMITS\index{mouse\_setlimits()}
\end{intest}
\begin{description}
\item [\texttt{void}]\texttt{mouse\_setlimits(int
xmin,
int
ymin,
int
xmax,
int
ymax);}
\item [\textbf{Description:}] It
changes
the
minimum
and
maximum
allowed
value
for
x
and
y
coordinate.
\end{description}
\begin{intest}
MOUSE\_GETLIMITS\index{mouse\_getlimits()}
\end{intest}
\begin{description}
\item [\texttt{void}]\texttt{mouse\_getlimits(int
{*}xmin,
int
{*}ymin,
int
{*}xmax,
int
{*}ymax);}
\item [\textbf{Description:}] Allow
to
obtain
the
minimum
and
maximum
permited
value
for
x
and
y
coordinate.
\end{description}
\begin{intest}
MOUSE\_SETTHRESHOLD\index{mouse\_setthreshold()}
\end{intest}
\begin{description}
\item [\texttt{void}]\texttt{mouse\_setthreshold(int
th);}
\item [\textbf{Description:}] It
changes
the
threshold
value
used
in
the
mouse
driver.
Is
a
scaling
factor
between
the
hardware
position
increment
and
the
logical
increment
in
the
mouse
position.
The
default
is
10.
\end{description}
\begin{intest}
MOUSE\_GETTHRESHOLD\index{mouse\_getthreshold()}
\end{intest}
\begin{description}
\item [\texttt{void}]\texttt{mouse\_getthreshold(int
th);}
\item [\textbf{Description:}] Return
the
threshold
value
used
in
the
mouse
driver.
Is
a
scaling
factor
between
the
hardware
position
increment
and
the
logical
increment
in
the
mouse
position.
The
default
is
10.
\end{description}
\begin{intest}
MOUSE\_HOOK\index{mouse\_hook()}
\end{intest}
\begin{description}
\item [\texttt{void}]\texttt{mouse\_hook(MOUSE\_HANDLER
hook);}
\item [\textbf{Description:}] Whenever
the
driver
receive
data
from
the
hardware
the
function
\texttt{hook()}
is
invoked
with
a
\texttt{MOUSE\_EVT}
as
parameter.
To
detach
a
previously
defined
hook
with
NULL
as
parameter.
\end{description}
\begin{intest}
MOUSE\_EVT\index{MOUSE\_EVT, structure}
\end{intest}
\begin{description}
\item [\textbf{Description:}] it is a data structure containing the following
fields:
\begin{description}
\item [x,y,z:]actual mouse position;
\item [dx,dy,dz:]increments from the last event;
\item [buttons:]each bit in the parameter rappresent the status of one button of
the mouse.
\end{description}
\item [The]following code shows an example of usage for the function
\texttt{mouse\_hook} and the structure \texttt{MOUSE\_EVT}:
\end{description}
\begin{description}
\item [Example:]
\end{description}
\begin{verbatim}
#include <drivers/shark_mouse26.h>
void hook_func(MOUSE_EVT *mevt) {
if (mevt->button & 0x1) {
/* The 1st button is pressed... */
...
}
if ((mevt->dx > 10) || (mevt->dx > 10)) {
/* Increment on x or y axis major than 10... */
...
}
if (mevt->dz > 0) {
/* Wheel position changed... */
...
}
int main(int argc,char *argv[]) {
/* mouse hook initialization */
mouse_hook(hook_func);
...
}
\end{verbatim}
\begin{intest}
ISLEFTBUTTON, ISCENTRALBUTTON, ISRIGHTBUTTON\index{isLeftButton()}
\index{isCentralButton()} \index{isRightButton()}
\end{intest}
\begin{description}
\item [\textbf{isLeftButton(int button)}]
\item [\textbf{isCentralButton(int button)}]
\item [\textbf{isRightButton(int button)}]
\item [\textbf{Description:}] These macros are used to test whether a specific
mouse button is pressed.
\end{description}
%----------------------------------------------------------------------------
\subsection{The mouse graphics functions}
%----------------------------------------------------------------------------
The system provide a set of function to quickly draw the mouse cursor both in
text and graphic mode. For each mode we can find 2 functions. The first used to
set the cursor shape and the second to enable/disable the cursor visualization.
ATTENTION: In text mode the mouse position is taken considering characters,
while in graphics values are pixels as mining.
\vspace{7mm}
\begin{intest}
MOUSE\_TXTCURSOR,\index{mouse\_txtcursor()}MOUSE\_GRXCURSOR\index{
mouse\_grxcursor()}
\end{intest}
\begin{description}
\item [\textbf{void mouse\_txtcursor(int cmd);}]
\item [\textbf{void mouse\_grxcursor(int cmd, int bpp);}]
\item [\textbf{Description:}] This function enables/disables the
textual/grafical autocursor features of the library; \texttt{cmd} can be:
\texttt{DISABLE} (disable cursor), \texttt{ENABLE} (enable a cursor). The
graphic version need and other parameter \texttt{bpp} which is depth of the
screen in bytes. These commands can be composite with two flags:
\begin{itemize}
\item \texttt{AUTOOFF}: if a user mouse handler is called, then during this call
the mouse is off (if you use a \texttt{mouse\_off()} you can hang the mouse
task).
\item \texttt{WITHOUTSEM}: the autocursor mouse functions are not protected by a
semaphore (so tasks cannot be blocked, but garbage can be displayed).
\end{itemize}
\end{description}
\begin{intest}
MOUSE\_TXTSHAPE\index{mouse\_txtshape()}
\end{intest}
\begin{description}
\item [\textbf{void mouse\_txtshape(DWORD shape);}]
\item [\textbf{Description:}] This function defines the shape of the text
cursor; ``shape'' is a DWORD that is used to display the cursor: the text
character and attributes are taken from the text memory, these values are and-ed
with the low word of \texttt{shape} and the result is XOR-ed with the high word
of \texttt{shape}, the result is written into the text memory. For examples, the
default mouse cursor shape is 0x7700ffff; the character and attribute that are
taken from the the memory are and-ed with 0xffff, so they do not change, and
then are xor-ed with 0x7700: the character is xor-ed with 0x00 and the attribute
byte is xor-ed with 0x77; the character remains the same but the attribute byte
is inverted; so the mouse cursor is displayed inverting the colors of the
character (the attribute byte contains the character foreground and background
color and is coded in the usually EGA/VGA mode; you can read a book about VGA
display adapters to find more
informations).
\end{description}
\begin{intest}
MOUSE\_GRXSHAPE\index{mouse\_grxshape()}
\end{intest}
\begin{description}
\item [\textbf{void mouse\_grxshape(BYTE {*}img, BYTE {*}mask, int bpp);}]
\item [\textbf{Description:}] This function defines the shape of the graphical
cursor; \texttt{img} is a pointer to an image of 16x16 that can be used with the
\texttt{grx\_putimage()} function, or can be \texttt{NULL} (in this case a
default cursor is used); before putting the image into the screen's memory, the
image is and-ed with \texttt{mask}. The parameter \texttt{bpp} is depth of the
screen in bytes.
\item [Example:]
\begin{tt}
\begin{verbatim}
/*
* the resolution is 640x480 with 2 BYTE for pixel
*/
/* WHITE,RED,GREEN and MAGENTA are defined into <cons.h>*/
#define W rgb16(255, 255, 255)
#define R rgb16(255, 0, 0)
#define G rgb16( 0, 255, 0)
#define M rbg16(255, 0, 255)
/* mouse shape */
WORD my_mouse_cursor[16 * 16] = {
0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,
0,W,W,W,W,0,0,0,0,0,0,W,W,W,W,0,
0,W,M,0,0,0,0,0,0,0,0,0,0,M,W,0,
0,W,0,M,0,0,0,0,0,0,0,0,M,0,W,0,
0,W,0,0,M,0,0,0,0,0,0,M,0,0,W,0,
0,0,0,0,0,M,0,0,0,0,M,0,0,0,0,0,
0,0,0,0,0,0,G,G,G,G,0,0,0,0,0,0,
0,0,0,0,0,0,G,0,0,G,0,0,0,0,0,0,
0,0,0,0,0,0,G,0,0,G,0,0,0,0,0,0,
0,0,0,0,0,0,G,0,0,G,0,0,0,0,0,0,
0,0,0,0,0,0,G,G,G,G,0,0,0,0,0,0,
0,0,0,0,0,0,M,M,M,M,0,0,0,0,0,0,
0,0,0,0,0,0,M,M,M,M,0,0,0,0,0,0,
0,0,0,0,0,M,M,M,M,M,M,0,0,0,0,0,
0,0,0,0,M,M,M,M,M,M,M,M,0,0,0,0,
0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,
};
/* mask for pixels (2 bytes in this case) */
/* 0xffff means that the background image is used */
/* 0x0000 means tha the background image is cleared */
/* prior to draw the mouse cursor */
#define F 0xffff
#define B 0x0000
/* mouse mask */
WORD my_mouse_mask[16 * 16] = {
B,B,B,B,B,B,F,F,F,F,B,B,B,B,B,B,
B,0,0,0,0,B,F,F,F,F,B,0,0,0,0,B,
B,0,0,B,B,F,F,F,F,F,B,B,B,0,0,B,
B,0,B,0,B,F,F,F,F,F,F,B,0,B,0,B,
B,0,B,B,0,B,F,F,F,F,B,0,B,B,0,B,
B,B,B,F,B,0,B,B,B,B,0,B,F,B,B,B,
F,F,F,F,F,B,0,0,0,0,B,F,F,F,F,F,
F,F,F,F,F,B,0,B,B,0,B,F,F,F,F,F,
F,F,F,F,F,B,0,B,B,0,B,F,F,F,F,F,
F,F,F,F,F,B,0,B,B,0,B,F,F,F,F,F,
F,F,F,F,F,B,0,0,0,0,B,F,F,F,F,F,
F,F,F,F,F,B,0,0,0,0,B,F,F,F,F,F,
F,F,F,F,F,B,0,0,0,0,B,F,F,F,F,F,
F,F,F,F,B,0,0,0,0,0,0,B,F,F,F,F,
F,F,F,B,0,0,0,0,0,0,0,0,B,F,F,F,
F,F,F,B,B,B,B,B,B,B,B,B,B,F,F,F,
};
int main(int argc, char *argv[]) {
MOUSE_PARMS mouse = BASE_MOUSE;
/*
* mouse initialization
*/
MOUSE26_init(&mouse);
/* a resolution of 640x480 is used */
mouse_setlimit(XMINLIMIT(640,480),
YMINLIMIT(640,480),
XMAXLIMIT(640,480),
YMAXLIMIT(640,480));
/* initial position */
mouse_setposition(320,280);
/* mouse threshold */
mouse_setthreshold(2);
/* my new mouse shape */
mouse_grxshape(my_mouse_cursor,my_mouse_mask, 2);
/* automatic graphics mouse cursor enabled */
mouse_grxcursor(ENABLE, 2);
/* mouse displayed into the screen */
mouse_on();
...
}
\end{verbatim}
\end{tt}
\end{description}
\begin{intest}
MOUSE\_OFF, MOUSE\_ON \index{mouse\_off()}\index{mouse\_on()}
\end{intest}
\begin{description}
\item [\textbf{void mouse\_off(void);}]
\item [\textbf{void mouse\_on(void);}]
\item [\textbf{Description:}] This functions disables and enables the display of
the mouse cursor on the screen (the mouse events are handled).
\item [\textbf{Warning:}]These functions must be called before/after calling any
graphic function that modifies the screen.
\end{description}
%----------------------------------------------------------------------------
\section{The joystick library}
%----------------------------------------------------------------------------
In order to use the gameport handling functions, the
\texttt{drivers/shark\_joy26.h} header file, containing the interface functions'
prototypes, has to be included in the application program.
First of all, the joystick needs be initialized by the calling
\texttt{JOY26\_init} primitive into the \texttt{\_\_init\_\_} function in the
initialization file or in any other point of the application code.
ATTENTION: The driver only work with gameport that emulate the ``old
SoundBlaster'' gameport interface. Other kind of gameports will not be
identified.
\vspace{7mm}
\begin{intest}
JOY26\_INIT\index{JOY26\_init()}
\end{intest}
\begin{description}
\item [\textbf{int JOY26\_init(void);}]
\item [\textbf{Description:}] It initializes the joystick interface and the
library's internal data structures.
\item [\textbf{Return value:}] 0 if the operation is performed successfully; a
value less than 0, otherwise.
\end{description}
\begin{intest}
JOY26\_CLOSE\index{JOY26\_close()}
\end{intest}
\begin{description}
\item [\texttt{int}]\texttt{MOUSE26\_close(void);}
\item [\textbf{Description:}] It close the joystick interface.
\item [\textbf{Return value:}] 0 if the operation is performed successfully; -1
if the joystick in not installed.
\end{description}
\begin{intest}
JOY26\_INSTALLED\index{JOY26\_installed()}
\end{intest}
\begin{description}
\item [\textbf{int JOY26\_installed(void);}]
\item [\textbf{Description:}] Return if the joystick driver is actually installed.
\item [\textbf{Return value:}] 0 if the joystick is installed; 1 otherwise.
\end{description}
\begin{intest}
JOY\_ENABLE\index{joy\_enable()}
\end{intest}
\begin{description}
\item [\textbf{void joy\_enable(void);}]
\item [\textbf{Description:}] Allow the driver to receive data from the hardware.
\end{description}
\begin{intest}
JOY\_DISABLE\index{joy\_disable()}
\end{intest}
\begin{description}
\item [\texttt{void}]\texttt{joy\_disable(void);}
\item [\textbf{Description:}] Throw away the data arriving from the hardware
instead of processing them inside the driver.
\end{description}
\begin{intest}
JOY\_SETSTATUS\index{joy\_setstatus()}
\end{intest}
\begin{description}
\item [\textbf{void joy\_setstatus(int axe0, int axe1, int axe2, int axe3, int buttons);}]
\item [\textbf{Description:}] Set values for axes and buttons. Usually
\texttt{axe0} and \texttt{axe1} are x and y axis for the first joystick while
\texttt{axe2} and \texttt{axe3} are x and y axis for the second one. In the
\texttt{buttons} parameter each bit rapresents the status of one button.
\end{description}
\begin{intest}
JOY\_GETSTATUS\index{joy\_getstatus()}
\end{intest}
\begin{description}
\item [\textbf{void joy\_getstatus(int {*}axe0, int {*}axe1, int {*}axe2, int {*}axe3, int {*}buttons);}]
\item [\textbf{Description:}] Get values for axes and buttons. Usually
\texttt{axe0} and \texttt{axe1} are x and y axis for the first joystick while
\texttt{axe2} and \texttt{axe3} are x and y axis for the second one. In the
\texttt{buttons} parameter each bit rappresent the status of one button.
\end{description}
%----------------------------------------------------------------------------
\section{The speaker library}
%----------------------------------------------------------------------------
The system provide a driver to use the internal PC speaker. It can play a note
at a given frequency for a predefined period or in a endless loop. In order to
use the speaker handling functions, the
\texttt{drivers/shark\_spk26.h} header
file, containing the interface functions' prototypes, has to be included in the
application program.
First of all, the mouse needs be initialized by the calling
\texttt{SPEAK26\_init} primitive into the \texttt{\_\_init\_\_} function in the
initialization file or in any other point of the application code and the input
low level driver must be already installed.
\vspace{7mm}
\begin{intest}
SPEAK26\_INIT\index{SPEAK26\_init()}
\end{intest}
\begin{description}
\item [\textbf{int SPEAK26\_init(void);}]
\item [\textbf{Description:}] It initializes the speaker interface and the
library's internal data structures.
\item [\textbf{Return value:}] 0 if the operation is performed successfully; a
value less than 0, otherwise.
\end{description}
\begin{intest}
SPEAK26\_CLOSE\index{SPEAK26\_close()}
\end{intest}
\begin{description}
\item [\textbf{int SPEAK26\_close(void);}]
\item [\textbf{Description:}] It close the speaker interface.
\item [\textbf{Return value:}] 0 if the operation is performed successfully; -1
if the speaker in not installed.
\end{description}
\begin{intest}
SPEAK26\_INSTALLED\index{SPEAK26\_installed()}
\end{intest}
\begin{description}
\item [\textbf{int SPEAK26\_installed(void);}]
\item [\textbf{Description:}] Return if the speaker driver is actually installed.
\item [\textbf{Return value:}] 0 if the speaker is installed; 1 otherwise.
\end{description}
\begin{intest}
SPEAKER\_SOUND\index{speaker\_sound()}
\end{intest}
\begin{description}
\item [\textbf{void speaker\_sound(unsigned int hz, unsigned int ticks);}]
\item [\textbf{Description:}] Generate a note at a frequency given using the
parameter \texttt{hz}. The parameter \texttt{ticks} is the duration of the note;
if set to 0 the note is repeated in an endless loop.
\end{description}
\begin{intest}
SPEAKER\_MUTE\index{speaker\_mute()}
\end{intest}
\begin{description}
\item [\texttt{int}]\texttt{speaker\_mute(void);}
\item [\textbf{Description:}] Reset the internal speaker making it silent.
\end{description}