A window descriptor is a lisp object of class |WINDOW| . Most graphical commands implicitely operate on the current window defined by the window descriptor stored in the symbol window .

Each window descriptor forwards all drawing requests to a ``Graphic Driver'' which performs the system dependent calls required to display the drawings on the corresponding device. The most common type of window (and driver) is the x11-window , which displays on your screen under Xwindows. Another one is the ps-window which sends all graphic command to an Encapsulated PostScript file. A particularly useful one is the comdraw-window which sends graphics to a comdraw graphic editor. This type of window can be used to produce "editable" graphics that can be modified using comdraw of one of the other applications of the ivtools package.

Function print-window performs the same task for creating a window descriptor that accesses your printer.

This is the device independent function for creating a window. It figures out which drivers are available, and call the appropriate function for creating a window.

Function new-window function creates a window named name . Arguments w and h specify the size of the window. Arguments x and y specify the location of the window.

The resulting window descriptor is then stored into variable window . This operation makes the window current.

Windows are closed when they are no longer referenced by the lisp interpreter, when they are deleted with the delete function, or when the windowing system sends a deletion request.

This is the device independent function for printing graphics on the system printer. This function figures out the best way to send graphics on the printer or the file specified by string destination . Arguments w and h specify the size of the printing area. The drawings will be scaled to fit a standard size page.

The resulting window descriptor is then stored into variable window . This operation makes the window current.

Function print-window actually calls a system dependent function (e.g. wpr-window under Windows 95 and NT, ps-window under Unix operating systems). Argument destination is passed verbatim to these functions. There are therefore two ways to write a portable program. The simplest way consists in omitting argument destination . The best way consists in using the PrintRequester class provided with the Ogre library.

The window descriptors returned by print-window are very similar to the window descriptors returned by new-window . They print pages instead of rendering graphics on your screen. A page is output when you call function cls or when the window descriptor is closed (because it is no longer referenced by the interpretor or because you called function delete ).

Note: Calling function cls while a clip rectangle is active (see function clip ) will not output a page. It will simply clears the clipping zone. Before using cls , you can use function clip to make sure that no clipping rectangle is active.

This function displays the pixels contained in idx mat at location ( x , y ) in the current window. The optional arguments sx and sy specify the horizontal and vertical zoom factors.

The matrix mat can be an idx2 or idx3. If it is an idx2 , each value is interpreted as a greyscale value where 0 is black and 255 is white. If it is an idx3 , the last dimension must be 1 , 3 , or more. If the last dimension is 1 , the values are interpreted as greayscale values. If the last dimension is 3 or more , the first 3 values in the last dimension are interpreted as RGB intensities (between 0 and 255).

Arguments x and y are the coordinates of the center of the square. Argument val is the value to be displayed. Argument maxv is the maximum absolute value for val . Argument maxs is the maximum size of the square. When val is larger than maxv , a square of size maxs is drawn.

Note: The square will not be visible if it is drawn in the same color as the background.

Arguments x and y are the coordinates of the top left edge of the background area. The squares are arranged in an array with ncol columns, the number of lines is then defined by the length of the list l . The grey background is always rectangular, even if ncol is not a divisor of the length of l .

As with draw-value , argument maxv is the maximum absolute value for the list elements. The size of the square is however bounded by maxs .

Argument apart defines the size of the space occupied by a single square, i.e, the centers of two neighboring squares will be apart pixels apart. It is generally suitable to choose a value for apart slightly greater than maxs so that no squares will overlap. For best results, the difference between apart and maxs should be an even number.

Example:

 ; draw 6 values on 3 columns and 2 lines, in 50 pixel squares
 (draw-list 50 50 '( 4 5 -10 
                     0 4  16 ) 3 16 52 50)
 ; draw the values in l on a single line
 (draw-list 100 100 l (length l) 10 20 18)

Arguments x and y are the coordinates of the topleft edge of the first square (representing the first element in the list). The squares are arranged in an array with ncol columns , the number of lines is defined by the length of the list l .

Values between minv and maxv will be displayed as gray levels. A value of minv will be rendered as a black square. A value of maxv will be rendered as a white square. Argument minv can be defined to be greater than maxv in order to produce a reverse video effect. The sizes of the squares are defined by the apart parameter.

Arguments x and y are the coordinates of the topleft edge of the first square (representing the first element in the list). The values between minv and maxv will be displayed as gray levels. A value minv will be rendered as a black rectangle. A value maxv will be rendered as a white rectangle. Value minv can be defined to be greater than maxv in order to produce a reverse video effect. The sizes of the rectangles are defined by the apartx and aparty parameter.

The function draw-mat computes statistical information about the matrix values in order to adjust the gray scales. This function automatically creates a window if no window is current when the function is called.

This function is essentially similar to gray-draw-list . Argument cmap however must be a one-dimensional matrix of 64 color numbers returned by alloccolor . Values between minv and maxv are rendered using the ramp of colors specified by this matrix.

This function is essentially similar to gray-draw-matrix . Argument cmap however must be a one-dimensional integer matrix of 64 color numbers returned by alloccolor . Values between minv and maxv are rendered using the ramp of colors specified by this matrix.

• There are still computers equipped with black and white screens. You can check that your hardware can display enough colors using function colorp .
  
• Many graphic devices use color palettes. The color palette defines a small set of colors that can be displayed simultaneously on the screen. Lush will allocate palette entries as soon as you start using a new color. Since palette entries are rare resources, you should use colors cautiously.
  

Lush provides two elementary functions for dealing with colors. Function alloccolor takes a set of three numbers (ranging from 0 to 1) representing the red, green and blue component of the color. This function allocates a palette entry if necessary and returns a hardware dependent color number. These color numbers can be used with function color to set the current drawing color.

It happens sometimes that it is not possible to allocate a color because the color palette is full. Lush will first try to create its own color palette and install it whenever you activate a Lush window. Windows created by other programs can display funny colors until you activate one of these windows. If the private color palette is full, function alloccolor simply returns a default color.

The use of a limited number of colors is therefore highly encouraged. The function color-stdmap provides several convenient sets of standard colors for this purpose.

See: Ogre Color Palette.

• color-fg or -1 for the system foreground color.
  
• color-bg or -2 for the system background color.
  
• color-gray or -3 for a 50 percent dithered gray level.

  
  

Ask the driver for a color number defined by its three primitive values. Arguments r , g , b are reals between 0 and 1 that define the red, green and blue components of the desired color.

Returns a color number suitable for using with the color function. This function returns the constant color-gray if the system is not able to display the requested color.

Using this function maximizes the chances that several part of your Lush programs will use the same palette entries and therefore avoid palette saturation.

The argument symb is a symbol which specifies ont of the predefined color sets:

• Symbol rainbow defines 64 colors located on a circle linking the pure red, green and blue hues. The first 48 colors actually represent a rainbow. The last 16 colors directly interpolate purple to red.
  
• Symbol spread defines 7 colors that are easy to discriminate.
  
• Symbol shade defines a set of 64 gray levels going from black to white.

  
  

• Argument x is number whose decimal part selects a color in the set returned by function color-stdmap . Value 0 selects the first color of the set. Value 0.9999 selects the last color of the set.
  
• Optional argument symb is a symbol which specifies a color set for function color-stdmap .
  

Function gprintf behaves like function printf , but prints out the text on the current graphic window, with the current font and color, starting at location ( x , y ).

Function font sets the font used for rendering characters in subsequent calls of function draw-text . It always returns the current font name.

Font "default" is recognized by all the drivers, and sets a reasonably small default font. Always using font "default" is the only guaranteed way to write fully portable programs.

All drivers however recognize PostScript(tm) style font names. These font names have the following form:

    "<family>[-<style>][-<size>]"

• The recognized font family family usually depends heavily on the operating system configuration. It is reasonable to assume that the basic families "Times" , "Helvetica" and "Courier" are available (or translated) everywhere.
  
• The optional style is preceded by a dash. Style "Roman" lets you print plain text. More complex style are composed by concatenating an optional weight specification (e.g. Light , DemiBold , Bold , Black , etc...) and an optional slant specification (i.e. Italic or Oblique ).
  
• The optional size is a number between 1 and 128.
  

Not all combination of families, styles and size are supported on all systems. A good compromise between fancy display and portable graphics consists in using PostScript font names, but to limit yourself to the following fonts:

    Courier-X, Courier-Bold-X, Courier-Italic-X, Courier-BoldItalic-X
    Times-Roman-X, Times-Bold-X, Times-Italic-X, Times-BoldItalic-X,
    Helvetica-X, Helvetica-Bold-X, Helvetica-Oblique-X, 
    Helvetica-BoldOblique-X, Symbol-X

where size X is one of 8 , 10 , 11 , 12 , 14 , 18 , 24 .

Most drivers also understand window system dependent font names (when such font names are defined by the window system). For instance, the X11 driver recognizes all font names listed by the utility program xlsfonts . These font names are very long, but a star * can be used as a wildcard character. A typical example is "-*-times-*medium-*r-*--18-*" . Function x11-fontname can be used to translate a Postrscript(tm) style font name into a system specific font name.

A few driver , including the PS driver , do not implement this function. In that case , rect-text returns the empty list.

Returns the width of the text in string s , if it is printed with the current font. This function uses rect-text if it is available, or uses some crude heuristics.

• (clip x y w h) sets a new clip rectangle whose top left corner is located at position ( x , y ), whose width is w , and whose height is h .
  
• (clip ()) cancels clipping and unset the clipping rectangle.
  
• (clip) just returns the current clipping rectangle.
  

Function (clip) always returns the previous clip rectangle, as a list (x y w h) , or the empty list if no previous clipping rectangle was set.

Function addclip sets the current clip rectangle to the intersection of the current clipping rectangle with a rectangle whose top left corner is located at position ( x , y ) , whose width is w , and whose height is h .

If this intersection is empty , the empty list is returned. Otherwise , addclip returns the new clip rectangle.

This function evaluates the lists l1 to ln , but if a graphic instruction is executed , the screen update is delayed until the end of these evaluations , and is performed only once.

Functions in the present section are maintained for backward compatibility, but their use should be avoided.

The following functions provide a way to plot curves. The basic abstraction is the plot port data structure, a Lush list which contains:

• The position of the current point,
  
• A pointer to the graphics window,
  
• Information for mapping real coordinates to pixel positions.
  

The plotting functions perform their drawing action in the current plot port. Function, setup-axes is provided for quickly initializing a plot port, making it current and drawing the axes.

Currently, plot ports are implemented as lists rather than a user defined class. In fact, the "graphenv.lsh" package has existed prior to the object extensions of Lush. This silly implementation has been kept for preserving backwards compatibility.

Argument brect is a list (bxmin bymin bxmax bymax) whose elements are the pixel coordinates of the target rectangle in the current window.

Argument rect is a list (xmin ymin xmax ymax) whose elements are the extremal real coordinates. No clipping is performed, except window clipping.

Argument object is a function generally called by plt-plot for drawing a small object at the current pen location. A few predefined functions are documented with plt-plot .

Argument brect is a list (bxmin bymin bxmax bymax) whose elements are the pixel coordinates of the target rectangle in the current window.

Arguments xl and yl are lists of label values for the x and y axis. These labels are numbers expressed with the same scale than the axes. The optional functions x2l and y2l are used to convert these numbers into strings to display at the proper positions along the axes. Both functions default to str which just prints the textual representation of the number.

Finally, argument name is a string that will be printed at the top of the brect using a 18 points font.

Arguments x1 and y1 are the lower bounds of the actual coordinates; arguments x2 and y2 are the upper bounds of the actual coordinates. The axes will be labeled every xst units horizontally and every yst units vertically. Argument s is a string that will be printed at the top of the window. object is the default plot object used by plt-plot .

When arguments xst or yst are not provided (or are the empty list), function setup-axes computes a reasonable value using the extrema.

This function uses uses plt-draw , plt-sd and plt-plot to draw a symbol and an uncertainity bar at each data point.

The shape of this symbol is defined by the argument object of new-plot-port or setup-axes . this argument must be a function that draws the object at the specified position. The following functions are predefined:

• object-nil does nothing. It is useful if you want cancel the effect of plt-plot .
  
• open-square , closed-square , open-circle , and closed-circle respectively draw a small hollow square, a small filled square, a small hollow circle or a small filled circle.
  
• open-up-triangle , closed-up-triangle , open-down-triangle , closed-down-triangle , draw various kind of small triangles.
  
• straight-cross and oblique-cross draw small crosses.
  

All these predefined object functions use the global variable object-size for defining the size of the object drawn by plt-plot . The default object may be overridden by setting the variable current-object to a new object function.

Several functions are provided for handling mouse and keyboard events occurring on graphic windows. Lush has a centralized event queue (see a full description in the Events and Timers section). It is possible to obtain the events occuring on a window by creating an EventLock object. Messages read-event and check-event allow for testing and waiting for events.

This mechanism is used by a few handy functions get-click , get-vector and get-rect , as demonstrated by the incredibly shrinking paint program lushpaint below:

(de lushpaint()
    (let ((window ()))
      (new-window)
      (draw-line 2 5 18 5)
      (draw-rect 22 2 18 8)
      (fill-rect 42 2 18 9)
      (gprintf 102 10 "Quit")
      (clip 0 12 1000 1000)
      (let ((ok t)
           (mode draw-line)
           (echo get-vector))
       (while ok
          (let (((x y) (get-click)))
            (cond
             ((> y 10)
              (apply mode (echo)) )
             ((point-in-rect x y '(0 0 20 10))
              (setq mode draw-line echo get-vector) )
             ((point-in-rect x y '(20 0 20 10))
              (setq mode draw-rect echo get-rect) )
             ((point-in-rect x y '(40 0 20 10))
              (setq mode fill-rect echo get-rect) )
             ((point-in-rect x y '(100 0 20 10))
              (setq ok ()) )) ) ) )
      (delete window) ) )              

(NOTE: more serious paint programs should probably be written with Ogre).

The initial state of the window is restored when the EventLock object is destroyed.

This function returns the first available event on the window associated to the EventLock object. Each event is represented by a list whose first element broadly describes the event type. Additional information can be obtained using function eventinfo .

If the event queue is empty, this function blocks until an event occurs.

This function returns the first available event on the window associated to the EventLock object. Each event is represented by a list whose first element broadly describes the event type. Additional information can be obtained using function eventinfo .

This function returns the empty list when no events are available.

Four kinds of drawings are supported, whose names are defined by "graphenv.lsh" :

• When mode is hilite-invert , the rectangle defined by the points ( x1 , y1 ) and ( x2 , y2 ) is inverted. The result however is poor on color displays.
  
• When mode is hilite-rect , the rectangle defined by the points ( x1 , y1 ) and ( x2 , y2 ) is outlined with a dashed line.
  
• When mode is hilite-line , a dashed line is drawn from point ( x1 , y1 ) to point ( x2 , y2 ).
  
• When mode is hilite-none , any transient graphics are cleared, and the window is refreshed.
  

Transient drawings created with hilite are very efficient, and totally disappear when the mouse button is released. This function is useful for providing an echo to the user during a mouse drag operation. For example, function hilite can display a rectangular outline while the user is dragging the mouse for selecting a part of an image.

The optional argument rect indicates a bouding rectangle which must entirely contain the resulting vector. The echoed dashed line reflects then this limitation.

The optional argument rect indicates a bouding rectangle which must entirely contain the resulting rectangle. The echoed dashed rectangle reflects then this limitation.

Events returned by methods read-event and check-event are encoded as lists, according to the following templates:

• (mouse-down x y) : The mouse button has been depressed at position ( x , y ). You may use function eventinfo to query the identity of the button and the status of the shift and control keys.
  
• (mouse-drag x_1 y_1 x_2 y_2) : The mouse button has been depressed at position ( x1 , y1 ).The mouse has then been moved to position ( x2 , y2 ). The mouse button still is depressed. You may use function eventinfo to query the identity of the button and the status of the shift and control keys.

  
  

• (mouse-up x_1 y_1 x_2 y_2) : The mouse button has been depressed at position (x_1,y-1). The mouse has then been moved to position (x_2,y_2), where the button has been released. You may use function eventinfo to query the identity of the button and the status of the shift and control keys.
  
• ("c" x y) : The key associated to the single character string "c" has been hit, while the mouse pointer was located at position ( x , y ). These events often are referred as keypress events.
  
• (arrow-left x y) , (arrow-right x y) , (arrow-up x y) or (arrow-down x y) : The left (respectively right, up and down) arrow has been hit, while the mouse pointer was located at position ( x , y ). You may use function eventinfo to query the exact identity of the depressed key and the status of the shift and control keys.
  
• (help x y) : The keyboard dependent help key has been hit, while the mouse pointer was located at position ( x , y ). You may use function eventinfo to query the exact name of the depressed key and the status of the shift and control keys.
  
• (fkey x y) : A function key has been depressed. You must use function eventinfo to get more information about the identity of the function key and of the status of the shift and control keys.
  
• (resize w h) The window has been resized by the user, and is now w x h pixels large.
  
• (delete) : Windowing systems often provides a mean to delete a window. For example, X11 ICCM compliant window managers are able to send a WM_DELETE message to a client. If an event handler is attached to the window, a delete event is added to the event queue, and the window is not destroyed. A program thus gets a chance to display a confirmation dialog before deleting the window.
  
• (sendevent x y) : These event is generated by function sendevent . Integer values x and y are arbitrary.
  

These few events give enough information for building graphics interfaces. The class library "libogre/ogre.lsh" is designed for that purpose.

This is the low level function called by new-window on X Windows systems.

This function creates a window of size w and h at position x and y named name on the default X Windows screen. During the first call of function x11-window , Lush searches the variable display and the environment variable DISPLAY for the name of the X Windows server and display to use.

Unlike new-window , this function does not store the newly created window in the variable window , and thus does not make this window current.

This function comes with the X11 driver. It converts a legal PostScript(TM) font name, into a X11 font name.

String s must be a legal PostScript font name, composed of a font family, an optional font style, and a font size, possibly separated by dashes, like "Helvetica-18" , "Times-Roman24" , "Courier-Bold-12" . This function returns the corresponding font name under the X11. conventions.

Example:

? (when x11-fontname
    (x11-fontname "Times-Roman18") )
= "-*-times-medium-r-normal-*-18-*"

This function works only with X11R4 or greater. When effective , it returns a list (visible w h) whose elements indicate the window visibility and size.

It implements today a cut buffer based mechanism suitable for exchanging text with emacs and xterm. We plan to support selection as soon as possible.

It implements today a cut buffer based mechanism suitable for exchanging text with emacs and xterm. We plan to support selection as soon as possible.

The following functions are only implemented on Windows

This is the low level function called by new-window on Windows 95 and NT systems. This function is available under WinLush only.

Function wbm-window creates a window of size w and h at position x and y named name in the WinLush environment. The command line version of Lush cannot create graphic windows yet.

Unlike new-window , this function does not store the newly created window in the variable window , and thus does not make this window current.

This function is very similar to function wbm-window described above. Instead of creating a child window of the main WinLush window (according to the Windows MDI scheme), function wbm-toplevel-window creates a toplevel window that is not attached to the main WinLush window.

This is the low level function called by print-window on Windows 95 and NT systems.

Function wpr-window creates a window descriptor which actually accesses the printer named name . The default printer is used if argument name is not specified. Function wpr-printers should be used to obtain the list of valid printer names.

Unlike new-window or print-window , this function does not store the newly created window in the variable window , and thus does not make this window current.

Arguments w and h specify the width and height of the coordinate system. The drawings will be scaled to fit the size of the page returned by your printer.

This function returns a list of printers names suitable for function wpr-window . The default printer name comes first.

This function returns a list (visible w h) whose elements indicate the window visibility and size.

• When opt is symbol loose , this function always returns a function. It returns the feature function as soon as a partial implementation exists. It returns function progn if the feature is not implemented.

  This option is usefull for calling minor services (e.g. puting text into the clipboard) for which failure has little consequence.
  

• When opt is symbol strict , this function returns a function if and only if the feature is fully implemented. It returns the empty list otherwise.
  

Features are the following.

• depth : This feature is a generalization of x11-depth .
  
• text-to-clip : This feature is a generalization of x11-text-to-clip .
  
• clip-to-text : This feature is a generalization of x11-clip-to-text .
  
• configure : This feature is a generalization of x11-configure .
  
• fontname : This feature is a generalization of x11-fontname .
  
• lookup-color : This feature is a generalization of x11-lookup-color .
  

Here is an example of the use which can be made of gdriver-feature .

? (new-window 400 400 400 400 "test")
= ::WINDOW:X11:8c440
? ((gdriver-feature 'configure 'loose) () 300 300 400 400)
= (t 400 400)

Note: Many computers use incompatible conventions for marking the end of lines (Unix machines use the character NL , Macs use the character CR and PC use a sequence CR NL.) Several popular software exhibit a strange behavior when they attempt to read a sequence of characters which appears to them as a very long line. You must probably use a text filter like dos2unix to convert your EPS files.

Function ps-window is the low level function called by print-window on systems that provide no other alternative. All versions of Lush however support Encapsulated PostScript files.

Function ps-window returns a window descriptor which actually writes PostScript commands into a file named name . When argument name is omitted, the PostScript commands are written to file "tloutput.ps" .

Unlike new-window or print-window , this function does not store the newly created window in the variable window , and thus does not make this window current.

Arguments w and h specify the width and height of the coordinate system. The target rectangle will be scaled to fit a standard A4 or Letter format page.

This function interprets PostScript files created with ps-window . Function ps-play parses the PostScript file filename , converts it into a sequence of SN calls, and applies function function to these calls. The default value for the optional argument function is eval . Function ps-play thus plays the contents of the PostScript file in the current window.

Exemples:

To play a EPS file into a window, type:

? (let ((window (new-window)))
   (ps-play "your_file.ps") )

To see the contents of a EPS file, type:

? (ps-play "your_file.ps" pprint)

Note: This function only interprets PostScript files created by the Lush PostScript driver. It is by no means a complete PostScript interpreter.

This function plots EPS-files created with SN or Lush in the window referred to by the symbol window in the region determined by x y w and h . x y correspond to the coordinates of the region's upper-left corner, w to its width and h to its height. The plot is scaled to fill exactly this region using the EPS "%%BoundingBox" directive which can be overruled by the optional bb-overrule parameter. If w or h are 0 or nil, scaling in their respective directions are choosen as to preserve proportions. If both w and h are 0 or nil, no scaling is performed.