X windows Isis software documentation

X windows

This library creates a simplified interface for using the X windows system in Isis. Windows can be created and manipulated, images can be displayed in them, and input can be received in the form of events or by polling.

As usual, all sizes and positions given as arguments to the following procedures are specified in lists. For example, to indicate a size of 320 in the X direction (horizontal) and 240 in the Y direction (vertical), you would enter: [320 240]


Creating and destroying windows

(xwin-create displayname title pos size maxsize dither-type show-now-flag) (xwin-child parent-xwin pos size show-now-flag) (xwin-destroy xwin) xwin-create creates an X window on a particular display screen. It accepts up to 7 arguments, but none are required. In order, the arguments are: display server name, window title, window position, window size, maximum window size, type of dither (used for 8-bit displays only), and an boolean representing whether the window should be opened immediately. The arguments must be specified in this order, but if Null is passed for any argument, or if less than seven arguments are passed, default values will be used for those arguments.

If displayname is Null, the window is created on the default display (whatever your DISPLAY environment variable is set to). The dither-type argument may be dither-decimate, dither-ordered, or dither-diffusion. When show-now-flag is False, you must explicitly open the window using the xwin-show procedure described below.

xwin-child creates a child window inside of a previously-created window. It accepts up to 4 arguments, and only the first is required: parent window handle, window position, window size, and a boolean specifying whether the window should be opened immediately. Again, default values are used if any argument is not specified or is Null.

Both xwin-create and xwin-child return a window "handle" that should be used in all future operations involving the new window. When the window is no longer needed, xwin-destroy should be called on it to release any associated memory.

For example, the following creates a 512 x 512 window on the default display, entitled "Ian":

(set win1 (xwin-create Null "Ian" Null [512 512]))
The following creates a 320 x 240 window that can be resized up to 640 x 480, on the display named "gibsons:0.0", with the title "Alexandra":
(set win2 (xwin-create "gibsons:0.0" "Alexandra" Null [320 240] [640 480]))
The following creates a 50 x 50 child window inside of win2, at position [100 100] relative to win2's origin:
(set win3 (xwin-child win2 [100 100] [50 50]))
Passing no arguments to xwin-create (using all the defaults) would be equivalent to the following call:
(xwin-create Null "Isis" [0 0] [640 480] [640 480] dither-decimate True)


Displaying images

(xwin-display-image xwin image pos) # postion is optional (xwin-display xwin pos size [rbuf gbuf bbuf] steps) (xwin-display-interleaved xwin pos size databuf steps) xwin-display-image displays an Isis image buffer in the specified window. An optional position may be specified as well.

xwin-display may be used to display image data that is not in the Isis image buffer protocol format. It displays image data directly from the specified RGB data buffer addresses. steps should be a list of two integers [xstep ystep] indicating the distances in bytes from the current sample to the next horizontal and vertical samples.

xwin-display-interleaved is similar to xwin-display except the RGB image data must already be interleaved properly in databuf. Each pixel is represented in 32-bits. The configuration of red, green, and blue values inside this 32 bits must match that of the X server that will be displaying the image. This prevents any costly format conversion, so this function is the most efficient way to display image data. However, it will not work on 8-bit displays.

The following example opens an X window, creates an Isis image, clears the image to a particular color, and displays it in several places in the window.

(set win (xwin-create)) (set image (new-standard-image 3 [100 150])) (image-fill-constant 255 (isolate-channel 0 image)) (image-fill-constant 128 (isolate-channel 1 image)) (image-fill-constant 0 (isolate-channel 2 image)) (xwin-display-image win image) # displays at [0 0] (xwin-display-image win image [142 269]) (xwin-display-image win image [500 300])


Window attributes

(xwin-get-size xwin) # returns current window size (xwin-get-location xwin) # returns current window location (xwin-show xwin) # open or show the window (xwin-hide xwin) # close or hide the window (xwin-move xwin pos) # move window to a new position (xwin-resize xwin size) # change size of window (xwin-title xwin title) # set window title These procedures query and set various window attributes. They are mostly self-explanatory.


Polling input devices

(xwin-pointer-inside xwin) # checks if pointer in boundaries (xwin-pointer-location xwin) # position relative to upper left (xwin-poll-all-actuators xwin) # [left mid right shift control alt caps] (xwin-poll-actuator xwin act-num) These functions check the status of the pointer, mouse buttons, and modifier keys. The word actuator is used collectively to represent mouse buttons or modifier keys (shift, control, alt, caps lock).

xwin-pointer-inside checks if the pointer is inside the boundaries of the specified window and returns a boolean value. It does not check to see if there is another window in front of the window of interest. xwin-pointer-location returns the pointer position relative to the origin of the specified window (values may be negative).

xwin-poll-all-actuators returns a list of seven integers representing the values of the seven recognized "actuators": left, middle, and right mouse buttons, and the shift, control, alt, and caps lock keys. A value of 1 indicates the button or key is pressed, and 0 means it is not pressed. xwin-poll-actuator polls a specific actuator (numbered 0-6).

For example, the following function is called while the left mouse button and the shift key are being held down:

-> (xwin-poll-all-actuators win) [ 1 0 0 1 0 0 0 ]


Processing events in windows

(xwin-select-events xwin event-type ...) (xwin-get-event xwin { event-type ... }) # return event immediately (xwin-wait-for-event xwin { event-type ... }) # block and wait for event (xwin-event-pending xwin { event-type ... }) # check if event pending (xwin-dump-events xwin { event-type ... }) # flush queued events xwin-select-events allows you to indicate that you would like to receive "events" notifying you about up to six different kinds of activity in a window. The arguments are the window handle and a variable number of event types. The event type constants that may be passed are: event-pointer-in-window event-pointer-location event-actuator event-window-geometry event-character event-expose event-none If event-none is passed, event processing is turned off (which is the default). Once xwin-select-events has been called, the window will begin queueing the specified types of events. The selected event types can be changed at any time by just calling this procedure again.

To actually receive an event, use xwin-get-event or xwin-wait-for-event. Both of these procedures accept a window handle and a variable number of event types as arguments. They check the event queue to see if any events of the specified types have occurred. The first match will be returned. If no event type is passed to the procedure, then the first event of any of the originally selected kinds is returned. If no event is available, xwin-get-event will immediately return an event of type event-none, but xwin-wait-for-event will block and wait until an appropriate event arrives before returning it.

Events are returned as a list with the event type as its first element. You can use this first element to switch processing based on the event type. The format of the rest of the list will vary depending on the event type, as outlined below:

[ event-pointer-in-window in-window-flag pointer-location actuator-list ] [ event-pointer-location pointer-location actuator-list ] [ event-actuator actuator-num actuator-value pointer-location actuator-list ] [ event-window-geometry new-window-location new-window-size ] [ event-character character-pressed pointer-location actuator-list ] [ event-expose rectangle-location rectangle-size ] [ event-none ] in-window-flag is a boolean representing whether the pointer is now inside the window. pointer-location represents the location of the pointer at the time of the event. actuator-list is a list of seven integers representing the values of all the actuators at the time of the event (same format as used by xwin-poll-all-actuators). rectangle-location and rectangle-size represent the area of the window that has been exposed and needs to be redrawn. The rest of the items in these lists should be fairly self-explanatory.

xwin-event-pending and xwin-dump-events take arguments in the same format as described above. xwin-event-pending simply returns True if at least one event of the specified types (or any of the originally selected types if no types are given) has occurred and is waiting to be received, and False otherwise. xwin-dump-events deletes all the events of the specified types (or all events if no types are given) from the specified window's event queue.

In the following example, a window is created and all types of events are selected in it. An infinite loop is established simply receiving and displaying the return values of xwin-wait-for-event. Notice that the first element in each event list is an integer that will match one of the pre-defined event type constants. Try this test for yourself to get a feel for how X window events are returned.

-> (set win (xwin-create)) 0x3a6008 -> (xwin-select-events win event-pointer-in-window event-pointer-location event-actuator event-window-geometry event-character event-expose) Null -> (while True (display (xwin-wait-for-event win))) [ 1 True [ 337 479 ] [ 0 0 0 0 0 0 0 ] ] [ 2 [ 337 478 ] [ 0 0 0 0 0 0 0 ] ] [ 2 [ 329 466 ] [ 0 0 0 0 0 0 0 ] ] [ 2 [ 326 464 ] [ 0 0 0 0 0 0 0 ] ] [ 4 1 1 [ 326 464 ] [ 0 0 0 0 0 0 0 ] ] [ 4 1 0 [ 326 465 ] [ 0 1 0 0 0 0 0 ] ] [ 16 'q' [ 326 465 ] [ 0 0 0 0 0 0 0 ] ] [ 16 '*' [ 326 465 ] [ 0 0 0 1 0 0 0 ] ] [ 1 False [ 332 489 ] [ 0 0 0 0 0 0 0 ] ] [ 8 [ 0 21 ] [ 471 320 ] ] [ 1 True [ 306 107 ] [ 0 0 0 1 0 1 0 ] ] [ 2 [ 307 101 ] [ 0 0 0 1 0 1 0 ] ] [ 2 [ 308 96 ] [ 0 0 0 1 0 1 0 ] ] [ 2 [ 308 94 ] [ 0 0 0 1 0 1 0 ] ] [ 4 2 1 [ 308 94 ] [ 0 0 0 1 0 1 0 ] ] [ 4 2 0 [ 308 94 ] [ 0 0 1 1 0 1 0 ] ] ...


Requirements:
Scripts: (load "xwin-helpers.isis")
Libraries: -lisis_xwin -lX11
Headers: isis_xwin.h
Binders: bind_xwin_library(script);


written by: Ann Bui and Stefan Agamanolis