THE VISOPSYS WINDOW LIBRARY (Version 0.3) The window library is a set of functions to aid GUI
development on the Visopsys platform. At present the list of functions is small,
but it does provide very useful functionality. This includes an interface for
registering window event callbacks for GUI components, and a 'run' function to
poll for such events.
The functions are defined in the header file <sys/window.h>
and the code is contained in libwindow.a (link with '-lwindow').
int windowRegisterEventHandler(objectKey key, void
(*function)(objectKey, windowEvent *))
Register a callback function as an event handler for the GUI object 'key'.
The GUI object can be a window component, or a window for example. GUI
components are typically the target of mouse click or key press events,
whereas windows typically receive 'close window' events. For example, if you
create a button component in a window, you should call
windowRegisterEventHandler() to receive a callback when the button is pushed
by a user. You can use the same callback function for all your objects if you
wish -- the objectKey of the target component can always be found in the
windowEvent passed to your callback function. It is necessary to use one of
the 'run' functions, below, such as windowGuiRun() or windowGuiThread() in
order to receive the callbacks.
void windowGuiRun(void)
Run the GUI windowEvent polling as a blocking call. In other words, use
this function when your program has completed its setup code, and simply needs
to watch for GUI events such as mouse clicks, key presses, and window
closures. If your program needs to do other processing (independently of
windowEvents) you should use the windowGuiThread() function instead.
void windowGuiThread(void)
Run the GUI windowEvent polling as a non-blocking call. In other words,
this function will launch a separate thread to monitor for GUI events and
return control to your program. Your program can then continue execution --
independent of GUI windowEvents. If your program doesn't need to do any
processing after setting up all its window components and event callbacks, use
the windowGuiRun() function instead.
void windowGuiStop(void)
Stop GUI event polling which has been started by a previous call to one of
the 'run' functions, such as windowGuiRun() or windowGuiThread(). Note that
calling this function clears all callbacks registered with the
windowRegisterEventHandler() function, so if you want to resume GUI execution
you will need to re-register them.
int windowNewInfoDialog(objectKey parentWindow, char
*title, char *message)
Create an 'info' dialog box, with the parent window 'parentWindow', and the
given titlebar text and main message. The dialog will have a single 'OK'
button for the user to acknowledge. If 'parentWindow' is NULL, the dialog box
is actually created as an independent window that looks the same as a dialog.
This is a blocking call that returns when the user closes the dialog window
(i.e. the dialog is 'modal').
int windowNewErrorDialog(objectKey parentWindow,
char *title, char *message)
Create an 'error' dialog box, with the parent window 'parentWindow', and
the given titlebar text and main message. The dialog will have a single 'OK'
button for the user to acknowledge. If 'parentWindow' is NULL, the dialog box
is actually created as an independent window that looks the same as a dialog.
This is a blocking call that returns when the user closes the dialog window
(i.e. the dialog is 'modal').
int windowNewQueryDialog(objectKey parentWindow,
char *title, char *message)
Create an 'query' dialog box, with the parent window 'parentWindow', and
the given titlebar text and main message. The dialog will have an 'OK' button
and a 'CANCEL' button. If the user presses OK, the function returns the value
1. Otherwise it returns 0. If 'parentWindow' is NULL, the dialog box is
actually created as an independent window that looks the same as a dialog.
This is a blocking call that returns when the user closes the dialog window
(i.e. the dialog is 'modal').
|