The Window Tool Kit

8 Reference Pages

activate-viewport Function

deactivate-viewport Function

Syntax:activate-viewport viewport&key :activate-children

Syntax:deactivate-viewport viewport

The functionactivate-viewport makes the specified viewport and all of its ancestors active. If the:activate-children keyword argument has a non-nil value, all of the viewport's descendants are also made active.

The functiondeactivate-viewport makes the specified viewport and all of its descendants inactive. The viewport viewport maintains its position in the display stack of its siblings. However, the viewport and its descendants do not appear on the screen until they are reactivated.

If a viewport is active, all of its ancestors are active. If a viewport is inactive, all of its descendants are inactive.

Ifdeactivate-viewport tries to deactivate a viewport that is already inactive, nothing happens.

Ifactivate-viewport tries to activate a viewport that is already active, nothing happens.

Syntax:active-region-bitmap active-region

The functionactive-region-bitmap returns the bitmap to which the argument active-region is attached. If active-region is not attached to a bitmap, it returnsnil.

Syntax:active-region-method active-region event-name

The functionactive-region-method accesses the method that is called when a mouse event occurs inside an active region or when the mouse enters or leaves an active region. The function returnsnil if no method is associated with the event.

The event-name argument must be one of the following mouse events::mouse-click,:mouse-transition,:mouse-moved,:mouse-enter-region, or:mouse-exit-region.

Thesetf method for this function updates the appropriate method. If you set the value tonil, no method is called when the corresponding mouse event occurs.

The method is called with the following sequence of arguments:

• the viewport on which the mouse event occurred

• the active region

• the mouse event character

• the x-coordinate of the position on which the mouse event occurred

• the y-coordinate of the position on which the mouse event occurred

The x- and y-coordinates are given relative to the origin of the active region's bitmap. For all mouse events except:mouse-exit-region, the x-coordinate and y-coordinate arguments specify a position inside the active region. For:mouse-exit-region, the specified position lies outside the active region; it can also lie outside the bitmap.

If the mouse's projected position on the viewport's bitmap falls inside one or more active regions, the following methods are invoked in the order given:

• If the mouse has exited an active region, the active region's exit method is invoked.

• If the mouse has entered an active region, the active region's entry method is invoked.

• If the mouse is inside one or more active regions, each active region's method for the event is invoked.

Note: An active region method is called inside the system's interrupt handler; no other user interrupts are permitted while the function is running. If your method has an infinite loop, there is no way to interrupt it.

Syntax:active-region-mouse-documentation region

The functionactive-region-mouse-documentation returns a function that takes an active region as a single argument and returns the mouse documentation for a specified active region.

You can use the Common Lisp macrosetf with this function to alter the mouse documentation associated with an active region.

The documentation is printed in the who window.

Syntax:active-region-p object

The predicateactive-region-p tests whether its object argument is an active region. It is true if object is an active region.

Syntax:active-region-user-data active-region

The functionactive-region-user-data returns the information that is specified in the:user-data keyword argument tomake-active-region.

The active-region argument specifies the active region that contains the user data.

You can use the Common Lisp macrosetf with this function to alter the contents of the:user-data argument.

See Also: make-active-region

deallocate-color Function

Syntax:allocate-color

Syntax:deallocate-color color-sequence

The functionallocate-color allocates and returns a single entry in the system color map if a free entry exists. The returned entry will be in the range from 0 to(1- (color-map-size)) inclusive. If there are no more free entries in the color map,allocate-color returnsnil.

The functiondeallocate-color deallocates the specified color or color number previously allocated by the functionallocate-color.

The color-sequence argument todeallocate-color can contain a single color or color number, or a sequence of either. If the color number is successfully deallocated, the color number is returned. If the color number has not been previously allocated and thus cannot be deallocated,nil is returned.

It is not an error to deallocate a color number that has not been allocated.

> (allocate-color)
22

> (deallocate-color 22)
22

detach-active-region Function

bitmap-active-regions Function

clear-bitmap-active-regions Function

Syntax:attach-active-region bitmap active-region

Syntax:detach-active-region active-region

Syntax:bitmap-active-regions bitmap

Syntax:clear-bitmap-active-regions bitmap

These functions attach and detach active regions from bitmaps.

• attach-active-region attaches an active region to a bitmap.

• detach-active-region detaches an active region from its bitmap.

• bitmap-active-regions returns a list of all the active regions that are attached to a bitmap.

• clear-bitmap-active-regions detaches all active regions that are attached to a bitmap.

When you attempt to attach an active region to a bitmap, the active region must be located in the bitmap.

Ifdetach-active-region is called with an active region that is not attached to a bitmap, nothing happens.

bitblt-position Function

bitblt-region Function

Syntax:bitblt source-bitmap source-x source-y destination-bitmap destination-x destination-y width height operation&key :clipping-region :foreground :background :pixel-map

Syntax:bitblt-position source-bitmap source-position destination-bitmap destination-position width height operation&key :clipping-region :foreground :background :pixel-map

Syntax:bitblt-region source-bitmap source-region destination-bitmap destination-region operation&key :foreground :background :pixel-map

These functions copy regions in bitmaps.

• bitblt copies regions from one bitmap to another.

• bitblt-position is similar tobitblt, except that the locations in each bitmap are expressed as positions rather than as x- and y-coordinates.

• bitblt-region is similar tobitblt, except that the arguments explicitly specify the source and destination regions.

The source-bitmap and destination-bitmap arguments specify the bitmap from which the copying is performed and the bitmap to which the copying is done respectively. You can specify the same bitmap for both arguments. If both bitmaps are not of equal depth or if source-bitmap is not of depth 1, you must supply the:pixel-map keyword argument.

The source-bitmap region that is copied is specified by the following arguments:

• The source-x, source-y, width, and height arguments ofbitblt. The source-x and source-y arguments specify the x- and y-coordinates respectively of the region's origin. The width and height arguments specify the region's width and height respectively.

• The source-position, width, and height arguments ofbitblt-position. The source-position argument specifies the position of the region's origin. The width and height arguments specify the region's width and height respectively.

• The source-region argument ofbitblt-region.

The destination-bitmap region that is to be modified is specified by the following arguments:

• The destination-x, destination-y, width, and height arguments ofbitblt. The destination-x and destination-y arguments specify the x- and y-coordinates respectively of the region's origin. The width and height arguments specify the region's width and height respectively.

• The destination-position, width, and height arguments ofbitblt-position. The destination-position argument specifies the position of the region's origin. The width and height arguments specify the region's width and height respectively.

• The destination-region argument ofbitblt-region.

Each position in the source bitmap region is combined with the corresponding position in the destination bitmap region, and the result is stored in the destination bitmap. The new value of the destination bitmap is the value returned when the functionboole is applied to these three arguments: the operation argument, the value of the bit at the source bitmap position, and the value of the bit at the destination bitmap position.

The operation argument must either be a single boolean constant or a sequence of boolean constants of length equal to the depth of the bitmap destination-bitmap. If operation is a sequence, the associated operation for each plane of the destination-bitmap is used to copy from the source-bitmap, in ascending order. The default value of the operation argument is the boolean constantboole-1.

You can specify the following keyword arguments to these functions:

• :clipping-region

This keyword argument specifies a region of the destination bitmap. If this keyword argument is given, only the region of the destination region that is located inside the clipping region is modified. The functionbitblt-region does not use this keyword option.

• :foreground,:background

These keyword arguments specify registered color entries and can be strings, symbols, or color numbers. They are used instead of the:pixel-map keyword argument when source-bitmap has a single plane and destination-bitmap has multiple planes.

• :pixel-map

This keyword argument is a user-created vector that maps pixel values in the bitmap source-bitmap onto the possible range of pixel values in the bitmap destination-bitmap. This argument is required when you map from a multiplane source-bitmap onto a destination-bitmap of unequal depth, such as from color to monochrome. You can supply this argument for bitmaps of equal depth if you want a color mapping. The vector that you specify for this argument must have(expt 2 (bitmap-depth source-bitmap)) integer entries in the range from 0 to(expt 2 (bitmap-depth destination-bitmap)) inclusive. If possible, it should be an array of typesimple-vector to optimize mapping speed.

When you specify the operation argument with the:pixel-map keyword argument or with the:foreground and:background arguments, the functionbitblt first determines the correct value for each source pixel in source-bitmap by using the mapping described by the:pixel-map keyword argument. It then combines the source pixel and destination pixel using the specified operation to determine the new destination pixel.

Mapping from a multiplane bitmap using the:pixel-map keyword argument requires per-pixel access, so mapping from a multiplane source-bitmap to any destination-bitmap is generally slow.

If the source-region and destination-region arguments ofbitblt-region are different widths, the width of the region that is actually copied is the smaller of the two. Similarly, if the source-region and destination-region arguments have different heights, the height of the region that is copied is the smaller of the two.

Syntax:bitmap-depth bitmap

The functionbitmap-depth returns the depth, or number of planes, of the specified bitmap.

You cannot change the depth of a bitmap.

> (setq *bitmap1* (make-bitmap :width 10 :height 10))
#<Bitmap 10x10x1 E664EB>

> (bitmap-depth *bitmap1*)
1

> (setq *bitmap2* (make-bitmap :width 10 :height 10 
                               :depth (display-depth)))
#<Bitmap 10x10x8 E67D0B>

> (bitmap-depth *bitmap2*)
8

bitmap-width Function

Syntax:bitmap-height bitmap

Syntax:bitmap-width bitmap

The functionbitmap-height returns the height of a bitmap.

The functionbitmap-width returns the width of a bitmap.

You can use the Common Lisp macrosetf with these functions. Increasing the width or height of a bitmap causes new area to appear at its boundaries. Decreasing the width or height can cause loss of data.

These are Liquid Common Lisp extensions.

> (setq my-bitmap (make-bitmap :width 100 :height 200))
#<Bitmap 100x200x1 25F391>

> (bitmap-height my-bitmap)
200

> (bitmap-width my-bitmap)
100

bitmap-background-pixel Function

Syntax:bitmap-foreground-pixel bitmap

Syntax:bitmap-background-pixel bitmap

The functionbitmap-foreground-pixel returns the current foreground pixel value for the given bitmap. Any graphic or text output operations on the bitmap use thebitmap-foreground-pixel value if no other color is specified.

The functionbitmap-background-pixel returns the current background pixel value for the given bitmap. Any graphic or text output operations on the bitmap use thebitmap-background-pixel value if no other color is specified.

You can use the Common Lisp macrosetf with these functions to specify a new default foreground or background pixel for a bitmap.

> (bitmap-foreground-pixel *bitmap*)
0

> (bitmap-background-pixel *bitmap*)
7

> (setf (bitmap-foreground-pixel *bitmap*) 1)
1

> (bitmap-foreground-pixel *bitmap*)
1

Syntax:bitmap-output-stream-p object

The predicatebitmap-output-stream-p tests whether its object argument is a bitmap output stream. It is true if object is a bitmap output stream.

> (bitmap-output-stream-p (make-bitmap-output-stream))
T

> (bitmap-output-stream-p 7)
NIL

Syntax:bitmap-p object

The predicatebitmap-p tests whether its object argument is a bitmap. It is true if object is a bitmap.

> (bitmap-p (make-bitmap :height 100 :width 200))
T

> (bitmap-p 7)
NIL

Syntax:bitmap-user-data bitmap

The functionbitmap-user-data returns the information that is specified in the:user-data keyword argument tomake-bitmap andinitialize-bitmap.

The bitmap argument specifies the bitmap that contains the data.

You can use the Common Lisp macrosetf with this function to alter the contents of the:user-data argument.

See Also: initialize-bitmap, make-bitmap

Syntax:bitmap-value bitmap x y

The functionbitmap-value returns the value of a bitmap's point at a given x-y coordinate.

The functionbitmap-value returns the pixel value at the location in the bitmap specified by the x and y arguments. The returned pixel value is an integer in the range from 0 to(1- (expt 2 (bitmap-depth bitmap))) inclusive.

You can use the Common Lisp macrosetf with this function to set the value of a point in a bitmap.

;; Create a 100x200 bitmap.
> (setq bmp (make-bitmap :width 100 :height 200))
#<Bitmap 100x200x1 AEC25B>

;; Look at the value of a point.
> (bitmap-value bmp 23 56)
0

;; Set the point to one.
> (setf (bitmap-value bmp 23 56) 1)
1

;; Look at the value of that point.
> (bitmap-value bmp 23 56)
1

stringblt Function

Syntax:charblt bitmap position font char&key :operation :foreground :background

Syntax:stringblt bitmap position font string&key :operation :foreground :background :start :end

The functioncharblt paints a character image from a font onto a bitmap.

The functionstringblt paints a string of character images from a font onto a bitmap.

The font argument must be a font, a string, or a symbol. If the argument is a string or a symbol, the functionfind-font is called to find the font named by the string or symbol.

The position argument specifies the position at which the character or characters are output. The first character is aligned so that the leftmost point of its baseline is at the point given by the position argument.

You can specify the following keyword arguments for both of these functions:

• :operation

This keyword argument controls how the font is painted onto the bitmap. The new value of the destination bitmap is the value returned by applying the Common Lisp functionboole to these three arguments: the:operation argument, the value of the font's bit, and the value of the destination bitmap position.

The:operation keyword argument must either be a single boolean constant or a sequence of boolean constants of length equal to the depth of the destination bitmap; the default value is the boolean constantboole-1. This default value causes the bits of the font's bitmap to overwrite whatever was previously on the bitmap. If the value of the:operation argument is a sequence, the associated operation for each plane of the destination bitmap is used to combine the source pixel with the destination pixel.

• :foreground,:background

These keyword arguments specify registered color entries and can be strings, symbols, or color numbers. The default values for these arguments are the foreground and background pixel defaults for the bitmap.

For the functionstringblt, the:start and:end keyword arguments take integer values that specify offsets into the string. These arguments restrict the output operation to a substring of the original string:

• The:start keyword argument marks the beginning position of the substring. The default value is 0.

• The:end keyword argument marks the position following the last element of the substring. The default value is the length of the string.

These functions use the specified text foreground and text background colors when they draw a character or a string on the specified bitmap. The resulting pixel value is combined with the destination pixel according to the boolean constant or constants specified in the:operation keyword argument.

The functionstringblt cannot handle tabs and other characters that have an ambiguous print representation. It can handle newline and space characters.

See Also: bitblt

char-width Function

max-char-width Function

Syntax:char-height char font

Syntax:char-width char font

Syntax:max-char-width font

The functionschar-height andchar-width return the height and width respectively of the specified character in the given font.

The functionmax-char-width returns the maximum character width that is allowed by the specified font.

Syntax:clear-bitmap bitmap&optional region background

The functionclear-bitmap clears a bitmap. That is, the value of every point in the bitmap is set to 0.

If a region argument is specified, only that region of the bitmap is cleared. Otherwise, the entire bitmap is cleared.

The background argument is a string, symbol, or color number; the default value is the background pixel of the specified bitmap. If you specify this argument, the function sets all the pixel values in the specified bitmap to the specified color.

;; Create a 10x10 bitmap.
> (setq btmp (make-bitmap :width 10 :height 10))
#<Bitmap 10x10x1 596D5D>

;; Put ones on the diagonal of the bitmap.
> (dotimes (i 10)
    (setf (bitmap-value btmp i i) 1))
NIL

;; A point on the diagonal has a value of one.
> (bitmap-value btmp 3 3)
1

;; A point not on the diagonal has a value of zero.
> (bitmap-value btmp 3 2)
0

;; Clear a region of the bitmap.
> (clear-bitmap btmp (make-region :x 2 :y 2 :height 3 :width 3))
#<Bitmap 10x10x1 596D5D>

;; Look at a diagonal point that was cleared.
> (bitmap-value btmp 3 3)
0

;; Look at a diagonal point that was not cleared.
> (bitmap-value btmp 9 9)
1

Syntax:color-available-p &key :display

The functioncolor-available-p checks whether the current display supports graphics and color functionality. If the display supports both graphics and color, this function returns the display depth and the color-map size respectively. Otherwise, it returns one of two sets of values:

• nil nil

These values indicate that the Window Tool Kit client is unable to connect to the specified X server; thus,color-available-p cannot determine whether the server supports color.

• nil t

These values indicate that a connection has been made, but the specified X server does not support color.

The:display keyword argument specifies the display used for Window Tool Kit interactions. It must be a string of one of the following forms:

"host"

"host:display-number"

The default value is supplied by the environment variableDISPLAY.

> (color-available-p)
8
256

Syntax:color-map-size

The functioncolor-map-size returns the total number of entries in the color map associated with the current system display.

Since some entries might be allocated already, the value returned bycolor-map-size does not necessarily reflect the number of available entries in the system color map.

> (display-depth)
8

> (color-map-size)
255

Syntax:color-registry-size

The functioncolor-registry-size returns the total number of entries that have already been allocated in the color registry.

Since color entries in the color registry can use the same system color map entry, the value returned bycolor-registry-size does not necessarily reflect the number of used or unavailable entries in the system color map.

> (color-registry-size)
22

Syntax:copy-bitmap bitmap

The functioncopy-bitmap copies a bitmap.

The original bitmap and the copy can be modified without affecting each other.

;; Create a 100x200 bitmap.
> (make-bitmap :height 100 :width 200)
#<Bitmap 200x100x1 5D95EE>

;; Make a copy of the bitmap.
> (copy-bitmap *)
#<Bitmap 200x100x1 5D9937>

See Also: store-bitmap

Syntax:copy-font font new-name

The functioncopy-font copies a font and stores the new font in the font registry under the name new-name.

The font argument should be a font, a string, or a symbol. If the argument is a string or a symbol, the functionfind-font is called to find the font named by the string or symbol.

The original font and the copy can be modified without affecting each other.

> *default-font*
#<Fixed-Width-Font ROMAN 4FB3CE>

;; Create a copy of the default font.  Call it "NEWROMAN".
> (copy-font *default-font* 'newroman)
#<Fixed-Width-Font NEWROMAN 5DA2C3>

See Also: find-font, store-font

Syntax:current-mouse-cursor

The functioncurrent-mouse-cursor returns the mouse cursor object that is currently tracking the mouse on the display screen.

You can use the Common Lisp macrosetf with this function to modify the mouse cursor object that is tracking the mouse.

See Also: make-mouse-cursor

Syntax:*current-screen*

For SunOS/Solaris only, the variable*current-screen* contains a Liquid Common Lisp screen structure that holds all of the machine-specific hooks.

Syntax:*default-font*

The value of the variable*default-font* is a font that is used by default by the functionsmake-bitmap-output-stream andmake-window.

The initial value of*default-font* is the font whose name is"ROMAN".

;; Create a bitmap output stream.
;; Do not give an :initial-font keyword argument.
> (make-bitmap-output-stream :width 100 :height 200)
#<Output-Stream to #<Bitmap 100x200x1 1A45D8> 1A49E0>

;; Check to see that the stream's font is *default-font*.
> (eq (stream-current-font *) *default-font*)
T

See Also: find-font

default-font-code-limit Constant

default-font-height Constant

Syntax:default-font-baseline

Syntax:default-font-code-limit

Syntax:default-font-height

These constants provide default values for font characteristics.

• default-font-baseline is the default value for the baseline height of every character in a font.

• default-font-height is the default value for the height of every character in a font.

• default-code-limit is the default value for the number of characters in a font.

Syntax:*default-pop-up-menu-font*

The value of the variable*default-pop-up-menu-font* is a font that the Window Tool Kit uses by default to display pop-up menus.

You can use the Common Lisp special formsetq to change the value of this variable, whose initial value is the font returned by the expression(find-font "ITALIC").

Syntax:delete-color name

The functiondelete-color deletes a previously registered color entry of the specified name from the color registry and returnsnil.

The name argument can be a symbol or a string.

If there are no other registered colors that refer to a system color map entry of the specified name, the color map entry is automatically deallocated.

It is not an error to delete a nonexistent color from the color registry.

> (register-color "PINK" :red max-mic-value
                         :green (round (* max-mic-value .4))
                         :blue (round (* max-mic-value .65)))
"PINK"

> (delete-color "PINK")
"PINK" unregistered.
NIL

Syntax:delete-font font

The functiondelete-font deletes a font from the font registry.

The font argument must be a font, a string, or a symbol. If it is a string or a symbol, the functionfind-font is called to convert the argument to a font.

The deleted font continues to exist. However, the functionfind-font no longer recognizes its name.

Syntax:delete-root-viewport root-viewport

The functiondelete-root-viewport deletes the specified viewport. It returnsnil.

You cannot use this function to delete the primary root viewport; the primary root viewport can only be deleted when you exit the Window Tool Kit with the functionleave-window-system.

See Also: leave-window-system

display-depth Function

Syntax:display-depth

The functiondisplay-depth returns the number of planes in the current system screen display.

On systems that do not support color, this function always returns a depth of 1.

> (display-depth)
8

Syntax:draw-circle bitmap center radius&key :width :operation :foreground :start-theta :angle

This function draws a circle on a bitmap whose center is the position center and whose radius is radius.

The keyword argument:width defines the line width that is used for drawing the line segments and circles. The border is drawn so that its outer edge is at the specified radius; the width must be less than or equal to the radius. If the:width keyword argument is omitted ornil, the default value is 1.

The keyword arguments:operation and:foreground are as fordraw-line.

The keyword arguments:start-theta and:angle correspond to the arguments angle1 and angle2 of the internal CLX functiondraw-arc, whichdraw-circle calls to draw the circle. The angles are signed integers in radians, with positive indicating counterclockwise motion and negative indicating clockwise motion. The start of the arc is specified by:start-theta, and the path and extent of the arc is specified by:angle, relative to the start of the arc. If the magnitude of:angle is greater than 360 degrees, it is truncated to 360 degrees. The default value of:start-theta is 0.0; the default value of:angle is(* 2 pi)).

draw-polyline Function

draw-polypoint Function

Syntax:draw-line bitmap start end&key :width :operation :foreground

Syntax:draw-polyline bitmap positions&key :width :operation :foreground

Syntax:draw-polypoint bitmap positions&key :width :operation :foreground

These functions draw geometric objects on bitmaps.

• draw-line draws a line segment from the position start to the position end.

• draw-polyline takes the sequence of positions positions and connects each adjacent pair.

• draw-polypoint takes the sequence of positions positions and draws a dot at each one.

You can specify the following keyword arguments to these functions:

• :width

This keyword argument defines the line width that is used for drawing the line segments and circles. Fordraw-polypoint, the:width argument specifies the diameter of the dot. If the:width keyword argument is omitted ornil, the default value is 1.

• :operation

This keyword argument controls how the values that are being written onto the bitmap combine with the values that are already present; it can be a single boolean constant or a list of boolean constants of length equal to the depth of the bitmap. If this keyword argument is omitted, the default value is the value of the constantboole-1; this default value causes the values that are being written onto the bitmap to overwrite whatever was already on the bitmap.

• :foreground

This keyword argument is a string, symbol, or a valid pixel color number for the specified bitmap. If this keyword argument is omitted ornil, the default value is the default foreground of the specified bitmap.

You can specify either the:foreground or the:operation argument, but not both.

Syntax:draw-rectangle bitmap x y&key :width :height :corner-x :corner-y :operation :foreground

The functiondraw-rectangle draws a rectangle on the specified bitmap.

The x and y arguments specify the x- and y-coordinates respectively of the rectangle's origin.

You can specify the following keyword arguments todraw-rectangle:

• :width,:height

These keyword arguments specify the rectangle's width and height respectively. The value of each must be a nonnegative fixnum. If either is omitted ornil, its default value is 0.

• :corner-x,:corner-y

These keyword arguments specify the rectangle's right and bottom edges respectively.

You can specify the keyword arguments:width and:height or the keyword arguments:corner-x and:corner-y, but not both pairs.

• :operation

This keyword argument must be a single boolean constant or a sequence of boolean constants of length equal to the depth of the specified bitmap. If the argument is a sequence of constants, the corresponding operation for each plane of the bitmap in ascending order is used to draw a rectangle on the bitmap. The default value of this argument is the boolean constantboole-1.

• :foreground

This keyword argument can be a pixel value or a registered color name string or symbol. If the argument is a pixel, it must be a valid pixel value for the bitmap in the range from 0 to(1- (expt 2 (bitmap-depth bitmap))) inclusive.

You can specify either the:foreground or the:operation argument, but not both. If you do not specify either keyword argument, the default foreground pixel of bitmap is used.

On systems that do not support color, the functiondraw-rectangle does not accept a foreground color; it does accept a boolean constant for the:operation keyword argument.

> (setq *window*
      (make-window :width 100 :height 100 :depth (display-depth)))
#<Window 100x100x8 at (0,0) E95ED3>

> (draw-rectangle
  *window* 10 10 :width 20 :height 20 :foreground "RED")
NIL

> (draw-rectangle
  *window* 10 30 :corner-x 30 :corner-y 50 :foreground "GREEN")
NIL

See Also: draw-circle, draw-line, draw-polyline, draw-polyline

hide-viewport Function

Syntax:expose-viewport viewport

Syntax:hide-viewport viewport

The functionexpose-viewport moves a viewport to the top of its sibling stack. Nothing happens if the viewport is already at the top of the stack.

The functionhide-viewport moves a viewport to the bottom of its sibling stack. Nothing happens if the viewport is already at the bottom of the stack.

In complex hierarchies,expose-viewport cannot place the viewport on the screen unoccluded because it can be occluded by its children, or because its parent can be occluded.

If two active viewports overlap on the screen, the following rules determine which viewport occludes the other:

• A viewport occludes all of its ancestor viewports.

• If two viewports are siblings, the viewport that is closest to the top of the sibling stack and all of its descendants occlude the viewport that is further down and all of its descendants.

See Also: viewport-children

find-color-number Function

Syntax:find-color&key :color :mdc :red :green :blue

Syntax:find-color-number&key :color :mdc :red :green :blue

The functionfind-color returns the color string that is associated with a color.

The functionfind-color-number returns the color number that is associated with a color. If the specified color is not registered,nil is returned.

You can specify any of the following keyword argument sets:

• :color

This keyword argument can be a string, a symbol, or a color number.

• :mdc

This keyword argument must be a previously registered machine-dependent color obtained with the functionfind-mdc.

• :red,:green,:blue

These keyword arguments must be in the range frommin-mic-value tomax-mic-value inclusive.

> (find-color :color "RED")
"RED"

> (find-color :color 1)
"RED"

> (find-color-number :color "RED")
1

> (find-color-number
  :red max-mic-value :blue min-mic-value :green min-mic-value)
1

> (find-color-number :mdc (find-mdc :color "RED"))
1

See Also: find-mdc, min-mic-value, max-mic-value

Syntax:find-font name

The functionfind-font finds and returns the font of the specified name. It returnsnil if it cannot find a font with that name.

The argument must be a string or a symbol. If it is a symbol, its print name is used.

The font registry initially contains three fonts that are named"ROMAN","BOLD-ROMAN", and"ITALIC".

See Also: copy-font, delete-font, load-font, rename-font, store-font

find-mic Function

Syntax:find-mdc&key:color :red :green :blue

Syntax:find-mic&key:color :mdc

The functionfind-mdc returns the machine-dependent color that is associated with a color. If the specified color is not registered and the keyword arguments:red,:green, and:blue are given, a new machine-dependent color is generated; otherwise,nil is returned.

The functionfind-mic returns the red, green, and blue values that are associated with a color. If the specified color is not registered,nil is returned.

The:color keyword argument is a string, symbol, or color number.

Forfind-mdc, the:red,:green, and:blue keyword arguments must be in the appropriate range frommin-mic-value tomax-mic-value inclusive.

Forfind-mic, the:mdc keyword argument is a previously registered machine-dependent color obtained with the functionfind-mdc.

> (find-mdc :color "RED")
#(255 0 0) 

> (find-mdc :red max-mic-value :blue min-mic-value 
            :green min-mic-value)
#(255 0 0)

> (find-mic :color "RED")
65535
0
0

> (find-mic :mdc (find-mdc :color "RED"))
65535
0
0

See Also: min-mic-value, max-mic-value

Syntax:find-root-viewport-from-viewport viewport

The functionfind-root-viewport-from-viewport returns the root viewport that is the ancestor of the specified viewport or window.

The viewport argument specifies a viewport or a window.

Syntax:follow-mouse min-x min-y max-x max-y function

The functionfollow-mouse tracks the movement of the mouse in the specified area during the execution of the specified function.

The min-x and min-y arguments specify the mininum x- and y- locations of the screen where the mouse is tracked. The max-x and max-y arguments specify the corresponding maximum x- and y- locations.

The function argument specifies the function that is executing while tracking occurs.

font-height Function

font-fixed-width Function

Syntax:font-baseline font

Syntax:font-height font

Syntax:font-fixed-width font

These functions return attributes of characters in a font.

• font-baseline returns the baseline height of a font, which is the baseline height of every character in the font.

• font-height returns the height of a font, which is the height of every character in the font.

• font-fixed-width returns the width of every character in a font if the font is a fixed-width font; otherwise, it returnsnil.

The font argument must be a font, a string, or a symbol. If the argument is a string or a symbol, the functionfind-font is called to find the font named by the string or symbol.

See Also: default-font-baseline, default-font-height, find-font

font-code-limit Function

font-name Function

Syntax:font-bitmap font

Syntax:font-code-limit font

Syntax:font-name font

These functions return attributes of a font.

• font-bitmap returns the underlying bitmap in which a font stores its character images.

• font-code-limit returns the number of character images that can be stored in a font.

• font-name returns the name of a font.

The font argument must be a font, a string, or a symbol. If the argument is a string or a symbol, the functionfind-font is called to find the font named by the string or symbol.

See Also: default-font-code-limit, find-font, rename-font

Syntax:fontp object

The predicatefontp tests whether its object argument is a font. It is true if object is a font.

> (fontp *default-font*)
T

> (fontp 7)
NIL

Syntax:get-screen-point-from-user &key :function :mouse-documentation

The functionget-screen-point-from-user prompts for a screen position. It returns the x- and y-location that is specified by a right click, if any. You can abort the operation by pressing the middle mouse button; in this case, the function returnsnil.

You indicate the position by moving the mouse to the proper screen location and pressing the right mouse button.

The:function keyword argument is a function that gets called with four arguments every time that the user moves the mouse:

• the x- and y-coordinates of the updated position of the mouse

• the x- and y-coordinates of the mouse before it was moved

The:mouse-documentation keyword argument is a string or a function that takes an active region as a single argument and returns a string. The string is printed in the who window and describes what actions the mouse can perform when in the given active region. If you do not specify a value for this argument, a default documentation string is used.

Syntax:get-screen-region-from-user &key :minimum-width :minimum-height &allow-other-keys

The functionget-screen-region-from-user prompts for a screen region. It returns the region that was selected, if any. You can abort the operation by pressing the middle mouse button; in this case, the function returnsnil.

You indicate the region by defining it with the mouse.

The:minimum-width and:minimum-height keyword arguments specify the minimum width and height of the region respectively.

You can also specify any keyword options that are valid for the functionmake-region.

See Also: make-region

Syntax:initialize-bitmap bitmap&key :width :height :user-data :depth :foreground :background

The functioninitialize-bitmap takes a bitmap structure and initializes or reinitializes it to have the shape and size described by the specified arguments. This function is useful whenever you create a new bitmap type that includes the Window Tool Kit bitmap structure and you wish to initialize the portion of it defined by the Window Tool Kit.

The bitmap argument specifies the bitmap to be initialized.

You can specify the following keyword arguments toinitialize-bitmap:

• :width,:height

These keyword arguments specify the width and height of the bitmap respectively. Unspecified dimensions default to 0.

• :user-data

This keyword argument contains any information that you would like to associate with the bitmap. There are no restrictions on the type of information specified in this argument.

• :depth

This keyword argument must be a legitimate depth for the specific system display. Depths can vary among host systems; the default depth is 1.

• :foreground,:background

These keyword arguments specify the default colors for the bitmap; they must be registered colors and can be strings, symbols, or color numbers. The default value of the:foreground keyword argument is the color number of the registered color"BLACK"; the default value of the:background keyword argument is the color number of the registered color"WHITE".

> (defstruct (my-bitmap (:include bitmap)
                        (:constructor new-my-bitmap))
              my-new-slot                ; This is a new slot.
	)
MY-BITMAP

> (defun make-my-bitmap (&key width height my-new-slot-value)
    (let ((new-my-bitmap 
          (new-my-bitmap :my-new-slot my-new-slot-value)))
    (initialize-bitmap new-my-bitmap :width width 
                                     :height height)))
MAKE-MY-BITMAP

See Also: make-bitmap

Syntax:initialize-viewport viewport &key :x :y :width :height :parent :activate :bitmap :bitmap-x :bitmap-y :depth :user-data :pixel-map :viewport-foreground :viewport-background

The functioninitialize-viewport takes a viewport structure and initializes or reinitializes it to have the shape and size described by the specified arguments. This function is useful whenever you create a new viewport type that includes the Window Tool Kit viewport structure and you wish to initialize the portion of it defined by the Window Tool Kit.

The viewport argument specifies the viewport to be initialized.

You can specify the following keyword arguments toinitialize-viewport:

• :x,:y

These keyword arguments specify the coordinates of the viewport's top-left corner relative to the root viewport. The value of each must be a nonnegative fixnum. If either is omitted, its default value is 0.

• :width,:height

These keyword arguments specify the width and height of the bitmap to which the viewport is attached. The value of each must be a nonnegative fixnum. If either is omitted ornil, its default value is 0.

You only need to use:width and:height if:bitmap is omitted ornil.

• :parent

This keyword argument specifies the parent viewport of the new viewport. Its value must be an existing viewport. If the value is a viewport or a window, the viewport or window is used as the parent of the new viewport. Otherwise, the current root viewport is used as the parent of the new viewport.

• :activate

This keyword argument specifies whether the viewport is active or inactive. If it is omitted or non-nil, the viewport is active. If it is specified andnil, the viewport is inactive.

• :bitmap

This keyword argument must be a bitmap; the bitmap output stream is attached to that bitmap. The specified bitmap must have a depth of 1 or(display-depth). If this keyword argument is omitted ornil, a new bitmap is created of depth(display-depth).

• :bitmap-x,:bitmap-y

These keyword arguments specify the x- and y-coordinates of the specified bitmap. The value of each must be a nonnegative fixnum. If either is omitted ornil, its default value is 0.

• :depth

This keyword argument must be a legitimate depth for the specific system display. Depths can vary among host systems; the default depth is 1.

• :user-data

This keyword argument contains any information that you would like to associate with the bitmap. There are no restrictions on the type of information specified in this argument.

• :pixel-map

This keyword argument is a vector that maps pixel values in the specified bitmap onto the possible range of pixel values on the display; it must be of length 2. The first entry of the vector:pixel-map is the value of the foreground pixel, and the second entry is the value of the background pixel. You can use this keyword argument instead of the keyword arguments:viewport-foreground and:viewport-background.

• :viewport-foreground,:viewport-background

You should supply these keyword arguments if the specified bitmap is of depth 1; the arguments describe how the monochrome bitmap should be mapped onto the multiplane display. Bits with the value 1 show as the viewport foreground color, and bits with the value 0 show as the viewport background color. These arguments must be registered color entries and can be strings, symbols, or color numbers. The default value of the:viewport-foreground keyword argument is the color number of the registered color"BLACK"; the default value of the:viewport-background keyword argument is the color number of the registered color"WHITE".

See Also: make-viewport

Syntax:initialize-window window &key :x :y :width :height :inside-x :inside-y :inside-width :inside-height :inner-border-width :outer-border-width :user-data :bitmap :bitmap-x :bitmap-y :depth :parent :scroll :vertical-scroll :horizontal-scroll :calculate-vertical-scroll-ratio :calculate-horizontal-scroll-ratio :initial-font :operation :title :title-font :foreground :background

The functioninitialize-window takes a window structure and initializes or reinitializes it to have the shape and size described by the specified arguments. This function is useful whenever you create a new window type that includes the Window Tool Kit window structure and you wish to initialize the portion of it defined by the Window Tool Kit.

The window argument specifies the window to be initialized.

You can specify the following keyword arguments toinitialize-window:

• :x,:y

These keyword arguments specify the position of the origin of the window's entire display (including borders) relative to the root viewport. The value of each must be a fixnum. If either argument is omitted ornil, its default value is 0.

• :width,:height

These keyword arguments specify the size of the entire window including all borders. The value of each must be a nonnegative fixnum. If either argument is omitted ornil, its default value is the width or height of the root viewport.

• :inside-x,:inside-y

These keyword arguments specify the position of the origin of the window's viewport relative to the root viewport. The value of each must be a fixnum. If either argument is omitted ornil and the default values for:inner-border-width and:outer-border-width are used, its default value is 3.

• :inside-width,:inside-height

These keyword arguments specify the size of the window's viewport. The value of each must be a nonnegative fixnum. If either argument is omitted ornil, its default value is the inside width or height of the root viewport minus the combined widths of either the vertical or the horizontal borders of the specified window.

• :user-data

This keyword argument contains any information that you would like to associate with the bitmap. There are no restrictions on the type of information specified in this argument.

• :inner-border-width,:outer-border-width

These keyword arguments specify the width of the window's inner and outer borders. If:inner-border-width is omitted ornil, its default value is 1. If:outer-border-width is omitted ornil, its default value is 2.

• :bitmap

This keyword argument must be a bitmap; the bitmap output stream is attached to that bitmap. The specified bitmap must have a depth of 1 or(display-depth). If this keyword argument is omitted ornil, a new bitmap is created of depth(display-depth).

• :bitmap-x,:bitmap-y

These keyword arguments specify the position in the window's bitmap that corresponds to the origin of the window's inside region. If either argument is omitted ornil, its default value is 0.

• :depth

This keyword argument must be a legitimate depth for the specific system display. Depths can vary among host systems; the default depth is 1.

• :parent

This keyword argument specifies the parent of the window. It can take one of three values, with three different consequences:

• If the argument is a window or a viewport, the new window is a child of the specified parent.

• If the argument ist, the new window is a child of the current root viewport; this value is the default.

• If the argument isnil, the new window is a new root viewport.

• :scroll

This keyword argument specifies whether the window can have scroll bars. If the value of this argument ist, the window can have scroll bars when the dimensions of the window's bitmap are greater than those of its viewport. Thus, when the bitmap is wider than the viewport, a scroll bar appears on the window's right border; when the bitmap is longer than the viewport, a scroll bar appears on the window's bottom border. If this argument is omitted ornil, the window is made without scroll bars. Do not give this keyword any value other thant ornil.

• :vertical-scroll,:horizontal-scroll

These keyword arguments specify the methods for vertical and horizontal scrolling. The value of each keyword must be a function that takes two arguments: the window and the current vertical scroll ratio or horizontal scroll ratio. If either argument is omitted ornil, its default value is the default method for vertical or horizontal scrolling. The default methods move the window's bitmap clipping region over the window's bitmap to a degree that corresponds to the movement of the bubble on the scroll bar.

• :calculate-vertical-scroll-ratio,:calculate-horizontal-scroll-ratio

These keyword arguments specify the methods for calculating vertical and horizontal scroll ratio respectively. The value of each keyword must be a function that takes the window as its argument and returns either a Common Lisp ratio between 0 and 1 ornil. If either keyword argument is omitted ornil, its default value is the default method for calculating the vertical or horizontal scroll ratio. The default method defines the current scroll ratio as that of the degree to which the window has been scrolled to the maximum degree to which it can be scrolled; thus, if a window has been scrolled to one-third of the possible horizontal scrolling distance, the horizontal scroll ratio is 1/3.

Note: You cannot use the Common Lisp macrosetf with these keyword arguments to set the respective scroll ratios.

• :initial-font

This keyword argument specifies the initial font used by the window's bitmap output stream. Its value must be a font, a string, or a symbol. If this argument is omitted ornil, its default value is the value of the variable*default-font*.

• :operation

This keyword argument specifies the boolean operation that the bitmap output stream uses to write onto the bitmap. Its value must be an acceptable first argument to the Common Lisp functionboole. If this argument is omitted ornil, its default value is the value of the constantboole-xor.

• :title

This keyword argument specifies the title of the window. Its value must be a string. The title of the window appears near the top-left corner of the window on the border. If this argument is omitted ornil, the window has no title.

• :title-font

This keyword argument specifies the font in which the title is displayed. Its value must be a font, a string, or a symbol. If this argument is omitted ornil, its default value is the value of the:initial-font keyword argument.

• :foreground,:background

These keyword arguments specify the default foreground pixel and background pixel for the bitmap associated with the new window. They must specify registered color entries and can be strings, symbols, or color numbers. Any text or graphic output to the window's bitmap uses the foreground and background pixel values. The default value of the:foreground keyword argument is the color number of the registered color"BLACK"; the default value of the:background keyword argument is the color number of the registered color"WHITE".

If you specify default values for:foreground,:background, and:operation, any drawing function that you invoke will use the window's foreground and background colors, not the values you specified, as defaults, unless you specify a color to the drawing function. In addition, the drawing function will assume a default operation ofboole-1.

See Also: make-window

Syntax:initialize-windows &key :height :width :screen-x :screen-y :label :no-wholine :icon-x :icon-y :icon-image :icon-label :display

The functioninitialize-windows initializes the Window Tool Kit.

The Window Tool Kit is normally initialized when the Editor is first entered. If you are not using the Editor, you must call the functioninitialize-windows to initialize the window system.

You can specify the following keyword arguments toinitialize-windows:

• :height,:width

This keyword argument pair specifies the size of the system window that will be the root viewport.

• :screen-x,:screen-y

This keyword argument pair indicates the position of the upper left corner of the system window.

• :label

This keyword argument names the system window.

• :no-wholine

If this keyword argument has a non-nil value, the primary root viewport is created without a who window. If the value of this keyword argument isnil, the primary root viewport is created with a who window for displaying information about the state of the mouse; this value is the default.

The functionmake-new-who-window creates a new who window.

• :icon-x,:icon-y

This keyword argument pair specifies the position for the icon when the window is closed.

• :icon-image

This keyword argument names the file that stores the image that will be used as the Lisp screen icon when an initialized window is closed.

• :icon-label

This keyword argument denotes the label displayed on the icon.

• :display

This keyword argument specifies the display used for Window Tool Kit interactions. It must be a string of one of the following forms:

"host"

"host:display-number"

The default value is supplied by the environment variableDISPLAY.

Note: Paired keyword arguments must be used together or not at all; when the system receives one of the paired arguments, it expects the other as well.

If you try to initialize the Window Tool Kit but it has already been initialized, the following message appears:

Window system already initialized

If the Window Tool Kit has been initialized and the functiondisksave is invoked, the window environment is temporarily suspended. Once thedisksave function has saved the Lisp image on disk, the windows on the running Lisp image are restored automatically to the state they were in before thedisksave function call. To restore the state of the window environment in the newly saved image, callinitialize-windows ored with no arguments. See Chapter 1, "Restoring windows in a saved image" for more information.

> (initialize-windows :display "applesauce:0")

See Also: leave-window-system, make-new-who-window

Syntax:keyboard-input &optional root-viewport

The functionkeyboard-input returns the stream that receives keyboard input. Any character typed at the keyboard is sent to the mouse input stream that is the value of this function.

Each root viewport has its own keyboard input stream. When you position the mouse over a root viewport, input to that root viewport is queued to that stream.

The optional root-viewport argument specifies the root viewport of the desired stream. If you do not specify this argument, the keyboard input stream of the current root viewport is used.

You can use the Common Lisp macrosetf with this function to change the stream that receives keyboard input; the second argument tosetf must be a mouse input stream. By default,(setf (keyboard-input)) sets the keyboard input stream for the current root viewport. Use the root-viewport argument to change the keyboard input stream for a specific root viewport. However, if the stream that you specify as a second argument tosetf is also a window and you do not supply a root-viewport argument, the window's root viewport is used. You can set the value ofkeyboard-input to any stream or window, even if the root viewport for the stream or window is different from the root-viewport argument.

The default value of this function is the mouse input stream that is returned by the functionmouse-input.

Syntax:leave-window-system

The functionleave-window-system exits the Window Tool Kit.

If you exit the window environment by callingleave-window-system, you cannot return to it. If you wish to use the Window Tool Kit after calling this function, you must set up new windows by invokinged orinitialize-windows.

See Also: initialize-windows

Syntax:listen-any &optional mouse-input-stream

The predicatelisten-any is true if a character or mouse event structure can be read from the given mouse input stream; otherwise, it is false.

The mouse-input-stream argument specifies a mouse input stream. If this argument is omitted ornil, the mouse input stream that is the value of the functionmouse-input is used. If the value of the mouse-input-stream argument is non-nil, the mouse input stream that is the value of the functionkeyboard-input is used.

See Also: keyboard-input, mouse-input, peek-any, read-any, read-any-no-hang

store-bitmap Function

Syntax:load-bitmap file-name

Syntax:store-bitmap bitmap file-name

The functionload-bitmap reads in a bitmap from the specified file and returns the bitmap.

The functionstore-bitmap stores a bitmap in the specified file.

;; Create a 10x10 bitmap with a random value at each point.
> (setq bitmap (make-bitmap :width 10 :height 10))
#<Bitmap 10x10 4B3F2B>

> (dotimes (i 10)
     (dotimes (j 10)
        (setf (bitmap-value bitmap i j) (random 2))))
NIL
> (progn ;; Store the bitmap in a file named "temp"
         (store-bitmap bitmap "temp")
         ;; Read the bitmap back in
         (setq new-bitmap (load-bitmap "temp")))
#<Bitmap 10x10 4B65BB>

;; Print a message if the two bitmaps differ at any point.
> (dotimes (i 10)
     (dotimes (j 10)
         (if (/= (bitmap-value bitmap i j)
                 (bitmap-value new-bitmap i j))
             (format t "values differ at ~D ~D~%" i j))))
NIL

See Also: copy-bitmap

store-color-registry Function

Syntax:load-color-registry pathname &optional destructive-load-p

Syntax:store-color-registry pathname

The functionload-color-registry loads the color entries from the file specified by the pathname argument. The color entries must have been previously stored by the functionstore-color-registry.

The functionstore-color-registry stores the color registry entries in the file specified by the pathname argument.

The color entries stored in the file pathname are read into the current system color registry in an arbitrary order. If there are more color entries than there are available entries in the system color map, an error is signaled.

If the optional argument destructive-load-p forload-color-registry has a non-nil value, the current system is reinitialized before the color entries in the specified file are loaded.

> (store-color-registry "colreg")
NIL

> (load-color-registry "colreg")
NIL

store-font Function

Syntax:load-font font-name&key :foreign-font-type

Syntax:store-font font file-name

The functionload-font loads and returns the specified font. The type of font that is loaded depends on whether the Window Tool Kit has been initialized and on the value of the:foreign-font-type keyword argument.

The functionstore-font stores a font in the specified file.

If the Window Tool Kit has been initialized and the functionload-font is invoked, it looks first for the X11 font specified by the font-name argument. If it cannot find such a font, the function searches for a Window Tool Kit font file. If neither type of font is available, an error is signaled.

If the:foreign-font-type keyword argument has a non-nil value,load-font attempts to load an X11 font even when the Window Tool Kit is not initialized.

Though you must initialize the Window Tool Kit before you can use fonts, you can load X11 fonts with the following expression at any time:

(load-font "-X-font" :foreign-font-type t) 

When the Window Tool Kit is initialized, it attempts to load the font specified by existing-X-font. If no such foreign font exists in the X server, an error is signaled.

When the value of the:foreign-font-type keyword argument isnil and the Window Tool Kit is not initialized,load-font interprets the font-name argument as a pathname for a file containing a Window Tool Kit font. It reads the file and returns the font. The default value of this argument isnil.

The font argument tostore-font must be a font, a string, or a symbol. If the argument is a string or a symbol, the functionfind-font is called to find the font named by the string or symbol. The information stored bystore-font includes the font's name.

You can specify the following keyword arguments toload-font:

• :foreign-font-type

This keyword argument specifies a font to be loaded that is not a Window Tool Kit font.

• :foreign-font-name

This keyword argument specifies the name of a foreign font to be loaded. If you do not specify this argument, the name of the foreign font is constructed by using the file-name argument.

See Also: copy-font, find-font

Syntax:make-active-region region&key :bitmap :mouse-click :mouse-transition :mouse-moved :mouse-enter-region :mouse-exit-region :mouse-documentation :user-data

The functionmake-active-region creates an active region for the specified region; as an option it can attach that active region to a bitmap.

The region argument is a region that describes the area of the bitmap in which mouse events can trigger the specified mouse methods. The x and y locations of this region are relative to the bitmap specified as the:bitmap keyword argument.

You can specify the following keyword arguments tomake-active-region:

• :bitmap

This keyword argument is the bitmap to which this active region should be attached. If this keyword argument is omitted ornil, the active region is not attached to any bitmap. Later it can be attached to a bitmap by using the functionattach-active-region.

• :mouse-click,:mouse-transition,:mouse-moved,:mouse-still,:mouse-enter-region,:mouse-exit-region

These keyword arguments specify the methods for each of the types of mouse events. The value of each keyword argument must be a function of five arguments. The method is called whenever the corresponding mouse event occurs inside the created active region.

If a mouse event keyword argument is omitted ornil, no method is associated with the mouse event, and no function is called when the mouse event occurs inside the created active region.

The method is called with the following sequence of arguments:

• the viewport on which the mouse event occurred

• the active region

• the mouse event character

• the x-coordinate of the position on which the mouse event occurred

• the y-coordinate of the position on which the mouse event occurred

• The x- and y-coordinates are given relative to the active region's bitmap.

For all mouse events except:mouse-exit-region, the x-coordinate and y-coordinate arguments specify a position inside the active region. For:mouse-exit-region, the specified position lies outside the active region; it can also lie outside the bitmap.

• :mouse-documentation

This keyword argument is a string or a function that takes an active region as a single argument and returns a string. The string is printed in the who window and describes what actions the mouse can perform when it is in the given active region.

• :user-data

This keyword argument contains any information that you would like to associate with the bitmap. There are no restrictions on the type of information specified in this argument.

The following keyword options tomake-active-region are supported for compatibility with previous releases of Liquid Common Lisp::mouse-left-down,:mouse-left-up,mouse-middle-down,:mouse-middle-up,:mouse-right-down, and:mouse-right-up.

See Also: attach-active-region

Syntax:make-bitmap&key :width :height :user-data :depth :foreground :background

The functionmake-bitmap creates a bitmap.

You can specify the following keyword arguments tomake-bitmap:

• :width,:height

These keyword arguments specify the width and height of the bitmap respectively. Unspecified dimensions default to 0.

• :user-data

This keyword argument contains any information that you would like to associate with the bitmap. There are no restrictions on the type of information specified in this argument.

• :depth

This keyword argument must be a legitimate depth for the specific system display. Depths can vary among host systems; the default depth is 1.

• :foreground,:background

These keyword arguments specify the default colors for the bitmap; they must be registered colors and can be strings, symbols, or color numbers. The default value of the:foreground keyword argument is the color number of the registered color"BLACK"; the default value of the:background keyword argument is the color number of the registered color"WHITE".

> (make-bitmap :height 100 :width 200)
#<Bitmap 200x100x1 856EE6>

Syntax:make-bitmap-output-stream &key :bitmap :width :height :operation :initial-font

The functionmake-bitmap-output-stream creates a bitmap output stream. The bitmap output stream can be attached to an already existing bitmap, or it can be attached to a new bitmap created by this function.

You can specify the following keyword arguments tomake-bitmap-output-stream:

• :bitmap

This keyword argument must be a bitmap; the bitmap output stream is attached to that bitmap. The specified bitmap must have a depth of 1 or(display-depth). If this keyword argument is omitted ornil, a new bitmap is created of depth 1.

• :width,:height

These keyword arguments specify the size of the new bitmap. An unspecified width or height defaults to 0.

• :operation

This keyword argument is the boolean operation used by the stream to write onto the bitmap. It can be a single boolean constant or a list of boolean constants of length equal to the depth of the specified bitmap. If the system depth is 1, the default operation isboole-1; otherwise, the default operation isboole-xor.

• :initial-font

This keyword argument is the font in which characters are painted onto the bitmap. The value of this keyword argument must be a font, a string, or a symbol. If the argument is a string or a symbol, the functionfind-font is called to find the font named by the string or symbol. The default value is the value of*default-font*.

The stream position of a newly created bitmap output stream is the position whose x-coordinate is 0 and whose y-coordinate is the baseline height of the initial font. Its linefeed distance is the height of the initial font.

Note: Do not attach an output stream to the bitmap that is associated with the root viewport.

;; Create a 100x200 bitmap, and attach a bitmap output stream to 
;; that bitmap.
> (make-bitmap-output-stream :width 100 :height 200)
#<Output-Stream to #<Bitmap 100x200x1 854AF5> 854EFD>

;; Check that the stream's current font is *default-font*.
> (eq (stream-current-font *) *default-font*)
T

;; Create another 100x200 bitmap.
> (setq btmp (make-bitmap :width 100 :height 200))
#<Bitmap 100x200x1 85603A>

;; Create a bitmap output stream that writes onto that bitmap.
> (make-bitmap-output-stream :bitmap btmp)
#<Output-Stream to #<Bitmap 100x200x1 85603A> 85646A>

See Also: find-font

Syntax:make-boole-op-sequence planes background foreground&key :mask :op-sequence

The functionmake-boole-op-sequence returns a sequence of boolean constants that are equivalent to the combination of the color arguments background and foreground and either of the keyword arguments:mask or:op-sequence. The sequence that is returned can be given as an operation sequence to other graphics output functions.

The color arguments foreground and background can be strings, symbols, or color numbers.

The planes argument must be the depth of the destination bitmap.

You can specify one of the keyword arguments:mask or:op-sequence, but not both.

• :mask

This keyword argument is an integer that specifies which planes of the destination bitmap are affected by the resulting sequence of boolean constants. The mask must be in the range from 0 to(1- (expt 2 planes)) inclusive. A 1 in any bit position of the mask indicates that the corresponding plane should be affected; a 0 indicates that the corresponding plane should not be affected.

• :op-sequence

This keyword argument is a single boolean constant or a sequence of boolean constants. If you specify a sequence of boolean constants, each boolean constant is associated with a plane of the destination bitmap in ascending order. The default value of:op-sequence is the boolean constantboole-1.

The functionmake-boole-op-sequence is useful when graphic or text output is drawn by using a mix of colors and boolean operations or by using a mix of colors and masking.

The use of operation lists in graphic or text output functions can be slower on host systems that are pixel oriented.

> (make-boole-op-sequence (display-depth)
                          (find-color-number :color "BLACK")
                          (find-color-number :color "WHITE")
                          :mask 1)
#(5 3 3 3 3 3 3 3)

> (make-boole-op-sequence (display-depth)
                          (find-color-number :color "BLACK")
                          (find-color-number :color "WHITE")
                          :op-sequence boole-1)
#(5 5 5 0 0 0 0 0)

> (setq *op-sequence*
      (make-boole-op-sequence (display-depth)
                              (find-color-number :color "BLACK")
                              (find-color-number :color "WHITE")
                              :op-sequence
                                (list boole-1 boole-1 boole-xor 
                                  boole-xor boole-xor boole-xor 
                                  boole-clr boole-clr)))
#(5 5 6 3 3 3 0 0)

> (draw-line *window*
    (make-position 0 0) 
    (make-position 100 100) :operation *op-sequence*)
NIL

maximum-cursor-height Function

maximum-cursor-width Function

Syntax:make-mouse-cursor bitmap&key :x-offset :y-offset :operation

Syntax:maximum-cursor-height

Syntax:maximum-cursor-width

The functionmake-mouse-cursor creates a mouse cursor object.

The constantsmaximum-cursor-height andmaximum-cursor-width are hardware constraints on the maximum height and width respectively of a mouse cursor.

The bitmap argument tomake-mouse-cursor is a bitmap that contains an image of the cursor.

You can specify the following keyword arguments tomake-mouse-cursor:

• :x-offset,:y-offset

These keyword arguments specify which point of the bitmap should be placed on the screen at the location to which the mouse is pointing. If either keyword argument is omitted ornil, the default value is 0.

• :operation

This keyword argument specifies the boolean operation that combines the bits of the mouse cursor's bitmap with the bits already on the screen. In Liquid Common Lisp, mouse cursors always behave as if they were defined with the boolean operationboole-1.

The value of the expression(bitmap-height bitmap) must be less than or equal tomaximum-cursor-height.

The value of the expression(bitmap-width bitmap) must be less than or equal tomaximum-cursor-width.

The functionmake-mouse-cursor and the constantsmaximum-cursor-height andmaximum-cursor-width are Liquid extensions to Common Lisp.

See Also: current-mouse-cursor

Syntax:make-mouse-input-stream&key :queue-mouse-events-p :viewport

The functionmake-mouse-input-stream creates a mouse input stream. A mouse input stream is identical to a Common Lisp input stream except that a mouse input stream can queue both characters and mouse event structures.

You can specify the following keyword arguments tomake-mouse-input-stream:

• :queue-mouse-events-p

This keyword argument determines whether this mouse input stream initially queues mouse event structures. The default value for this keyword argument isnil, which means that only characters are queued on the newly created mouse input stream.

• :viewport

This keyword argument is the viewport associated with the mouse input stream that is being created. If this keyword argument is omitted ornil, the mouse input stream is associated with the root viewport.

See Also: listen-any, mouse-input-stream-queue-mouse-events-p, peek-any, read-any, unread-any

Syntax:make-new-who-window&key :parent :x :y :width :height :border-width

The functionmake-new-who-window makes a new who window.

You can specify the following keyword arguments tomake-new-who-window:

• :parent

This keyword argument specifies the parent of the who window. It can have one of the following values:

• If the value is a window or viewport, the new window is a child of the specified window or viewport.

• If the value ist, the new window is the child of the current root viewport. This value is the default.

• If the value isnil, the new who window has no parent and is a top-level window on the screen.

• :x,:y

These keyword arguments specify the position of the origin of the window's display relative to the specified parent. If the value of the:parent keyword argument isnil, the position specified is relative to the screen.

• :width,:height

These keyword arguments specify the size of the new window, including borders.

• :border-width

This keyword argument specifies the width of the window's border. The default value is 2, which means that the border is two pixels wide.

Syntax:make-pop-up-menu choice-list&optional default-value font foreground background

The functionmake-pop-up-menu creates a pop-up menu object.

The choice-list argument is a list. Each element of the list is either a symbol or a cons whose car is a string.

If the element is a symbol, the print name of the element is one of the choices when the functionpop-up-menu-choose displays the pop-up menu. If chosen, the element is returned as the value ofpop-up-menu-choose.

If the element is a cons, the car of the element, which must be a string, is displayed as one of the choices. If the element is chosen, the value ofpop-up-menu-choose is the cdr of the cons.

If the mouse is moved off the choice menu, the default-value argument is returned. If this argument is omitted, the default value isnil.

You can specify the optional font argument if you want the menu items to appear in a different font from the default; the variable*default-pop-up-menu-font* specifies the default font.

The optional foreground and background arguments specify alternate colors for the pop-up menu. These arguments must be registered colors and can be strings, symbols, or color numbers. If you do not specify these arguments, the pop-up menu has a black foreground and a white background.

See Also: *default-pop-up-menu-font*, pop-up-menu-choose

Syntax:make-position&optional x y

The functionmake-position creates a position whose coordinates are specified by the x and y arguments.

The arguments must be nonnegative fixnums. If either argument is omitted, the default value is 0.

> (make-position)
#<Position (0,0) 855C2D>

> (make-position 100 200)
#<Position (100,200) 855C3E>

Syntax:make-region&key :region :x :y :width :height :corner-x :corner-y

The functionmake-region creates a new region.

To create a region, you must specify two of the following three attributes of a region: its origin, its corner, and its size. A region's origin is its top-left position. A region's size is its height and width. A region's corner is the point just below and to the right of its bottom-right position.

You can use the following keyword arguments to specify these attributes:

• :region

This keyword argument is a region that was created with the functionmake-region.

• :x,:y

These keyword arguments specify the x- and y-coordinates of the region's origin respectively.

• :width,:height

These keyword arguments specify the width and height of the region respectively.

• :corner-x,:corner-y

These keyword arguments specify the x- and y-coordinates of the region's corner respectively.

Syntax:make-viewport&key :x :y :width :height :parent :activate :bitmap :bitmap-x :bitmap-y :depth :user-data :pixel-map :viewport-foreground :viewport-background

The functionmake-viewport creates a viewport. The viewport is attached to an already existing bitmap or to a newly created bitmap.

The function returns two values: the newly created viewport and the bitmap to which the viewport is attached.

You can specify the following keyword arguments tomake-viewport:

• :x,:y

These keyword arguments specify the coordinates of the viewport's top-left corner relative to the root viewport. The value of each must be a nonnegative fixnum. If either is omitted, its default value is 0.

• :width,:height

These keyword arguments specify the width and height of the bitmap to which the viewport is attached. The value of each must be a nonnegative fixnum. If either is omitted ornil, its default value is 0.

You only need to use:width and:height if:bitmap is omitted ornil.

• :parent

This keyword argument specifies the parent viewport of the new viewport. Its value must be an existing viewport. If the value is a viewport or a window, the viewport or window is used as the parent of the new viewport. Otherwise, the current root viewport is used as the parent of the new viewport.

• :activate

This keyword argument specifies whether the viewport is active or inactive. If it is omitted or non-nil, the viewport is active. If it is specified andnil, the viewport is inactive.

• :bitmap

This keyword argument must be a bitmap; the bitmap output stream is attached to that bitmap. The specified bitmap must have a depth of 1 or(display-depth). If this keyword argument is omitted ornil, a new bitmap is created of depth(display-depth).

• :bitmap-x,:bitmap-y

These keyword arguments specify the x- and y-coordinates of the specified bitmap. The value of each must be a nonnegative fixnum. If either is omitted ornil, its default value is 0.

• :depth

This keyword argument must be a legitimate depth for the specific system display. Depths can vary among host systems; the default depth is 1.

• :user-data

This keyword argument contains any information that you would like to associate with the bitmap. There are no restrictions on the type of information specified in this argument.

• :pixel-map

This keyword argument is a user-created vector that maps pixel values in the specified bitmap onto the possible range of pixel values on the display; it must be of length 2. The first entry of the vector:pixel-map is the value of the foreground pixel, and the second entry is the value of the background pixel. You can use this keyword argument instead of the:viewport-foreground and:viewport-background keyword arguments.

• :viewport-foreground,:viewport-background

You should supply these keyword arguments if the specified bitmap is of depth 1; the arguments describe how the monochrome bitmap should be mapped onto the multiplane display. Bits with the value 1 show as the viewport foreground color, and bits with the value 0 show as the viewport background color. These arguments must be registered color entries and can be strings, symbols, or color numbers. The default value of the:viewport-foreground keyword argument is the color number of the registered color"BLACK"; the default value of the:viewport-background keyword argument is the color number of the registered color"WHITE".

;;; To run this example, you must have already initialized the
;;; Window Tool Kit.
;; Create a bitmap and a viewport onto that bitmap.
> (make-viewport :width 100 :height 200)
#<Viewport 100x200x1 at (0,0) onto #<Bitmap 100x200x1 85516A> 855572>
#<Bitmap 100x200x1 85516A>

;; Create another bitmap.
> (setq btmp (make-bitmap :width 100 :height 200))
#<Bitmap 100x200x1 85560C>

;; Create a viewport onto that bitmap.  Note that the bitmap
;; is returned as the second value.
> (make-viewport :bitmap btmp)
#<Viewport 100x200x1 at (0,0) onto #<Bitmap 100x200x1 85560C> 855A2A>
#<Bitmap 100x200x1 85560C>

Syntax:make-window&key :x :y :width :height :inside-x :inside-y :inside-width :inside-height :user-data :inner-border-width :outer-border-width :bitmap :bitmap-x :bitmap-y :depth :parent :scroll :vertical-scroll :horizontal-scroll :calculate-vertical-scroll-ratio :calculate-horizontal-scroll-ratio :initial-font :operation :title :title-font :activate:foreground :background

The functionmake-window creates and returns a window.

A window combines the functionality of a viewport, a bitmap, a bitmap output stream, and a mouse input stream. On the display screen, a window appears as a viewport. It can be surrounded by a border and can have a title. A window can also have scroll bars.

You can specify the following keyword arguments tomake-window:

• :x,:y

These keyword arguments specify the position of the origin of the window's entire display (including borders) relative to the root viewport. The value of each must be a fixnum. If either argument is omitted ornil, its default value is 0.

• :width,:height

These keyword arguments specify the size of the entire window including all borders. The value of each must be a nonnegative fixnum. If either argument is omitted ornil and the value of the:scroll keyword argument isnil, the default size is the size of the root viewport's inside region; if the value of:scroll ist, the default size is the size of the underlying bitmap. Thus, to make a scrollable window fit in the root viewport, you must explicitly specify its dimensions.

• :inside-x,:inside-y

These keyword arguments specify the position of the origin of the window's viewport relative to the root viewport. The value of each must be a fixnum. If either argument is omitted ornil and the default values for:inner-border-width and:outer-border-width are used, its default value is 3.

• :inside-width,:inside-height

These keyword arguments specify the size of the window's viewport. The value of each must be a nonnegative fixnum. If either argument is omitted ornil, its default value is the inside width or height of the root viewport minus the combined widths of either the vertical or the horizontal borders of the specified window.

• :user-data

This keyword argument contains any information that you would like to associate with the bitmap. There are no restrictions on the type of information specified in this argument.

• :inner-border-width,:outer-border-width

These keyword arguments specify the width of the window's inner and outer borders. If:inner-border-width is omitted ornil, its default value is 1. If:outer-border-width is omitted ornil, its default value is 2.

• :bitmap

This keyword argument must be a bitmap; the bitmap output stream is attached to that bitmap. The specified bitmap must have a depth of 1 or(display-depth). If this keyword argument is omitted ornil, a new bitmap is created of depth(display-depth).

• :bitmap-x,:bitmap-y

These keyword arguments specify the position in the window's bitmap that corresponds to the origin of the window's inside region. If either argument is omitted ornil, its default value is 0.

• :depth

This keyword argument must be a legitimate depth for the specific system display. Depths can vary among host systems; the default depth is 1.

• :parent

This keyword argument specifies the parent of the window. It can take one of three values:

• If the argument is a window or a viewport, the new window is a child of the specified parent.

• If the argument ist, the new window is a child of the current root viewport; this value is the default.

• If the argument isnil, the new window is a new root viewport.

• :scroll

This keyword argument specifies whether the window can have scroll bars. If the value of this argument ist, the window can have scroll bars when the dimensions of the window's bitmap are greater than those of its viewport. Thus, when the bitmap is wider than the viewport, a scroll bar appears on the window's right border; when the bitmap is longer than the viewport, a scroll bar appears on the window's bottom border. If this argument is omitted ornil, the window is made without scroll bars. Do not give this keyword argument any value other thant ornil.

• :vertical-scroll,:horizontal-scroll

The keyword arguments specify the methods for vertical and horizontal scrolling. The value of each keyword must be a function that takes two arguments: the window and the current vertical or horizontal scroll ratio. If either argument is omitted ornil, its default value is the default method for vertical or horizontal scrolling. The default methods move the window's bitmap clipping region over the window's bitmap to a degree that corresponds to the movement of the bubble on the scroll bar.

• :calculate-vertical-scroll-ratio,:calculate-horizontal-scroll-ratio

These keyword arguments specify the methods for calculating vertical and horizontal scroll ratio respectively. The value of each keyword must be a function that takes the window as its argument and returns either a Common Lisp ratio between 0 and 1 ornil. If either keyword argument is omitted ornil, its default value is the default method for calculating the vertical or horizontal scroll ratio. The default method defines the current scroll ratio as that of the degree to which the window has been scrolled to the maximum degree to which it can be scrolled; thus, if a window has been scrolled to one-third of the possible horizontal scrolling distance, the horizontal scroll ratio is 1/3.

Note: You cannot use the Common Lisp macrosetf with these keyword arguments to set the respective scroll ratios.

• :initial-font

This keyword argument specifies the initial font used by the window's bitmap output stream. Its value must be a font, a string, or a symbol. If this argument is omitted ornil, its default value is the value of the variable*default-font*.

• :operation

This keyword argument specifies the boolean operation that the bitmap output stream uses to write onto the bitmap. Its value must be an acceptable first argument to the Common Lisp functionboole. If this argument is omitted ornil, its default value is the value of the constantboole-1.

• :title

This keyword argument specifies the title of the window. Its value must be a string. The title of the window appears near the top-left corner of the window on the border. If this argument is omitted ornil, the window has no title.

• :title-font

This keyword argument specifies the font in which the title is displayed. Its value must be a font, a string, or a symbol. If this argument is omitted ornil, its default value is the value of the:initial-font keyword argument.

• :activate

This keyword argument specifies whether the viewport is active or inactive. If this argument is omitted or non-nil, the viewport is active; if it isnil, the viewport is inactive.

• :foreground,:background

These keyword arguments specify the default foreground pixel and background pixel for the bitmap associated with the new window. They must specify registered color entries and can be strings, symbols, or color numbers. Any text or graphic output to the window's bitmap uses the foreground and background pixel values. The default value of the:foreground keyword argument is the color number of the registered color"BLACK"; the default value of the:background keyword argument is the color number of the registered color"WHITE".

If you specify default values for:foreground,:background, and:operation, any drawing function that you invoke will use the window's foreground and background colors, not the values you specified, as defaults, unless you specify a color to the drawing function. In addition, the drawing function will assume a default operation ofboole-1.

;;; To run this example, you must have already initialized the 
;;; Window Tool Kit.
> (setq w (make-window :width 100 :height 200 :title "hello"))
#<Window 100x200x1 at (0,0) 8D1FF3>

> (windowp w)
T

See Also: window-vertical-scroll-ratio, window-horizontal-scroll, window-calculate-vertical-scroll-ratio, window-calculate-horizontal-scroll-ratio

Syntax:map-color-registry function

The functionmap-color-registry iterates over the color entries in the color registry and applies the specified function to each entry.

The function argument must take five arguments: color-name, color-number, red, green, and blue.

> (map-color-registry
  #'(lambda (color-name color-number red green blue)
      (format t "~S~20T~A  red: ~A, green: ~A, blue: ~A~%"
	      color-name color-number red green blue)))
"YELLOW"            5  red: 65535, green: 65535, blue: 0
"BLACK"             0  red: 0, green: 0, blue: 0
"WHITE"             7  red: 65535, green: 65535, blue: 65535
"CYAN"              4  red: 0, green: 65535, blue: 65535
"BLUE"              3  red: 0, green: 0, blue: 65535
"RED"               1  red: 65535, green: 0, blue: 0
"MAGENTA"           6  red: 65535, green: 0, blue: 65535
"GREEN"             2  red: 0, green: 65535, blue: 0
NIL

Syntax:map-fonts function

The functionmap-fonts iterates over the fonts in the font registry and applies the specified function to each entry.

The function argument specifies a function of two arguments, a font name and a font.

> (map-fonts #'(lambda (fontname font) 
                 (format t "~S~20T~A~%" fontname font)))
"ROMAN"             #<Fixed-Width-Font ROMAN C00E3A46>
"ITALIC"            #<Fixed-Width-Font ITALIC C00E679E>
"BOLD-ROMAN"        #<Fixed-Width-Font BOLD-ROMAN C00E517E>
NIL

min-mic-value Constant

Syntax:max-mic-value

Syntax:min-mic-value

The value of the constantmax-mic-value is the maximum value for specifying the color intensity of red, green, or blue when registering a color or setting a color in the color map.

The value of the constantmin-mic-value is the minimum value for specifying the color intensity of red, green, or blue when registering a color or setting a color in the color map.

If red, green, and blue are each set tomax-mic-value, the resulting color is white. If red, green, and blue are each set tomin-mic-value, the resulting color is black. The value ofmin-mic-value is 0, and the value ofmax-mic-value is 65535.

> max-mic-value
65535

> min-mic-value
0

Syntax:menu-mouse-buttons

The functionmenu-mouse-buttons returns a list of keywords that indicate which mouse buttons select menu items.

The default list returned bymenu-mouse-buttons is(:left :middle :right).

When you press a mouse button that is included in the list returned by this function, a menu item is selected. If the mouse button is not listed, no selection is made.

You can use the Common Lisp macrosetf with this function to set the mouse buttons that select menu items.

mouse-x Function

mouse-y Function

Syntax:mouse-buttons

Syntax:mouse-x

Syntax:mouse-y

The functionmouse-buttons returns an integer in the range 0 to 7. This integer encodes the mouse buttons that are currently depressed.

The functionsmouse-x andmouse-y return the current x- and y-coordinates of the mouse. These positions are relative to the root viewport.

The functionsmouse-x andmouse-y return coordinates of the mouse relative to the current root viewport.

See the table in Chapter 3, "Interpretation of mouse buttons" for the possible values returned bymouse-buttons.

See Also: mouse-buttons, *mouse-x*, *mouse-y*, mouse-event-buttons, mouse-event-x, mouse-event-y, move-mouse

*mouse-x* Variable

*mouse-y* Variable

Syntax:*mouse-buttons*

Syntax:*mouse-x*

Syntax: *mouse-y*

The variable*mouse-buttons* contains an integer in the range 0 to 7. This integer encodes the mouse buttons that are currently depressed.

The variables*mouse-x* and*mouse-y* contain the current x- and y-coordinates of the mouse. These positions are relative to the root viewport.

These variables are provided for backward compatibility; you should use the functionsmouse-buttons,mouse-x, andmouse-y in most instances.

See Also: mouse-buttons, mouse-event-buttons, mouse-event-x, mouse-event-y, mouse-x, mouse-y, move-mouse

mouse-cursor-x-offset Function

mouse-cursor-y-offset Function

mouse-cursor-operation Function

Syntax:mouse-cursor-bitmap mouse-cursor-object

Syntax:mouse-cursor-x-offset mouse-cursor-object

Syntax:mouse-cursor-y-offset mouse-cursor-object

Syntax:mouse-cursor-operation mouse-cursor-object

These functions return components of a mouse cursor object.

• mouse-cursor-bitmap returns a mouse cursor object's bitmap.

• mouse-cursor-x-offset returns a mouse cursor object's x-offset.

• mouse-cursor-y-offset returns a mouse cursor object's y-offset.

• mouse-cursor-operation returns the boolean constant that is used to write the mouse cursor object onto the display screen.

You can use Common Lisp macrosetf with these functions to modify a mouse cursor object.

Syntax:mouse-cursor-p object

The predicatemouse-cursor-p tests whether its object argument is a mouse cursor object. It is true if object is a mouse cursor object.

*mouse-leaves-window-system* Variable

Syntax:*mouse-enters-window-system*

Syntax:*mouse-leaves-window-system*

The variable*mouse-enters-window-system* contains a list of functions to be called whenever the mouse enters the root viewport.

The variable*mouse-leaves-window-system* contains a list of functions to be called whenever the mouse leaves the root viewport.

Syntax:mouse-event-p object

The predicatemouse-event-p tests whether its object argument is a mouse event structure. It is true if object is a mouse event structure.

mouse-event-x Function

mouse-event-y Function

mouse-event-buttons Function

Syntax:mouse-event-char mouse-event

Syntax:mouse-event-x mouse-event-structure

Syntax:mouse-event-y mouse-event-structure

Syntax:mouse-event-buttons mouse-event-structure

These functions access the fields of a mouse event structure.

• mouse-event-char returns a mouse event character that describes the mouse action of the specified mouse event.

• mouse-event-x andmouse-event-y give the x- and y-coordinates of the mouse when the mouse event occurred that created the mouse event structure. These coordinates are relative to the viewport that owns the mouse input stream on which the mouse event structure was read.

• mouse-event-buttons returns the value of the variable*mouse-buttons* at the time the mouse event occurred.

See Chapter 3, "Queuing mouse events" for information about mouse events and for the list of mouse event characters.

Syntax:mouse-input

The functionmouse-input determines where mouse input is sent.

The value of the functionmouse-input is examined when a mouse event occurs. If the expression

(mouse-input-stream-queue-mouse-events-p (mouse-input))

is non-nil, an object encoding the mouse event is appended to the mouse input stream that is the value of the expression(mouse-input).

You can use the Common Lisp macrosetf with this function to change the stream to which mouse input is sent. The second argument tosetf must be a mouse input stream.

Syntax:mouse-input-stream-interrupt-char mouse-input-stream char

The functionmouse-input-stream-interrupt-char returns the function that is called when the given character is typed to a mouse input stream.

The function returned bymouse-input-stream-interrupt-char takes two arguments: mouse-input-stream and char. The function is called as soon as char is typed to mouse-input-stream.

If the char argument is not an interrupt character, this function returnsnil. If the character causes the Debugger to be entered, the function returns the keyword value:debugger.

You can use the Common Lisp macrosetf to modify a character's interrupt handler. If you set the function value tonil, char is no longer an interrupt character on mouse-input-stream. If you set the function value to a function of two arguments, char becomes an interrupt character, and the function is called when char is typed. If you set the function value to the keyword value:debugger, typing this character causes the Debugger to be entered.

Note: The function corresponding to an interrupt character is called inside the system's interrupt handler; no other user interrupts are permitted while the function is running. If your function has an infinite loop, there is no way to interrupt it.

Syntax:mouse-input-stream-p object

The predicatemouse-input-stream-p tests whether its object argument is a mouse input stream. It is true if object is a mouse input stream.

Syntax:mouse-input-stream-queue-mouse-events-p mouse-input-stream

When a mouse event occurs, the predicatemouse-input-stream-queue-mouse-events-p is called on the mouse input stream that is the value of the functionmouse-input. If the value returned is non-nil, a mouse event structure encoding the mouse event is queued on the mouse input stream that is the value of the functionmouse-input.

You can use the Common Lisp macrosetf with this function to cause a mouse input stream to start or stop queueing mouse event structures.

The initial value for this function can be set in the functionmake-mouse-input-stream with the:queue-mouse-events-p keyword argument.

See Also: make-mouse-input-stream, read-any

Syntax:mouse-input-stream-viewport mouse-input-stream

The functionmouse-input-stream-viewport returns the viewport that is associated with a mouse input stream.

Syntax:move-mouse x y

The functionmove-mouse moves the mouse cursor from its current position to the position specified by the x and y arguments.

Using this function from within the window input process can cause the following warning to appear:

;;; Warning: MOVE-MOUSE timed out waiting for kernel to move mouse

The reason for this warning is that the I/O operation performed bymove-mouse involves requesting the mouse to move and then waiting for the movement to take place. Therefore, you should not invokemove-mouse from the window input process.

See Also: mouse-x, mouse-y, *mouse-x*, *mouse-y*

Syntax:move-viewport viewport x y

The functionmove-viewport moves a viewport's origin so that its top-left corner is at the point whose screen coordinates are specified by the x and y arguments.

The root viewport cannot be moved.

Syntax:outline-box-on-screen viewport x1 y1 delta-x delta-y&optional foreground op

The functionoutline-box-on-screen outlines a box directly on the screen on top of all other windows or viewports.

The viewport argument is a viewport for gaining access to the screen. Generally you should specify the root viewport for this argument.

The x1 and y1 arguments specify the coordinates of the upper left-hand corner of the box to be outlined relative to the root viewport.

The delta-x and delta-y arguments specify the width and the height of the box respectively.

The optional color argument foreground specifies a pixel value. If this argument is not specified, the default color entry is used.

The optional op argument can be any boolean constant. If this argument is not specified, the default value is the boolean constantboole-c2.

Syntax:peek-any&optional peek-type mouse-input-stream eof-error-p eof-value recursive-p mouse-event

The functionpeek-any peeks at and returns the next character or mouse event in a mouse input stream without reading it. The character or mouse event is read at a later time.

You can also usepeek-any for skipping over characters and mouse events in the input stream until a particular character is encountered.

The mouse-input-stream argument specifies a mouse input stream. If this argument is omitted ornil, the mouse input stream that is the value of the functionmouse-input is used. If the value of the mouse-input-stream argument is non-nil, the mouse input stream that is the value of the functionkeyboard-input is used.

The eof-error-p and eof-value arguments are provided for compatibility with the Common Lisp functionsread-char andread-char-no-hang and are ignored.

If the call topeek-any comes from within some function that itself has been called fromread or a similar input function, the recursive-p argument must have a non-nil value. If this argument is omitted, the default value isnil.

The peek-type argument specifies the type of object searched for on the mouse input stream. If peek-type is specified, its value must be eithernil,t, or a character:

• If the value isnil,peek-any looks at and returns the next character or mouse event structure in the mouse input stream without reading it from the stream. This value is the default.

• If the value ist,peek-any reads and discards any whitespace characters at the front of the mouse input stream and returns the first mouse event structure or character that is not white space without reading it from the stream. Comments are not discarded.

• If the value is a character,peek-any discards characters and mouse event structures from the front of the input stream until it encounters a character that is equal to (char=) the peek-type argument. That character is returned without being read from the stream.

If the mouse-event argument is specified, it must be a mouse event structure. This structure is used to store the mouse event that is returned and later read from the mouse input stream. If this argument is not specified, a mouse event structure is created when the mouse event is read.

See Also: keyboard-input, listen-any, mouse-event-p, mouse-input, read-any, read-any-no-hang

Syntax:pop-up-menu-choose pop-up-menu-object

The functionpop-up-menu-choose displays a pop-up menu specified by the pop-up-menu-object argument. The menu appears on the display screen near the current position of the mouse. You can choose one of the objects on the menu by clicking the right button on top of the selected item, or you can move the mouse off the menu.

Once you have made a choice or moved the mouse off the menu, the menu disappears and two values are returned. The first value is the item that you selected, and the second is a keyword that indicates which button you used to select the item. If you did not make a selection and the menu has a default value, the default value andnil are returned; if the menu does not have a default value, both of the values returned arenil.

See Also: make-pop-up-menu

Syntax:pop-up-menu-p object

The predicatepop-up-menu-p tests whether its object argument is a pop-up menu. It is true if object is a pop-up menu.

position-y Function

Syntax:position-x position

Syntax:position-y position

The functionsposition-x andposition-y return the x- and y-coordinates respectively of a position.

You can use the Common Lisp macrosetf with these functions to set the x- and y-coordinates of a position.

> (setq pos (make-position 100 200))
#<Position (100,200) 595ba3>

> (position-x pos)
100

> (setf (position-y pos) 300)
300

> pos
#<Position (100,300) 595ba3>

Syntax:positionp object

The predicatepositionp tests whether its object argument is a position. It is true if object is a position.

> (positionp (make-position 100 200))
T

> (positionp 7)
NIL

Syntax:print-color-registry &key :percentage-values

The functionprint-color-registry displays the contents of the color registry on the stream that is the value of the Common Lisp variable*standard-output*.

If the:percentage-values keyword argument has a non-nil value, the red, green, and blue values in the registry are shown as percentages of the maximum saturation, which is the value returned by the functionmax-mic-value; otherwise, the red, green, and blue values are integers between 0 and 65535, which reflect the absolute saturation. The default value of this argument isnil.

> (print-color-registry)
Color Registry
'YELLOW'  Color-No: 5 Red: 65535 Green: 65535 Blue: 0     count: 1
'BLACK'   Color-No: 0 Red: 0     Green: 0     Blue: 0     count: 1
'WHITE'   Color-No: 7 Red: 65535 Green: 65535 Blue: 65535 count: 1
'CYAN'    Color-No: 4 Red: 0     Green: 65535 Blue: 65535 count: 1
'BLUE'    Color-No: 3 Red: 0     Green: 0     Blue: 65535 count: 1
'RED'     Color-No: 1 Red: 65535 Green: 0     Blue: 0     count: 1
'MAGENTA' Color-No: 6 Red: 65535 Green: 0     Blue: 65535 count: 1
'GREEN'   Color-No: 2 Red: 0     Green: 65535 Blue: 0     count: 1
NIL

See Also: max-mic-value

Syntax:print-fonts

The functionprint-fonts displays all of the fonts currently in the font registry.

;; Assume that the font registry contains a roman and an italic
;; font.
> (print-fonts)
                                                                                                                                Code
Fontname               Font              Width Height Baseline Limit
ROMAN  #<Fixed-Width-Font ROMAN C00E3A46>  8     16      11     128
ITALIC #<Fixed-Width-Font ITALIC C00E679E> 8     16      11     128
NIL

See Also: find-font

read-any-no-hang Function

Syntax:read-any&optional mouse-input-stream eof-error-p eof-value recursive-p mouse-event

Syntax:read-any-no-hang&optional mouse-input-stream eof-error-p eof-value recursive-p mouse-event

The functionsread-any andread-any-no-hang read either a single character or a single mouse event structure from a mouse input stream.

The mouse-input-stream argument specifies a mouse input stream. If this argument is omitted ornil, the mouse input stream that is the value of the functionmouse-input is used. If the value ist, the mouse input stream that is the value of the functionkeyboard-input is used. Otherwise, the specified mouse input stream is used.

If there is no character or mouse event structure ready to be input, the functionread-any waits until a character is typed to the stream or a mouse event occurs on the stream mouse-input-stream. In this same situation, the functionread-any-no-hang returns the valuenil without waiting.

The eof-error-p and eof-value arguments are provided for compatibility with the Common Lisp functionsread-char andread-char-no-hang and are ignored.

If the call toread-any orread-any-no-hang comes from within some function that itself has been called fromread or a similar input function, the recursive-p argument must have a non-nil value. If this argument is omitted, the default value isnil.

If the mouse-event argument is specified, it must be a mouse event structure. This structure is used to store the mouse event that is read from the mouse input stream. If this argument is not specified, a mouse event structure is created when the mouse event is read.

See Also: keyboard-input, listen-any, make-mouse-input-stream, mouse-event-p, mouse-input, mouse-input-stream-queue-mouse-events-p, peek-any, unread-any

region-contains-position-p Predicate

Syntax:region-contains-point-p region x y

Syntax:region-contains-position-p region position

The predicateregion-contains-point-p is true if the position whose coordinates are specified by the x and y arguments is in the given region.

The predicateregion-contains-position-p is true when the specified position is in the given region.

;; Create a region whose origin is (100,100) and whose corner is (400,300).
> (setq reg (make-region :x 100 :y 100 :width 300 :height 200))
#<Region 300x200 at (100,100) 596507>

> (region-contains-point-p reg 150 299)
T

> (region-contains-position-p reg (make-position 150 300))
NIL

region-corner-x Function

region-corner-y Function

region-height Function

region-width Function

region-origin Function

region-origin-x Function

region-origin-y Function

region-size Function

Syntax:region-corner region&optional result-position

Syntax:region-corner-x region

Syntax:region-corner-y region

Syntax:region-height region

Syntax:region-width region

Syntax:region-origin region&optional result-position

Syntax:region-origin-x region

Syntax:region-origin-y region

Syntax:region-size region

Each of these functions returns a component of a region.

You can use the Common Lisp macrosetf with all of these functions. If a result-position argument is given forregion-corner andregion-origin, that position is modified to the region's corner position or origin position and returned. Otherwise, a new position is created and returned.

;; Create a region whose origin is (400,500) and whose corner 
;; is (480,590).
> (setq r (make-region :x 400 :y 500 :width 80 :height 90))
#<Region 80x90 at (400,500) ada243>

> (region-corner r)
#<Position (480,590) ada2e3>

> (region-corner-x r)
480

> (region-corner-y r)
590

> (region-height r)
90

> (region-width r)
80 >>> Undefined macro: \guideject

> (region-origin r)
#<Position (400,500) adb1db>

> (region-origin-x r)
400

> (region-origin-y r)
500

> (region-size r)
#<Extent 80x90 adb253>

region-union Function

Syntax:region-intersection region region&rest regions

Syntax:region-union region region&rest regions

The functionregion-intersection returns the region covered in common by all of the given regions. If there is no intersection, it returnsnil.

The functionregion-union returns the smallest region that contains all of the supplied regions.

> (setq r1 (make-region :x 0 :y 0 :width 100 :height 200))
#<Region 100x200 at (0,0) 5AC098>

> (setq r2 (make-region :x 50 :y 150 :width 100 :height 100))
#<Region 100x100 at (50,150) 5AC0BD>

> (region-union r1 r2)
#<Region 150x250 at (0,0) 5AC0CE>

> (region-intersection r1 r2)
#<Region 50x50 at (50,150) 5AC0E3>

region<= Function

region= Function

region/= Function

region> Function

region>= Function

Syntax:region< region region&rest regions

Syntax:region<= region region&rest regions

Syntax:region= region region&rest regions

Syntax:region/= region region&rest regions

Syntax:region> region region&rest regions

Syntax:region>= region region&rest regions

These functions test containment and equality for regions.

• region< is true if each argument except the last is contained in the following argument.

• region<= is true if each argument except the last is contained in or equals the following argument.

• region= is true if every argument is the same region.

• region/= is true if no two arguments are the same region.

• region> is true if each argument except the last contains the argument that follows it.

• region>= is true if each argument except the last contains or is equal to the argument that follows it.

> (setq region1 (make-region :x   0 :y   0 :corner-x 100 :corner-y 100)
      region2 (make-region :x   0 :y   0 :corner-x 100 :corner-y 101)
      region3 (make-region :x  50 :y  50 :corner-x 200 :corner-y 300)
      region4 (make-region :x 200 :y 300 :corner-x 500 :corner-y 700)
      region5 (make-region :x 150 :y 299 :corner-x 500 :corner-y 701)
      region6 (make-region :x 150 :y 299 :corner-x 500 :corner-y 700))
#<Region 350x401 at (150,299) 4850CB>

> (region< region1 region2)
T

> (region< region1 region1)
NIL

> (region<= region1 region2)
T

> (region<= region1 region1)
T

> (region> region2 region1)
T

> (region> region2 region2)
NIL

> (region>= region2 region1)
T

> (region>= region2 region2)
T

;; For region/= to be true, all of the regions must be different.
> (region/= region1 region2 region3 region4 region5 region6)
T

> (region/= region1 region2 region3 region4 region5 region6 region1)
NIL

> (region= region1 region1 region1 region1 region1)
T

> (region= region1 region2)
NIL

Syntax:regionp object

The predicateregionp tests whether its object argument is a region. It is true if object is a region.

> (regionp (make-region :x 0 :y 0 :width 100 :height 200))
T

> (regionp 8)
NIL

Syntax:register-color name&key :red :green :blue :delta-red :delta-green :delta-blue :new-p :starting-color-number

The functionregister-color registers the specified color in the color registry and returns the name symbol of the color as a string. If the color is already registered,nil is returned. You can remove the registered color with the functiondelete-color.

The name argument is a string that can be used later to refer to the registered color. If name is not a new color name, no new color is registered.

You can specify the following keyword arguments toregister-color:

• :red,:green,:blue

These keyword arguments specify the intensity of these components of the display color for the color entry. Their values must be integers in the range frommin-mic-value tomax-mic-value inclusive; their default value ismin-mic-value.

• :delta-red,:delta-green,:delta-blue

These keyword arguments specify how much variation from the specified values of:red,:green and:blue is allowed. These arguments default to 0, or no variation. If you specify variations and the:red,:green, and:blue values are close, an existing color entry in the system color map can be used for the new color to save space in the system color map.

• :new-p

If this keyword argument has a non-nil value, the registered color is registered with a new system color map entry even if another registered color has a color map entry that is within the specified variation for the red, green, and blue values.

• :starting-color-number

If you specify an integer value for this keyword argument, the functionregister-color attempts to associate the registered color with the system color map entry number. This number must be in the range from 0 to(1- (color-map-size)) inclusive. If the requested system color map entry number is already in use, the succeeding map entry numbers are searched for an available number. It is not an error to request an entry number that is already in use.

> (register-color "MINT" :red (round (* max-mic-value .50))
                         :green (round (* .80 max-mic-value))
                         :blue (round (* .60 max-mic-value)))
"MINT"

> (register-color 'my-black :new-p t)
"MY-BLACK"

> (register-color 'my-black :new-p t)
NIL

See Also: delete-color, min-mic-value, max-mic-value

Syntax:rename-color old-name new-name

The functionrename-color changes the name of the registered color specified by the old-name argument to be the name specified by the new-name argument. The color's new name is returned as a string.

The old-name and new-name arguments must be either symbols or strings. The old-name argument must be an existing color symbol or string.

> (rename-color "BLACK" "OLDBLACK")
"OLDBLACK"

> (rename-color 'oldblack 'newblack)
"NEWBLACK"

> (rename-color 'newblack "BLACK")
"BLACK"

Syntax:rename-font font new-name

The functionrename-font changes the name of the specified font to the name new-name. The name of the font is also changed in the font registry.

The font argument must be a font, a string, or a symbol. If the argument is a string or a symbol, the functionfind-font is called to find the font named by the string or symbol.

The new-name argument is either a string or a symbol. If it is a symbol, the symbol's print name is used.

See Also: font-name

Syntax:reset-color-registry &key :confirm

The functionreset-color-registry restores the color registry entries to the values that were registered when the Window Tool Kit was initialized; that is, it deletes all colors from the registry except the default values,'BLACK and'WHITE.

If the:confirm keyword argument has a non-nil value, you are queried before the color registry is restored; this value is the default.

Since the functionreset-color-registry can change any system color map entry, you can destructively change the color intensity of registered colors and thus change the appearance of the screen immediately. You should use this function with caution. Any entries added to the color registry since the Window Tool Kit was initialized are destructively removed.

> (reset-color-registry :confirm nil)
8

> (print-color-registry)
Color Registry
'WHITE' Color-No: 0   Red: 65535 Green: 65535 Blue: 65535 count: 1
'BLACK' Color-No: 255 Red: 0     Green: 0     Blue: 0     count: 1
NIL

Syntax:reshape-viewport viewport&key :region :x :y :width :height :corner-x :corner-y

The functionreshape-viewport moves and reshapes the specified viewport so that its screen region is the region specified by the keyword arguments.

You can specify the following keyword arguments toreshape-viewport. You must specify enough keyword arguments to identify the region uniquely.

• :region

This keyword argument is a region that was created with the functionmake-region.

• :x,:y

These keyword arguments specify the x- and y-coordinates respectively of the top-left corner of the region.

• :corner-x,:corner-y

These keyword arguments specify the x- and y-coordinates respectively of the point just below and to the right of the region.

• :width,:height

These keyword arguments specify the width and height respectively of the region.

All coordinates are given in terms of the root viewport. The root viewport cannot be reshaped.

Moving a viewport also moves all of its descendants.

Syntax:root-viewport-p object

The functionroot-viewport-p is true if its argument is a root viewport.

See Also: root-viewport, root-viewports

root-viewports Function

Syntax:root-viewport

Syntax:root-viewports

The functionroot-viewport returns the current root viewport. The current root viewport is the viewport that receives all window system input and output.

The functionroot-viewports returns a list of all of the root viewports that are currently active.

You can use the Common Lisp macrosetf with the functionroot-viewport to change the current root viewport.

Syntax:root-viewport-under-mouse

The functionroot-viewport-under-mouse returns the root viewport that is currently under the mouse.

If there is no root viewport under the mouse, this function returnsnil.

set-color-map-mdc Function

Syntax:set-color-map-mic color-number red green blue

Syntax:set-color-map-mdc color-number mdc

The functionsset-color-map-mic andset-color-map-mdc set the specified system color map entry to the specified color intensity values. The specified color number is not entered in the color registry but is set directly into the system color map. Both functions return the system color map entry or the first entry that is set.

The color-number argument must be an allocated index into the system color map and must be in the range from 0 to(1- (color-map-size)) inclusive.

The red, green, and blue arguments must be in the integer range frommin-mic-value tomax-mic-value inclusive; they can be sequences of integers in the appropriate range. If red, green, and blue are sequences, the color-number argument and each successive system color map entry is set to the corresponding values in each sequence.

The mdc argument must be a legitimate machine-dependent color that is obtained with functionfind-mdc.

> (set-color-map-mic (allocate-color) 100 1000 10000)
23

> (set-color-map-mdc (allocate-color) (find-mdc :color 0))
24

See Also: find-mdc, min-mic-value, max-mic-value

Syntax:setup-color-library&key :primary-colors :extended-colors :use-existing-primaries

By default, the only registered colors in the Window Tool Kit are"BLACK" and"WHITE". This function registers the additional six primary colors"RED","GREEN","BLUE","YELLOW","MAGENTA", and"CYAN", and possibly other color library shades.

This function provides more control over potentially destructive operations on the color map and makes registering additional colors more convenient.

You can specify the following keyword arguments tosetup-color-library:

• :primary-colors

If this argument has a non-nil value, the function registers the primary colors in the color registry. If the current display is not a color display, the primary colors are not set in the system color map but are registered so that they can be used in normal color code. The default value ist.

• :extended-colors

If this argument has a non-nil value, the function registers the extended library colors in the color registry. If the current display is not a color display, the extended colors are not set in the system color map but are registered so that they can be used in normal color code. The default value isnil

• :use-existing-primaries

This argument only applies to color displays. If it has a non-nil value, the primary colors"RED","GREEN","BLUE","CYAN","MAGENTA", and"YELLOW" are registered if they already exist in the system color map. They must have been entered into the system color map before the root-viewport window is initialized.

The system color map will be searched for colors that match these six primaries in intensity. Any primary colors that are not found in the system color map are registered.

This argument allows you to reuse common primary color entries in the system color map when possible. The default value isnil.

Any color that is not"WHITE" is displayed as"BLACK" on a monochrome display.

See Also: delete-color, print-color-registry, register-color, reset-color-registry

Syntax:stream-current-font bitmap-output-stream

The functionstream-current-font returns the current font of a bitmap output stream.

You can use the Common Lisp macrosetf to modify the stream's current font. The second argument tosetf must be a font, a string, or a symbol. If the argument is a string or a symbol, the functionfind-font is called to find the font named by the string or symbol. Changing a stream's current font does not modify the stream's linefeed distance.

;; Create a 100x200 bitmap.
> (setq btmp (make-bitmap :height 100 :width 200))
#<Bitmap 200x100x1 5ACEC3>

;; Create a bitmap output stream to that bitmap.
> (setq b-o-s (make-bitmap-output-stream :bitmap btmp))
#<Output-Stream to #<Bitmap 200x100x1 5ACEC3> 5AD21D>

;; The bitmap output stream's current font is *default-font*.
> (eq (stream-current-font *) *default-font*)
T

See Also: stream-linefeed-distance

stream-draw-line Function

stream-draw-polyline Function

Syntax:stream-draw-circle bitmap-output-stream radius&key :width :operation :foreground

Syntax:stream-draw-line bitmap-output-stream end&key :width :operation :foreground

Syntax:stream-draw-polyline bitmap-output-stream positions&key :width :operation :foreground

These functions draw geometric objects at particular positions of a bitmap output stream.

• stream-draw-circle draws a circle of radius radius around a bitmap output stream's current position.

• stream-draw-line draws a line segment from a bitmap output stream's current position to the position end. The bitmap output stream's new current position becomes the position end.

• stream-draw-polyline draws a series of connected line segments, starting at a bitmap output stream's current position and then going through each position in a sequence of positions. The current position of the bitmap output stream is left at the final position.

You can specify the following keyword arguments to these functions:

• :width

This keyword argument defines the line width that is used for drawing the line segments and circles. For the functionstream-draw-circle, the border is drawn so that its outer edge is at the specified radius; the width must be less than or equal to the radius. If this keyword argument is omitted ornil, the default value is 1.

• :operation

This keyword argument controls how the values that are being written onto the bitmap combine with the values that are already present; it can be a single boolean constant or a list of boolean constants of length equal to the depth of the bitmap. If this keyword argument is omitted ornil, the bitmap output stream's operation is used. You can find that operation by using the functionstream-operation.

• :foreground

This keyword argument is a string, symbol, or a valid pixel color number for the specified bitmap. If this keyword argument is omitted ornil, the default value is the default foreground of the specified bitmap.

You can specify either the:foreground or the:operation argument, but not both.

See Also: draw-circle, draw-line, draw-polyline, stream-operation

Syntax:stream-linefeed-distance bitmap-output-stream

The functionstream-linefeed-distance accesses the linefeed distance of a bitmap output stream.

You can use the Common Lisp macrosetf with this function to modify a bitmap output stream's linefeed distance. When a bitmap output stream is created, its linefeed distance is the height of the initial font.

A stream's linefeed distance is used when one of the Common Lisp output functions sends a newline character to the bitmap output stream. The bitmap output stream's y-coordinate is incremented by the linefeed distance, and the x-coordinate is set to 0.

Syntax:stream-operation bitmap-output-stream

The functionstream-operation returns a bitmap output stream's defaultbitblt operation, which is used in writing characters or figures to the bitmap output stream's bitmap.

You can use the Common Lisp macrosetf with this function to set a new value. The new value must be an acceptable first argument to the Common Lisp functionboole.

;; Create a bitmap.
> (setq x (make-bitmap :height 100 :width 200))
#<Bitmap 200x100x1 AD476B>

;; Create a bitmap output stream to that bitmap.  Specify 
;; an operation.
> (setq b-o-s (make-bitmap-output-stream :bitmap x :operation boole-1))
#<Output-Stream to #<Bitmap 200x100x1 AD476B> AD54B3>

;; The stream operation of b-o-s is the specified operation.
> (eql (stream-operation b-o-s) boole-1)
T

stream-x-position Function

stream-y-position Function

Syntax:stream-position bitmap-output-stream&optional result-position

Syntax:stream-x-position bitmap-output-stream

Syntax:stream-y-position bitmap-output-stream

These functions return the output position of a bitmap output stream. The output position specifies the next position for writing to the bitmap output stream's bitmap.

• stream-position returns a position.

• stream-x-position returns the x-coordinate of the position.

• stream-y-position returns the y-coordinate of the position.

If a result-position argument is given for the functionstream-position, that position is modified to the output position and then returned. Otherwise, a new position is created and returned.

You can use the Common Lisp macrosetf with these functions to modify a bitmap output stream's position.

When a bitmap output stream is created, its stream position is the position whose x-coordinate is 0 and whose y-coordinate is the baseline height of the initial font.

;; Create a bitmap and a bitmap output stream.
> (setq b-o-s (make-bitmap-output-stream :width 100 :height 200))
#<Output-Stream to #<Bitmap 100x200x1 AD75BB> AD8463>

;; Check the initial value.
> (and (= 0 (stream-x-position b-o-s))
       (= (font-baseline *default-font*) 
          (stream-y-position b-o-s)))
T

;; Set the x position to a new value.
> (setf (stream-x-position b-o-s) 50)
50

Syntax:string-width string font

The functionstring-width determines the width in bits of the specified string when printed in the specified font.

The font argument must be a font, a string, or a symbol. If the argument is a string or a symbol, the functionfind-font is called to find the font named by the string or symbol.

The function can give false results if the string contains any characters that cannot be printed, such as the newline character. The space character is a printable character.

Syntax:unread-any char-or-mouse-event&optional mouse-input-stream

The functionunread-any returns a character or mouse event structure to the front of a mouse input stream's queue. The character or mouse event structure must be the same object that was last read from the queue.

The mouse-input-stream argument specifies a mouse input stream. If this argument is omitted ornil, the mouse input stream that is the value of the functionmouse-input is used. If the value of the mouse-input-stream argument is non-nil, the mouse input stream that is the value of the functionkeyboard-input is used.

See Also: keyboard-input, mouse-input, read-any

Syntax:viewport-active-p viewport

The functionviewport-active-p determines if the specified viewport or window is active.

The viewport argument specifies the viewport or window that is checked.

The functionactivate-viewport makes a viewport active.

See Also: activate-viewport, deactivate-viewport

viewport-at-position Function

Syntax:viewport-at-point x y

Syntax:viewport-at-position position

The functionviewport-at-point interprets its x and y arguments as the coordinates of a point on the screen. It returns as its value the viewport that is displayed at that point.

The functionviewport-at-position is identical toviewport-at-point except that it is passed a single position argument rather than x- and y-coordinates.

These functions return the viewport or window at the specified position relative to the current root viewport.

Syntax:viewport-bitmap viewport

The functionviewport-bitmap returns a viewport's underlying bitmap.

viewport-bitmap-x-offset Function

viewport-bitmap-y-offset Function

Syntax:viewport-bitmap-offset viewport&optional result-position

Syntax:viewport-bitmap-x-offset viewport

Syntax:viewport-bitmap-y-offset viewport

These functions return coordinates that identify the offset from the bitmap's origin of the specified viewport's origin. This offset indicates what part of the bitmap is being displayed in the viewport.

• viewport-bitmap-offset returns the position that represents the offset of the viewport's origin.

• viewport-bitmap-x-offset andviewport-bitmap-y-offset return the x- and y-coordinates of the offset respectively.

If a result-position argument is given for the functionviewport-bitmap-offset, that position is modified to the viewport's offset and returned. Otherwise, a new position containing the viewport's offset is created and returned.

You can use the Common Lisp macrosetf with these functions to change the viewport's offset. Modifyingviewport-bitmap-y causes vertical scrolling. However, if the bitmap is the same size as the viewport, changing the offset withsetf has no effect.

You should avoid setting the offset so that part of the viewport's clipping region falls outside the bitmap boundaries.

viewport-screen-region Function

Syntax:viewport-bitmap-region viewport&optional result-region

Syntax:viewport-screen-region viewport&optional result-region

The functionviewport-bitmap-region returns a copy of a viewport's bitmap clipping region.

The functionviewport-screen-region returns a copy of the entire screen region occupied by the specified viewport or window.

If the optional result-region argument is specified, the result is copied into that region object and returned; otherwise, a new region is created.

viewport-parent Function

Syntax:viewport-children viewport

Syntax:viewport-parent viewport

The functionviewport-children returns a list of the current root viewport's children. The list is in the same order as the children's sibling stack.

The functionviewport-parent returns a viewport's parent.

You can use the Common Lisp macrosetf withviewport-parent to change a viewport's parent. You can only change a viewport's parent when the viewport is inactive. The viewport is put at the top of the sibling stack of its new parent's children.

You can use the Common Lisp macrosetf withviewport-children to change a viewport's children. The second argument tosetf must be a list of inactive viewports. All of the viewport argument's children must also be inactive. The viewport argument's list of children is modified to be the second argument tosetf; children in the sibling stack will appear in the same order as in the viewport list. Any viewport in the viewport list whose parent was not the viewport argument is modified so that its parent becomes the viewport argument. Any viewport whose parent was formerly the viewport argument but that is not in the viewport list becomes detached from the tree.

viewport-background-pixel Function

Syntax:viewport-foreground-pixel viewport

Syntax:viewport-background-pixel viewport

The functionsviewport-foreground-pixel andviewport-background-pixel return the pixel values for the specified viewport that map bits of a depth 1 bitmap onto pixel values for a screen of depth greater than 1.

You can use the Common Lisp macrosetf with these functions to specify a new default viewport foreground pixel or viewport background pixel for a bitmap.

The foreground and background pixels associated with the viewport argument are only used when a bitmap of depth 1 is displayed on a color screen. In all other cases, these values are ignored.

;;; Register primary colors.
> (setup-color-library)
NIL

> (setq *viewport*
      (make-viewport
        :bitmap (make-bitmap :width 20 :height 20 :depth 1)
        :viewport-foreground "BLUE"
        :viewport-background "GREEN"))
#<Viewport 20x20 at (0,0) onto #<Bitmap 20x20x1 F34E23> F34F83>

> (viewport-foreground-pixel *viewport*)
3

> (viewport-background-pixel *viewport*)
2

> (setf (viewport-foreground-pixel *viewport*) "RED")
1

> (viewport-foreground-pixel *viewport*)
1

Syntax:viewportp object

The predicateviewportp tests whether its object argument is a viewport. It is true if object is a viewport.

;;; To run this example, you must have already initialized the
;;; Window Tool Kit.
;; Create a 10x10 bitmap and a viewport onto that bitmap.
;; Note that make-viewport returns two values, the viewport and
;;  the bitmap.
> (multiple-value-setq (vwpt btmp) 
    (make-viewport :width 10 :height 10))
#Viewport 10x10x1 at (0,0) onto #<Bitmap 10x10x1 40D4E5> 40D51D>

> (viewportp vwpt)
T

> (viewportp btmp)
NIL

Syntax:viewport-user-data viewport

The functionviewport-user-data returns the information that is specified in the:user-data keyword argument tomake-viewport andinitialize-viewport.

The viewport argument specifies the viewport that contains the data.

You can use the Common Lisp macrosetf with this function to alter the contents of the:user-data argument.

See Also: initialize-viewport, make-viewport

Syntax:who-window

The functionwho-window returns the window that is currently being used for output by the who process.

You cannot use the Common Lisp macrosetf to modify this window. You can use the functionmake-new-who-window to change the window of the who process.

See Also: make-new-who-window

window-calculate-vertical-scroll-ratio Function

Syntax:window-calculate-horizontal-scroll-ratio window

Syntax:window-calculate-vertical-scroll-ratio window

The functionswindow-calculate-horizontal-scroll-ratio andwindow-calculate-vertical-scroll-ratio calculate the horizontal and vertical scroll ratios respectively for the specified window.

You can use the Common Lisp macrosetf with these functions to modify the values of the:calculate-horizontal-scroll-ratio and:calculate-vertical-scroll-ratio keyword options tomake-window for the specified window.

See Also: make-window, window-horizontal-scroll-ratio, window-calculate-vertical-scroll-ratio

Syntax:window-frame window

The functionwindow-frame returns the window frame that is associated with a given window.

The window frame can be thought of as a special bitmap; the image that this bitmap displays on the screen is the window's frame. You cannot modify the bits of this special bitmap in any way without signaling an error. You can attach active regions to window frames in the same way that you normally attach active regions to bitmaps.

You cannot use the Common Lisp macrosetf with this function.

window-vertical-scroll Function

Syntax:window-horizontal-scroll window

Syntax:window-vertical-scroll window

The functionswindow-horizontal-scroll andwindow-vertical-scroll return the scroll method used by a specified window.

The argument to each function must be a window.

> (window-horizontal-scroll test-window)
#<Compiled-Function WINDOWS::DEFAULT-HORIZONTAL-SCROLL-METHOD 36BD27>

window-outer-border-width Function

Syntax:window-inner-border-width window

Syntax:window-outer-border-width window

The functionwindow-inner-border-width returns the width of the inner border of the window.

The functionwindow-outer-border-width returns the width of the outer border of the window.

The window border consists of two strips: the black strip around the edge of the window is the outer border, and the white strip inside the black strip is the inner border.

Thesetf macro can be used with these functions to modify the widths of the inner and outer borders of a window.

Syntax:window-inside-region window&optional region

The functionwindow-inside-region returns the region inside the specified windows borders. The region is in screen coordinates.

If you specify the optional region argument, that region is returned.

window-title-font Function

Syntax:window-title window

Syntax:window-title-font window

The functionwindow-title returns the title of a window as a string.

The functionwindow-title-font returns the font in which a window's title is displayed.

You can use the Common Lisp macrosetf with the functionwindow-title to modify the title of a window. The second argument tosetf must be a string.

You can use the Common Lisp macrosetf withwindow-title-font to redraw the title of a window in a new font. The second argument tosetf must be a font, a string, or a symbol. If the argument is a string or a symbol, the functionfind-font is called to find the font named by the string or symbol.

;;; To run this example, you must have already initialized the
;;; Window Tool Kit.
;; Create a window with the title "hello".
> (setq w (make-window :width 100 :height 200 :title "hello"))
#<Window 100x200x1 at (0,0) 19C513>

> (window-title w)
"hello"
;; Note that the title font is *default-font*.

> (eq (window-title-font w) *default-font*)
T
;; Modify the title.

> (setf (window-title w) "new-name")
"new-name"

> (window-title w)
"new-name"

Syntax:window-user-data window

The functionwindow-user-data returns the information that is specified in the:user-data keyword argument tomake-window andinitialize-window.

The window argument specifies the window that contains the data.

You can use the Common Lisp macrosetf with this function to alter the contents of the:user-data argument.

See Also: initialize-window, make-window

window-horizontal-scroll-ratio Function

Syntax:window-vertical-scroll-ratio window

Syntax:window-horizontal-scroll-ratio window

The functionswindow-vertical-scroll-ratio andwindow-horizontal-scroll-ratio return the vertical and horizontal scroll ratio respectively of a given window.

The scroll ratio is a Common Lisp ratio between 0 and 1. Generally the scroll ratio is the ratio of the current location of the window to the size of the window's underlying bitmap. However, window system developers can redefine the methods for scrolling and for calculating these ratios so that scrolling can be performed over an abstract bitmap or extent.

You can use the Common Lisp macrosetf with these functions to specify a vertical or horizontal ratio for the given window. If the value of the ratio is set tonil, the window cannot scroll and the scroll bars disappear.

See Also: make-window, window-calculate-horizontal-scroll-ratio, window-calculate-vertical-scroll-ratio

Syntax:windowp object

The predicatewindowp tests whether its object argument is a window. It is true if object is a window.

;;; To run this example, you must have already initialized the
;;; Window Tool Kit.
> (setq w (make-window :width 100 :height 200 :title "hello"))
#<Window 100x200x1 at (0,0) 87F32E>

> (windowp w)
T

> (windowp 7)
NIL

Syntax:windows-available-p &key :display

The functionwindows-available-p checks the Lisp environment for a window system that is capable of supporting the Window Tool Kit.

The functionwindows-available-p returns as values the display width in pixels, the display height in pixels, and the number of display planes if a Window System can be run from the current process; otherwise, the function returnsnil. The returned display parameters can be used in subsequent calls toinitialize-windows.

The:display keyword argument specifies the display used for Window Tool Kit interactions. It must be a string of one of the following forms:

"host"

"host:display-number"

The default value is supplied by the environment variableDISPLAY.

See Also: initialize-windows

Syntax:with-fast-drawing-environment {form}*

The macrowith-fast-drawing-environment groups display operations. Overhead operations that are required to produce output are executed only once rather than for every display operation in the group.

The output for the group might not appear on the screen until the macro is exited. Therefore, you should not use this macro to group operations that require user input or that will run for a long time.

Syntax:with-mouse-documentation string-or-function {form}*

The macrowith-mouse-documentation replaces any mouse documentation and executes the specified forms. Upon exit, the mouse documentation is restored to its original value.

The string-or-function argument is a string or a function of no arguments that returns a string describing actions the mouse can perform when it is in the current active region.

The mouse documentation appears in the who window.

with-mouse-methods-preempted-globally Macro

Syntax:with-mouse-methods-preempted bitmap {form}*

Syntax:with-mouse-methods-preempted-globally region {form}*

The macrowith-mouse-methods-preempted evaluates each of its form arguments. While these forms are being evaluated, any active region that is not attached to the bitmap argument is disabled. Its methods are not called even if a mouse event occurs inside it.

The macrowith-mouse-methods-preempted-globally disables all active regions in the current root viewport except the active region of interest. A mouse event in any area of the current root viewport is treated as though it happened in the specified region.

The bitmap argument towith-mouse-methods-preempted can be a bitmap, an active region, ornil. If the value isnil, all active regions are disabled.

The region argument towith-mouse-methods-preempted-globally must be an active region.

The results of evaluating the last form are returned as the results ofwith-mouse-methods-preempted andwith-mouse-methods-preempted-globally.

Syntax:with-root-viewport root-viewport {form}*

The macrowith-root-viewport allows you to temporarily use the specified root viewport instead of the current one during the execution of the form arguments.

Generated with Harlequin WebMaker