THE VISOPSYS WINDOW LIBRARY (Version 0.9)
(older version 0.85 is here)
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 or libwindow.so (link with ‘-lwindow’).
windowArchiveList *windowNewArchiveList(objectKey parent, windowListType type, int rows, int columns, archiveMemberInfo *members, int numMembers, void (*callback)(int), componentParameters *params)
Create a new archive list widget with the parent window ‘parent’, the window list type ‘type’ (windowlist_textonly or windowlist_icononly is currently supported), of height ‘rows’ and width ‘columns’, an array of archive member info and number of members, a function ‘callback’ for when the status changes, and component parameters ‘params’.
objectKey windowNewBannerDialog(objectKey parentWindow, const char *title, const char *message)
Create a ‘banner’ dialog box, with the parent window ‘parentWindow’, and the given titlebar text and main message. This is the very simplest kind of dialog; it just contains the supplied message with no acknowledgement mechanism for the user. If ‘parentWindow’ is NULL, the dialog box is actually created as an independent window that looks the same as a dialog. This is a non-blocking call that returns the object key of the dialog window. The caller must destroy the window when finished with it.
void windowCenterDialog(objectKey parentWindow, objectKey dialogWindow)
Center a dialog window. The first object key is the parent window, and the second is the dialog window. This function can be used to center a regular window on the screen if the first objectKey argument is NULL.
int windowNewChoiceDialog(objectKey parentWindow, const char *title, const char *message, char *choiceStrings[], int numChoices, int defaultChoice)
Create a ‘choice’ dialog box, with the parent window ‘parentWindow’, the given titlebar text and main message, and ‘numChoices’ choices, as specified by the ‘choiceStrings’. ‘default’ is the default focussed selection. The dialog will have a button for each choice. If the user chooses one of the choices, the function returns the 0-based index of the choice. Otherwise it returns negative. 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 windowNewColorDialog(objectKey parentWindow, color *pickedColor)
Create an ‘color chooser’ dialog box, with the parent window ‘parentWindow’, and a pointer to the color structure ‘pickedColor’. Currently the window consists of red/green/blue sliders and a canvas displaying the current color. The initial color displayed will be whatever is supplied in ‘pickedColor’. 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 windowNewFileDialog(objectKey parentWindow, const char *title, const char *message, const char *startDir, char *fileName, unsigned maxLength, fileType type, int thumb)
Create a ‘file’ dialog box, with the parent window ‘parentWindow’, and the given titlebar text and main message. If ‘startDir’ is a non-NULL directory name, the dialog will initially display the contents of that directory. If ‘fileName’ contains data (i.e. the string’s first character is non-NULL), the file name field of the dialog will contain that string. The ‘type’ argument specifies whether the user is expected to select a file (fileT) or directory (dirT) or any (unknownT). If ‘thumb’ is non-zero, an area will display image thumbnails when image files are clicked. The dialog will have a file selection area, a file name field, an ‘OK’ button and a ‘CANCEL’ button. If the user presses OK or ENTER, the function returns the value 1 and copies the file name into the fileName buffer. Otherwise it returns 0 and puts a NULL string into fileName. 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’).
windowFileList *windowNewFileList(objectKey parent, windowListType type, int rows, int columns, const char *directory, int flags, void (*callback)(windowFileList *, file *, char *, loaderFileClass *), componentParameters *params)
Create a new file list widget with the parent window ‘parent’, the window list type ‘type’ (windowlist_textonly or windowlist_icononly is currently supported), of height ‘rows’ and width ‘columns’, the name of the starting location ‘directory’, flags (such as WINFILEBROWSE_CAN_CD or WINFILEBROWSE_CAN_DEL — see sys/window.h), a function ‘callback’ for when the status changes, and component parameters ‘params’.
windowKeyboard *windowNewKeyboard(objectKey parent, int width, int height, void *callback, componentParameters *params)
Create a ‘virtual keyboard’ widget with the parent window ‘parent’, the given width and height in pixels, and an optional function pointer ‘callback’ for when virtual keys are pressed.
int windowNewLanguageDialog(objectKey parentWindow, char *pickedLanguage)
Create a ‘language chooser’ dialog box, with the parent window ‘parentWindow’, and a pointer to the string buffer ‘pickedLanguage’, which should be at least 6 bytes in length. The initial language selected will be the value of the LANG environment variable, if possible. 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 windowClearEventHandlers(void)
Remove all the callback event handlers registered with the windowRegisterEventHandler() function.
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.
int windowClearEventHandler(objectKey key)
Remove a callback event handler registered with the windowRegisterEventHandler() function.
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.
int 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.
int windowGuiThreadPid(void)
Returns the current GUI thread PID, if applicable, or else 0.
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().
int windowNewNumberDialog(objectKey parentWindow, const char *title, const char *message, int minVal, int maxVal, int defaultVal, int *value)
Create a ‘number’ dialog box, with the parent window ‘parentWindow’, and the given titlebar text and main message. The dialog will have a text field for the user to enter data using the keyboard, and a slider component for adjusting it with the mouse. Minimum, maximum, and default values should be supplied. 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 windowNewInfoDialog(objectKey parentWindow, const char *title, const 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, const char *title, const 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’).
windowPixelEditor *windowNewPixelEditor(objectKey parent, int width, int height, image *img, componentParameters *params)
Create a new pixel editor widget with the parent window ‘parent’, with the required width and height, a pointer to the image data ‘img’, and component parameters ‘params’.
objectKey windowNewProgressDialog(objectKey parentWindow, const char *title, progress *tmpProg)
Create a ‘progress’ dialog box, with the parent window ‘parentWindow’, and the given titlebar text and progress structure. The dialog creates a thread which monitors the progress structure for changes, and updates the progress bar and status message appropriately. If the operation is interruptible, it will show a ‘CANCEL’ button. If ‘parentWindow’ is NULL, the dialog box is actually created as an independent window that looks the same as a dialog. This is a non-blocking call that returns immediately (but the dialog box itself is ‘modal’). A call to this function should eventually be followed by a call to windowProgressDialogDestroy() in order to destroy and deallocate the window.
int windowProgressDialogDestroy(objectKey window)
Given the objectKey for a progress dialog ‘window’ previously returned by windowNewProgressDialog(), destroy and deallocate the window.
int windowNewPromptDialog(objectKey parentWindow, const char *title, const char *message, int rows, int columns, char *buffer)
Create a ‘prompt’ dialog box, with the parent window ‘parentWindow’, and the given titlebar text and main message. The dialog will have a single text field for the user to enter data. 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 windowNewPasswordDialog(objectKey parentWindow, const char *title, const char *message, int columns, char *buffer)
Create a ‘password’ dialog box, with the parent window ‘parentWindow’, and the given titlebar text and main message. The dialog will have a single password field. 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, const char *title, const char *message)
Create a ‘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’).
int windowNewRadioDialog(objectKey parentWindow, const char *title, const char *message, char *choiceStrings[], int numChoices, int defaultChoice)
Create a dialog window with a radio button widget with the parent window ‘parentWindow’, the given titlebar text and main message, and ‘numChoices’ choices, as specified by the ‘choiceStrings’. ‘default’ is the default focussed selection. The dialog’s radio button widget will have items for each choice. If the user chooses one of the choices, the function returns the 0-based index of the choice. Otherwise it returns negative. 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’).
objectKey windowNewThumbImage(objectKey parent, const char *fileName, unsigned maxWidth, unsigned maxHeight, int stretch, componentParameters *params)
Create a new window image component from the supplied image file name ‘fileName’, with the given ‘parent’ window or container, and component parameters ‘params’. Dimension values ‘maxWidth’ and ‘maxHeight’ constrain the maximum image size. The resulting image will be scaled down, if necessary, with the aspect ratio intact, unless ‘stretch’ is non-zero, in which case the thumbnail image will be resized to ‘maxWidth’ and ‘maxHeight’. If ‘params’ specifies a background color, any empty space will be filled with that color. If ‘fileName’ is NULL, an empty image will be created.
int windowThumbImageUpdate(objectKey thumbImage, const char *fileName, unsigned maxWidth, unsigned maxHeight, int stretch, color *background)
Update an existing window image component ‘thumbImage’, previously created with a call to windowNewThumbImage(), from the supplied image file name ‘fileName’. Dimension values ‘maxWidth’ and ‘maxHeight’ constrain the maximum image size. The resulting image will be scaled down, if necessary, with the aspect ratio intact. If ‘fileName’ is NULL, the image will become blank.