Data Structures | Defines | Functions

iliad_app.h File Reference

Iliad API functions for application initialisation and event handling. More...

#include <X11/Xlib.h>
#include <gtk/gtkstyle.h>
#include <gdk/gdkkeysyms.h>

Go to the source code of this file.

Data Structures

struct  iliad_event_sys
 System event type, currently limited to exposure and delete events. More...
struct  iliad_event_key
 Key (= Iliad button) event. More...
struct  iliad_event_pen
 Pen drag or click event. More...
struct  iliad_event_toolbar
 Toolbar IPC event. More...
struct  iliad_event_pagebar
 Pagebar IPC event. More...
union  iliad_event
 Union event type, subtypes distinguished by type member. More...

Defines

#define EV_SYS   0
#define EV_KEY   1
#define EV_PEN   2
#define EV_TOOLBAR   3
#define EV_PAGEBAR   4
#define EV_SYS_DELETE   0
#define EV_SYS_EXPOSE   1
#define EV_KEY_ASCEND   0
#define EV_KEY_FORW   1
#define EV_KEY_BACK   2
#define EV_KEY_UP   3
#define EV_KEY_DOT   4
#define EV_KEY_DOWN   5
#define SYNC_TOOLBAR   1
#define SYNC_PAGEBAR   2
#define SYNC_OK   0
#define SYNC_ERROR   1
#define SYNC_TIMEOUT   2

Functions

int app_init (char *prgname)
 Initialise GTK and X and create main window.
void app_exit ()
 Clean up before application terminates.
GtkWidget * app_window ()
 Returns the GTK handle of the application window.
Display * app_xdisplay ()
 Returns the X display.
Window app_xwindow ()
 Returns the X handle of the application window.
int app_events_pending ()
 Returns number of events in the event queue.
void app_wait_event (iliad_event *ev)
 Return next event from the event queue.
int sync_bars (int mask)
 Synchronise with toolbar and/or pagebar.
FILE * app_debug ()
 Debug output file handle.

Detailed Description

Iliad API functions for application initialisation and event handling.

This application-level library contains functionality that every application will have to perform, such as initialising GTK, opening a full-screen window and receiving events from GTK and other sources. A common event queue is maintained which receives events from GTK, the toolbar and the pagebar, and from which the application can read when it is ready. A union event type declared here can contain all common kinds of events.

Required linker options: -lpthread -leripc -lerdm -lgtk-x11-2.0 -lgthread-2.0


Function Documentation

FILE* app_debug (  ) 

Debug output file handle.

This function returns a writable file handle to one of the following, in order of declining priority: the terminal on which a current SSH session is running (/dev/pts/0), the file /tmp/iliad_api.debug (opened to append new messages), or stderr. The files are opened on demand, and opening the first two is retried every time this function is called.

Returns:
File handle
int app_events_pending (  ) 

Returns number of events in the event queue.

If the return value is not 0, a subsequent app_wait_event() will not block.

Returns:
number of available events
void app_exit (  ) 

Clean up before application terminates.

The GTK and IPC event handling threads are terminated. This function must be called outside any gdk_threads_enter()...gdk_threads_leave() region since it calls these functions itself (and the GTK lock is not re-entrant).

int app_init ( char *  prgname  ) 

Initialise GTK and X and create main window.

This function creates an application main window of the correct size and obtains the GTK and X window handle and the X display. Besides, the event mask is set, the GTK event handlers installed, the common event queue is set up and the GTK and IPC event loop threads are created.

Parameters:
prgname Name or path of the command as which this application was started. If this is not correct, the application will fail to receive most GTK events for unknown reasons. Pass argv[0] here.
Returns:
0 OK, != 0 error. In the latter case, the application should terminate.
void app_wait_event ( iliad_event ev  ) 

Return next event from the event queue.

If no event is available, this function blocks until there is.

Parameters:
ev pointer to write event struct to
GtkWidget* app_window (  ) 

Returns the GTK handle of the application window.

app_init() must have been called successfully before this function can be used.

Display* app_xdisplay (  ) 

Returns the X display.

app_init() must have been called successfully before this function can be used.

Window app_xwindow (  ) 

Returns the X handle of the application window.

app_init() must have been called successfully before this function can be used.

int sync_bars ( int  mask  ) 

Synchronise with toolbar and/or pagebar.

Send synchronise messages to toolbar and/or pagebar and wait for receipt of synchronise events from them. Times out after approximately one second. This works only via the reporting of sync events by evq_ipc() and therefore requires app_init() to have been called before.

Synchronising with the tool/pagebar seems to cause their latest event to be resent. It is apparently not necessary for ensuring their region of the display is updated.

Parameters:
mask Bit mask; generate from SYNC_TOOLBAR and SYNC_PAGEBAR
Returns:
SYNC_ERROR if a synchronise message could not be sent, otherwise SYNC_OK or SYNC_TIMEOUT.