Common Graphics Variables

This variable can be used to create translucent effects when drawing lines, filling areas, and displaying pixmaps, where anything that was drawn earlier appears to partially "show through" new content that is drawn later.

When the value is true, a drawing or filling function such as draw-line or fill-polygon will use the alpha component of the current foreground-color that is being used for the drawing. See make-rgb, where the alpha component of a color can be specified. When displaying pixmaps, if the alpha argument is passed to copy-to-stream then it will be used whenever the value of this variable is true.

An alpha value is an integer between 0 and 255 inclusive. A value of 255 represents full opacity, where the pre-existing background does not show through at all, and is no different than drawing without alpha blending. A value of 0 represents full transparency, where the new content is not seen at all (and so of course is not useful). A typical value might be 192, which will blend three-fourths of the color that's being drawn with one-fourth of the colors that the pixels had before. This lets the underlying image show through a little while mostly showing the new content in front of it.

The default value is nil for backward compatibility and efficiency. Typically you would bind this variable to true around a block of drawing code where alpha blending is desired. Or this variable could simply be set to true globally if the effect is desired everywhere.

Caveat: When using alpha-blending, any existing background at all will be blended with the content that's being drawn. Even with a fairly large alpha value like 192 (for three-fourths opacity), background areas that are white will still show through by one-fourth, making the content that's being drawn appear somewhat washed-out. And new content that's drawn over black areas of the background will be darker than they would be without alpha-blending. This may limit the usefulness of alpha blending to special effects, rather than where you want the content that's being drawn in front to look as good as it can look by itself.

Example

This example simply generates a set of random triangles and fills them with random colors that use random amounts of alpha blending, and adds bilateral symmetry. Clicking the window generates another image. The alpha blending works only on the Windows platform, but the code runs elsewhere.

(defclass triangle-window (frame-window)
  ((triangles :accessor triangles :initform nil))
  (:default-initargs
      :double-buffered t
    :scrollbars nil
    :width 600 :height 600))

(defmethod make-triangles ((window triangle-window))
  (let* ((width (interior-width window))
         (height (interior-height window))
         triangles vertices mirrors x y color)
    (dotimes (j (+ 3 (random 12)))
      (setq vertices (make-array 3))
      (setq mirrors (make-array 3))
      (dotimes (k 3)
        (setq x (random width))
        (setq y (random height))
        (setf (aref vertices k)(make-position x y))
        (setf (aref mirrors k)(make-position (- width x) y)))
      (setq color (make-rgb :red (random 255) :green (random 255)
                            :blue (random 255) :alpha (random 255)))
      (push (list (list color vertices)
                  (list color mirrors))
            triangles))
    (setf (triangles window) triangles)))

(defmethod redisplay-window ((window triangle-window) &optional box)
  (declare (ignore box))
  (clear-page window)
  (unless (triangles window)
    (make-triangles window))
  (let* ((*antialiasing* t)
         (*alpha-blending* t))
    (dolist (pair (triangles window))
      (dolist (triangle pair)
        (with-foreground-color (window (first triangle))
          (fill-polygon window (second triangle))))
      (dolist (triangle pair)
        (with-foreground-color (window gray)
          (draw-polygon window (second triangle)))))))

(defmethod mouse-left-down ((window triangle-window) buttons position)
  (declare (ignore buttons position))
  (make-triangles window)
  (invalidate window))

(make-window :triangle-window
  :class 'triangle-window)

alt-key

The value of this constant is an integer that will be passed as a bit flag component of the buttons argument to various event-handling generic functions such as mouse-left-down if either Alt key was down when the event occurred. See extended-key for how to tell whether the right or left key was down.

On the Windows platform, the righthand Alt key will be handled by Common Graphics only if the reserve-righthand-alt-key configuration option is nil.

On the Apple Mac, the alt-key corresponds to the Option/Alt key and the meta-key corresponds to the Command key (also called the Apple key).

*antialiasing*

When this variable is true, drawing and filling functions such as draw-line, draw-ellipse, and fill-polygon will draw straight and curved lines and edges using antialiasing. And draw-string-in-box will draw antialiased text.

This technique produces smoother-looking lines and edges by using a variety of colors for edge pixels to interpolate between the foreground and background colors.

The default value is nil. Typically you would bind this variable to true around a block of drawing code where antialiasing is desired. Or this variable could simply be set to true if the effect is desired everywhere.

Caveats: Antialiased drawing is generally somewhat slower than otherwise, though not by a lot with a decent video adapter. Antialiased text looks fuzzier than non-antialiased, though is perhaps easier on the eyes. Antialiasing appears to have no effect on non-TrueType fonts. Antialiasing may not work with certain font faces, such as FixedSys in 8.2.beta but should work in the final release.

You can't feasibly bind this variable around the drawing of widgets, which draw themselves asynchronously, so some widgets that are drawn by Lisp provide the antialias-lines and antialias-text properties for this.

app-starting-cursor

The cursor-handle for a mouse cursor in the shape of an arrow with an hourglass next to it. This could be shown while an application is starting up.

application-icon

A pre-defined icon showing a square with blank interior. Code that might run in CG/JS mode should instead call the application-icon function.

arrow-cursor

The cursor-handle for a mouse cursor in the shape of an arrow. This is often used as the default mouse cursor.

*beep-duration*

This variable affects the sound that's produced when calling the function beep in web browser mode to emit a short beep, typically for a warning or error.

*beep-duration* is the number of milliseconds that the sound will last, and the initial value is 80 (less than one-tenth of one second).

*beep-frequency*

This variable affects the sound that's produced when calling the function beep in web browser mode to emit a short beep, typically for a warning or error.

*beep-frequency* is the pitch of the sound in herz (cycles per second), and the initial values is 440 (the A above middle C).

*beep-loudness*

This variable affects the sound that's produced when calling the function beep in web browser mode to emit a short beep, typically for a warning or error.

*beep-loudness* ranges from 0 to 100 (inclusive). The initial value is 12. WARNING: 100 is extremely loud on the tested machine.

black

black-texture

Compatibility note

Prior to version 8.0, the value of this variable was a texture rather than a pixmap. If you had passed the value to copy-pixels-to-stream, for example, then you would now need to pass it to copy-to-stream instead.

blue

*browser-server-port*

The port at which CG/JS is communicating with one or more web browsers. If a particular port was specified for the "Browser Server Port" property of a project or with a --browser-server-port command line argument, then the value will be that port number. Otherwise it will be the free port that the operating system selected.

*cg-is-initialized*

The value of this variable is true if Common Graphics is currently initialized, and nil if not. Common Graphics is initialized when initialize-cg has been called (and returned t, indicating success) more recently than exit-cg.

*cg-timer-resolution*

This variable is no longer used. It was related to the GTK version of CG, which is no longer supported.

*cgjs-client-options*

The value of this variable is an association list of stylistic options such as the color and thickness of window borders, the font used in all menus, and the delay before showing a child menu. These are typically system-wide parameters that affect all applications in a windowing system, but there's no equivalent in the web browser world and so CG defines them itself in this alist.

The function cgjs-client-option could be used to return any of these values, such as (cgjs-client-option :browser-keychords). The setf could be used to modify this alist, though that will have no effect after CG has already started up and sent the values to the web browser, and so special means are provided for specifying custom values.

To modify these style options for a project, use the "Style Options" widget on the CG/JS tab of the Project Manager dialog in the IDE. Or programmatically set the style-options of the cgjs-options of the project.

Here is the actual code for this variable, with comments that explain each option.

;; Options that affect how the web browser client works, and which
;; are passed over to the web browser for the JavaScript code to use.
;; These are mostly stylistic things, such as the color and thickness
;; of window borders and the font to use in all menus.

(copy-tree
 `(

   ;; ------------------------------------------------------------
   ;; This first set (most of them) gets passed to the web browser
   ;; just once at startup time.
   ;; ------------------------------------------------------------

   ;; Keystrokes that should get passed to the web browser for its
   ;; default behavior.  Each keystroke should contain a main key name
   ;; that's preceded by zero or more shift key names, with a plus
   ;; character between names.  The possible shift key names are
   ;; Shift, Control, and Alt, plus Meta on the Mac (for the Command
   ;; key).  When the the main key is a letter key, it should be the
   ;; uppercase character.  For numeral and punctuation keys, it
   ;; should be the unshifted character.  Other special key names
   ;; (which come from JavaScript) include Enter, Escape, Backspace,
   ;; Tab, Home, End, PageUp, PageDown, ArrowLeft, ArrowUp,
   ;; ArrowRight, ArrowDown, Insert, Delete, F1 through F12,
   ;; Shift, Control, Alt, PrintScreen, and OS.  (OS is for the
   ;; Windows/Start key on a Windows keyboard.)  These names are all
   ;; case-sensitive.
   ;; This one can be specified as the ide:browser-keychords
   ;; property of the cgjs-options of a project.
   (:browser-keychords 
    ("F11"                 ;; toggling full-screen mode
     "Control+Meta+F"      ;; full-screen mode on the Mac
     ;; zooming (scaling) the whole app
     "Control+0" "Control+-" "Control+=" "Control+Shift+-" "Control+Shift+="
     ;; zooming keys on Mac; Meta is the Command key
     "Meta+0" "Meta+-" "Meta+=" "Meta+Shift+-" "Meta+Shift+="))

   ;; The text to appear in the small tab above the application.
   ;; This should be a lisp string, or nil to use a project property.
   ;; This one can be specified as the ide:title-for-browser-tab
   ;; property of the cgjs-options of a project.
   (:title-for-browser-tab nil)

   ;; The characters at which draw-string-in-box can wrap text
   ;; to a new line.
   (:string-in-box-wrapping-delimiters (#\space))

   ;; Whether scroll bars will appear on the logical screen, which
   ;; is the web browser interior, whenever top-level windows exist
   ;; partly or fully beyond the width or height of the logical screen.
   ;; (When this is turned on, currently there's a problem in both
   ;; Firefox and Chromium when the app window is maximized and the user
   ;; drags the browser size smaller, where occasionally the browser will
   ;; needlessly turn on the scrollbars of the screen, causing them
   ;; to cover part of the application window on the right and bottom.)
   (:scrolling-screen nil)

   ;; Whether a shadow effect will be drawn below and to the right of
   ;; all windows that have borders.
   (:show-box-shadows t)

   ;; The color of the logical screen, which is the web browser interior.
   (:screen-background-color
    ,(make-rgb :red #xdd :green #xdd :blue #xdd))

   ;; The default background color for all windows of class
   ;; dialog-mixin.  This value is returned by the function
   ;; system-dialog-background-color.
   (:dialog-background-color
    ,(make-rgb :red #xf0 :green #xf0 :blue #xf0))

   ;; The default background color for all tab-control widgets.
   (:tab-control-background-color
    ,(make-rgb :red #xf8 :green #xf8 :blue #xf8))

   ;; The text color that's used in widgets and menu-items whose
   ;; "available" property is nil, indicating that they will not
   ;; respond.  This value is also returned by the function
   ;; system-disabled-color.
   (:unavailable-text-color
    ,(make-rgb :red #x77 :green #x77 :blue #x77))

   ;; The colors that are used for the borders and title text
   ;; of a window when the window is either the selected child
   ;; of its parent or not.
   (:selected-window-title-color ;; the text color
    ,(make-rgb :red #x00 :green #x00 :blue #x00))
   (:unselected-window-title-color
    ,(make-rgb :red #x55 :green #x55 :blue #x55))
   (:selected-window-border-color
    ,(make-rgb :red #x70 :green #x98 :blue #xff)
    #+previous ;; a bolder cyan/blue
    ,(make-rgb :red #x00 :green #xaa :blue #xff))
   (:unselected-window-border-color
    ,(make-rgb :red #x88 :green #xb0 :blue #xf0)
    #+previous ;; a bolder cyan/blue
    ,(make-rgb :red #x77 :green #xcc :blue #xff))
   (:selected-widget-border-color
    ,(make-rgb :red #x00 :green #x00 :blue #xcc))
   (:unselected-widget-border-color
    ,(make-rgb :red #xaa :green #xbb :blue #xcc))

   ;; The colors that are used in a thin outer edge of a window frame,
   ;; partly to provide a 3D look and also to clarify where the frames
   ;; of multiple windows overlap.  These colors are returned by the
   ;; functions system-edge-highlight-color and
   ;; system-edge-shadow-color.
   (:frame-highlight-color
    ,(make-rgb :red #xbb :green #xee :blue #xff)
    #+previous
    ,(make-rgb :red #x88 :green #xdd :blue #xff))
   (:frame-lowlight-color
    ,(make-rgb :green #x88 :blue #xaa))

   ;; The height in pixels of every menu-bar.  It should be big
   ;; enough for the current menu-bar font (below).
   (:menu-bar-height 24)

   ;; The font to use in every menu-bar.
   (:menu-bar-font-face "sans-serif")
   (:menu-bar-font-size 14)

   ;; The background-color of every menu-bar.
   (:menu-bar-color ,(make-rgb :red #xc7 :green #xdd :blue #xee))

   ;; The font to use in every menu.  This should be a JavaScript font name.
   (:menu-font-face "sans-serif")
   (:menu-font-size 13)

   ;; The number of pixels of vertical and horizontal blank space
   ;; around the text within each item in a menu or item-list widget.
   (:menu-item-vpadding 3)
   (:menu-item-hpadding 3)
   (:list-item-vpadding 2)
   (:list-item-hpadding 4)

   ;; The radius in pixels of the corners of button widgets.
   ;; nil means not rounded at all.
   (:button-corner-radius nil)

   ;; The background-color for an item in a menu or item-list widget
   ;; when the item is highlighted by moving the mouse over it (for
   ;; a menu) or using the arrow keys.
   (:menu-item-highlighted-color
    ,(make-rgb :red #x88 :green #xcc :blue #xff))
   (:list-item-highlighted-color
    ,(make-rgb :red #xcf :green #xdf :blue #xef))

   ;; The number of milliseconds to pause before showing a child menu
   ;; after the mouse is moved to that child menu's title in the
   ;; parent menu.  This avoids showing child menus as you quickly
   ;; move the mouse over their titles, especially because they might
   ;; cover the parent menu when the browser window is not very wide.
   ;; If the value is zero, then there is no delay.
   (:child-menu-delay 500) ;; bug26409

   ;; -------------------------------------------------------------
   ;; The rest are passed later whenever particular CG functions
   ;; such as make-window are called, rather than being initialized
   ;; just once at startup time.
   ;; -------------------------------------------------------------

   ;; These are used for any window whose border property is :frame,
   ;; :plain, or :dialog-box, where the first one is used when the
   ;; resizable property is true, and the second when it is nil.
   (:resizing-border-width 8)
   (:plain-border-width 2)

   ;; Used when the border property is :palette.
   (:palette-border-width 2)

   ;; Used when the border property is :static or :black.
   (:static-border-width 1)

   ;; The pixel height of window title bars (not including the
   ;; window's border).  (The height of the font for the title
   ;; will be automatically calculated to fit this title bar
   ;; height, and the sans-serif JavaScript font is always used.)
   (:title-height 19)

   ;; The amount by which the font-size of a stream's current
   ;; font will be multiplied to derive the line-height of the
   ;; stream, which determines how far apart lines of text get
   ;; printed onto the stream.  The default factor of 1.2 will
   ;; leave empty space between text lines that's one-fifth
   ;; as tall as the font characters.  This affects the built-in
   ;; line spacing of a text-edit-pane, and the printing of
   ;; newlines in regular windows.
   (:line-height-factor 1.2)

   ;; These are for the similarly-named CG functions.  Those
   ;; functions will return the values that are established here.
   (:system-foreground-color ,black)
   (:system-background-color ,white)
   (:system-highlight-foreground-color ,black)
   (:system-highlight-background-color 
    ,(make-rgb :red 96 :green 232 :blue 255))
   (:system-disabled-color
    ,(make-rgb :red 109 :green 109 :blue 109 :alpha 255))
   (:system-app-workspace-color
    ,(make-rgb :red 171 :green 171 :blue 171 :alpha 255))

   ;; ---------------------------------
   ;; The rest are probably not useful.
   ;; ---------------------------------

   ;; Whether to use the native JavaScript combo-box (which
   ;; wasn't fully working out) rather than one that's constructed
   ;; from more basic HTML elements.
   (:use-native-combo-box nil)

   ;; The interval in seconds between custom pongs that the CGJS
   ;; client will send to help determine when a client may have
   ;; died, though other techniques now appear to be sufficient.
   ;; Zero means that the client will never send custom pongs
   ;; at all (which requires a constant timer).
   (:pong-interval 0))))

*cgjs-reply-timeout*

When CG sends a message to the web browser and that message requires a reply, this is the number of seconds that CG will wait before timing out. Normally when a reply takes a while, it is because earlier messages have accumulated in the browser's queue. This is not an error, and it is necessary to wait on the browser to catch up. So the default value of this variable is large (360, meaning six minutes), to handle only an exceptional delay that may indicate a fundamental problem. If the timeout is reached, then errors may result because the calling function will receive nil as the answer rather than the expected value. A modal dialog will explain this the first time it happens.

*cgjs-server-options*

An association list that holds options that affect how the CG/JS server works, and which are used only in lisp code on the server side. These option values will be in common for all of the multiple clients that are sharing the same running CG/JS server.

This alist could be examined for informational purposes, or by calling cgjs-server-option on individual option names. But this alist should not be modified directly. To set the values for a project, use the CG/JS tab of the Project Manager dialog in the IDE.

character-message

The value of this variable is the event number corresponding to a character being typed.

*check-cg-args*

This variable is no longer supported. In releases prior to 7.0, it allowed enabling argument type checking. This type checking was possible because the version of Common Graphics used by the IDE contained extra code for checking argument types. In 7.0, the version used by the IDE and the version used in applications are the same and the extra code is no longer present.

*clipboard*

This variable holds the stack of lisp clipboard values. The value is a list where each element is an item in the Lisp clipboard stack, with the first item in the list being the topmost (most recent) item on the stack. Each item is a cons whose car is the actual clipboard value and whose cdr is the keyword symbol naming its OS clipboard format. Some of the clipboard values near the top may be the symbol :needs-conversion; this indicates a value that was copied in another application and has not yet been pasted in Lisp --- Lisp avoids actually reading the value from the OS clipboard until needed, for efficiency.

*color-gradient-blend*

This variable specifies how the lightness of the fill color will vary along the line from its lightest shade to its darkest, when filling an area while *color-gradient-filling* is true.

The default value is nil, which means that the lightness will vary in a linear manner. Otherwise the value should be an association list, where each element in the list is a list of two real numbers between zero and one (exclusive). The first number indicates a fraction of the distance from the lightest point to the darkest point. The second number indicates a fraction of the change in lightness from the lightest shade to the darkest shade, which will be used at the corresponding point. The first number in each pair should be greater than the first number in the preceding pair, and likewise for the second number.

This is best explained with an example. Here's what would be drawn if *color-gradient-direction* is :vertical and *color-gradient-blend* is ((.2 .3) (.8 .5)). The lightest version of the fill color will be used at the very top of the filled area. At one-fifth (.2) of the distance to the bottom of the filled area, the color will be darker by 30% (.3) of the total lightness range, and will darken linearly between the top and that point. At four-fifths (.8) of the distance, the color will have darkened by 50% (.5) from the lightest shade. It will darken by the remaining 50% of the lightness range between there and the bottom. The lightness range itself is controlled by *color-gradient-intensity*.

That particular value would distribute most of the lightness change toward the top and bottom edges, varying the lightness only by 20% over the middle three-fifths of the area. That creates a three-dimensional effect that looks like a raised button that's relatively flat in the middle. It also may be suitable for a label that's drawn in the middle of the area, to avoid a large color shift under the text that may decrease the readability. (The linear shift that results from the default value of nil tends to look somewhat like a horizontal line drawn through the middle of the text.) The example value also distributes more of the color shift toward the darker edge than toward the lighter edge, to avoid darkening the middle area more than needed.

Also see the macro with-named-gradient which provides a convenient way to set and clear this variable.

*color-gradient-direction*

This variable indicates the direction along which the lightness of the fill color will change, when filling an area while *color-gradient-filling* is true.

The value should be one of the keyword symbols :vertical, :horizontal, :forward-diagonal, or :backward-diagonal. The default is :vertical. If :vertical, the fill color will become gradually darker in the downward direction. If :horizontal it will darken in the rightward direction. If :forward-diagonal it will darken from the upper left to the lower right, and if :backward-diagonal it will darken from the upper right to the lower left.

Also see the macro with-named-gradient which provides a convenient way to set and clear this variable.

*color-gradient-filling*

When this variable is true, filling functions such as fill-ellipse and fill-polygon will fill an area with a color gradient for a highlighted or three-dimensional effect.

The default value is nil. Typically you would bind this variable to true around a block of drawing code where gradient filling is desired. It is probably not a good idea to globally set this variable to true, because gradient filling is usually not desirable absolutely everywhere.

As a special case, erase-contents-box and erase-contents-box-x-y will bind this variable to nil to prevent default redisplay-window methods from clearing the background of windows with a gradient effect, even if this variable is globally true.

Also see the macro with-named-gradient which provides a convenient way to set and clear this variable.

*color-gradient-intensity*

This variable controls the intensity of gradient filling when *color-gradient-filling* is true. The larger the value, the greater the difference there will be between the lightest and darkest shades that are drawn, for a more pronounced effect.

When gradient filling is enabled, colors tend to come out darker than otherwise. If that's undesirable, then decreasing the value of this variable will decrease that effect. The reason is that the range of colors that's drawn is adjusted so the lightest shade has its lightest red, green, or blue component at its maximum value, with the other components at lower values to maintain the same hue; then each component of the darkest shade will be darker than those by the amount specified by this variable. This means that the average shade that's drawn will often be significantly darker than the original non-gradient shade, especially when it is a relatively light color.

Also see the macro with-named-gradient which provides a convenient way to set and clear this variable.

control-key

The value of this constant is an integer that will be passed as a bit flag component of the buttons argument to various event-handling generic functions such as mouse-left-down if either Control key was down when the event occurred. See extended-key for how to tell whether the right or left key was down.

*copied-character-format*

The initial value of this variable is nil. Its value must be either nil or an instance of the character-format class. It should not be set directly, but should be set using the Edit | Copy Format command on a rich-edit-menubar (on a rich-edit-dialog. Edit | Paste Format can be used to paste the format to another rich-edit-pane location.

Note that these Edit menu commands are only on the Edit menu of a rich-edit menubar, not on the standard Allegro CL Edit menu.

See cg-rich-text.html for information about rich text editing in Common Graphics.

crlf

A string that is two characters long, with the two characters being #\return and #\linefeed. This string may be useful for constructing strings that contain DOS-style newlines in them, such as

(concatenate 'string "first line" crlf "second line")

cross-cursor

The cursor-handle for a mouse cursor that is a thin cross or plus sign. It is useful for selecting a precise position, such as when calling get-position.

cyan

dark-blue

dark-cyan

dark-gray

dark-gray-texture

Compatibility note

dark-green

dark-magenta

dark-red

dark-yellow

*default-cg-bindings*

A variable whose value should be passed as the :initial-bindings argument to make-process or related operators like process-run-function in order to make the process debuggable in the IDE and/or to allow the process to create Common Graphics windows and receive events for them. If it is not feasible to specify the initial bindings of the process, then see with-cg-bindings.

This list is used by Common Graphics itself when it starts its own processes, such as the IDE GUI process and the Listener 1 process (which is the Debug Window listener (note: IDE process names may change).

If you need additional bindings, make a list that is the union of this list and the list of additional bindings. Despite the fact that this symbol names a variable (rather than a constant), its value should not be modified.

When the app might be run in CG/JS mode (in a web browser), then a special binding of *system* must be added to the bindings. That additional binding is OK in any mode, so here the general way to pass the bindings for any mode:

(mp:process-run-function
  (list :name "Second CG Process"
        :initial-bindings
        (acons '*system* *system* *default-cg-bindings*))
  'second-process-startup-function)

*default-cg-message-timeout*

The value of this variable is the number of milliseconds that a Common Graphics thread will wait before timing out with an error when it sends a message to a window that was created in another thread. The default is 3000 (a generous three seconds), but it is still possible for a message timeout to occur if the second thread is busy for longer than this period, because of running code that was triggered by a single event or by a number of events that were all queued up before the first thread sent the message. Many Common Graphics functions internally send messages to the window on which they are invoked or to that window's relatives.

Message timeouts are possible in a generated Common Graphics application only if it starts up additional Common Graphics threads. (By default, an application generated from a project uses only a single thread, without starting up multiprocessing at all.) When multiple Common Graphics threads are used, possible timeouts can still be prevented by not mixing windows that are created in different threads into a single window hierarchy, and not calling code in one thread that accesses windows created in another thread. Timeouts are still possible in the IDE, since it uses multiple Common Graphics threads that sometimes mix windows into a single hierarchy but the likelihood should be very low at the default value of this variable.

If you write an application where message timeouts are possible, you may want to set this variable to a smaller value during development and testing than in your shipped product, to increase the likelihood of catching timeouts that may occur when the shipped product is run on slower or busier machines. If you experience message timeouts in the IDE, you may want to use a larger value than the default.

This special variable is not bound per-thread initially (and thus is not on the *default-cg-bindings* list), so setting its value in any thread will affect all threads. But it may instead be bound in a particular thread to control only the amount of time that that thread will wait when sending a message to a window in any other thread within the dynamic scope of that binding.

*default-cgjs-external-format*

The external format that will be used by default in CG streams when running in CG/JS mode. The default value is (crlf-base-ef :utf-8s). The "s" at the end of the name stands for "strict", and makes recovery easier after an error such as printing a substring that starts or ends with an unpaired surrogate lisp character that's part of a single extended Unicode character (one that's beyond the 16-bit range). In particular, in CG/JS this avoids a problem otherwise where printing such a bad substring to a CG stream would leave the stream in a state where correct extended Unicode characters fail to print correctly.

CG/JS also sets the global variable *utf-8s-transcoding-error-action* to :count, for use in debugging. If errors such as printing unpaired surrogates do happen, then the value of that variable will change to the number of bad characters that have been encountered so far. You could monitor the value of that variable to see if your application code is using invalid substrings.

You could set this variable to (crlf-base-ef :utf-8) if you would rather that errors get signaled, to help track down the source of the problem, though that might lead to repeating errors when trying to view a backtrace.

Alternately, you could set this variable to simply :utf-8 or :utf8-s if you would like files on the Windows platform to be read and written with CR/LF newlines rather than LF newlines. Whenever CG is about to use this external format with internal websocket code where CR/LF newlines are not appropriate, it always first calls crlf-base-ef on the value of this variable to obtain the actual external format to use, so that is not a problem.

*default-header-justification*

The default horizontal justification for a header item on a header-control widget. The initial value is :left.

*default-header-width*

The default pixel width for a header item on a header-control widget. The initial value is 48.

*default-inverted-texture-info*

The value of this variable is a standard texture-info object that may be used by multiple pixmaps for efficiency, if the properties of those pixmaps all happen to match those specified by this texture-info. In addition, this texture-info may be used with typical button-sized pixmaps to cause them to automatically change some of their colors to match the user's Control Panel color scheme.

The invert-p property of this texture-info is t, meaning that it is suitable for use with pixmaps that are defined as source code (with the rows of the source code matching the order of the rows in the image). If you instead are loading pixmaps from files with load-pixmap, then use *default-texture-info* instead to match the row order.

If a pixmap is created by specifying its width, height, bits-per-pixel, and invert-p properties individually such that they all match this special texture-info, and the colors property is specified as the keyword :default, then this texture-info will automatically be used internally.

Example:

Here is how the IDE creates the check-box pixmap that appears in the Component Toolbar. By using *default-inverted-texture-info*, the colors at indices 7, 8, and 15 will automatically change to match the user's Control Panel colors as explained on the page for default-pixmap-color-vector.

(cache-pixmap
 (make-instance 'pixmap
   :name 'check-box
   :contents
   '((7 7 7 7 7 7 7 7 7 7 7 7 7 7 7 7)
     (7 7 7 7 7 7 7 7 7 7 7 7 7 7 7 7)
     (7 15 15 15 15 15 15 15 15 15 15 15 15 15 7 7)
     (7 8 7 7 7 7 7 7 7 7 7 7 7 15 7 7)
     (7 8 0 15 15 15 15 15 15 15 15 15 7 15 7 7)
     (7 8 0 15 15 15 0 15 15 15 15 15 7 15 7 7)
     (7 8 0 15 15 0 0 0 15 15 15 15 7 15 7 7)
     (7 8 0 15 0 0 0 0 0 15 15 15 7 15 7 7)
     (7 8 0 15 0 0 15 0 0 0 15 15 7 15 7 7)
     (7 8 0 15 0 15 15 15 0 0 0 15 7 15 7 7)
     (7 8 0 15 15 15 15 15 15 0 0 15 7 15 7 7)
     (7 8 0 15 15 15 15 15 15 15 0 15 7 15 7 7)
     (7 8 0 15 15 15 15 15 15 15 15 15 7 15 7 7)
     (7 8 0 0 0 0 0 0 0 0 0 0 7 15 7 7)
     (7 8 8 8 8 8 8 8 8 8 8 8 8 15 7 7)
     (7 7 7 7 7 7 7 7 7 7 7 7 7 7 7 7))
   :texture-info *default-inverted-texture-info*))

*default-printer-bottom-margin*

Works like *default-printer-left-margin* except that it applies to the bottom margin. The value of this variable measures the margin from the bottom edge of the page, and the initial value is 500 to indicate a half inch. On the other hand, the bottom-margin property of printer, which is initially derived from this variable, is measured from the top "hardware margin" of the stream as returned by printer-physical-offset. See *default-printer-left-margin* for a further description and links.

*default-printer-left-margin*

The value of this variable is an integer that determines the initial left-margin property of any printer stream that is opened. Its units are one-thousandths of an inch, and so the initial value of 500 indicates a default margin of half an inch. (This arbitrary resolution is used because the variable is independent of any particular printer that would have a particular resolution.)

If the Page Setup dialog is invoked by calling pop-up-printer-setup-dialog, the value of this variable is modified afterwards to reflect the left margin value that the user specified on this dialog (if they do not cancel). An application may also set this variable directly if it knows what printer margins it plans to use.

When a printer stream is opened, Common Graphics sets its left-margin property to the x coordinate at which an application should draw in order to draw at the margin indicated by *default-printer-left-margin*. This left-margin number is different from **default-printer-left-margin*, though, for a couple of reasons. First, the left-margin property is in the stream units of the stream, which an application uses to draw on a stream, rather than the arbitrary one-thousandths of an inch of *default-printer-left-margin*. Second, a printer has a "hardware margin" outside of which it cannot draw.

For a laser printer, the hardware margin is typically about a quarter of an inch. When an application draws at position 0,0 it is actually drawing at the top-left hardware margin. An application can find these hardware margins by calling printer-physical-offset and printer-physical-size, and can compute its own margins from that, but in most cases it is easier to let Common Graphics set up the margins for you, assuming that *default-printer-left-margin* and the other default margin variables are set up as desired. Common Graphics computes the initial left-margin for a printer stream by scaling *default-printer-left-margin* into the stream units of the printer stream and then subtracting the hardware left margin. An application then simply needs to check the margin properties of the printer stream to find the range of coordinates into which it should fit its drawing.

*default-printer-right-margin*

Works like *default-printer-left-margin* except that it applies to the right margin. The value of this variable measures the margin from the right edge of the page, and the initial value is 500 to indicate a half inch. On the other hand, the right-margin property of printer, which is initially derived from this variable, is measured from the left "hardware margin" of the stream as returned by printer-physical-offset. The initial value is 500 to indicate a half inch. See *default-printer-left-margin* for a further description and links.

*default-printer-top-margin*

*default-texture-info*

The invert-p property of this texture-info is nil, meaning that it is suitable for use with pixmaps that were loaded from a file with load-pixmap. (If such a pixmap matches all of the attributes of this special texture-info, including the color order, then this texture-info could be swapped in by calling (setf texture-info) on the pixmap after loading it, to cause the pixmap to match the user's Control Panel colors). If you are instead defining pixmaps as source code (with the rows of the source code matching the order of the rows in the image), then use *default-inverted-texture-info* instead. See that page for an example usage.

If a pixmap is created by specifying its width, height, bits-per-pixel, and invert-p properties individually such that they all match this special texture-info, and the colors property is specified as the keyword :default, then this texture-info will automatically be used internally.

dst

ds~t

d~st

d~s~t

*edit-allowed-types*

This variable is no longer supported. The IDE configuration option file-dialog-source-types provides the default when using the IDE. In applications and in direct calls to ask-user-for-new-pathname and ask-user-for-existing-pathname, a suitable default is provided for the allowed-types argument (this variable used to provide the default). If you wish a different value for that argument to those functions, you must supply the value directly. (file-dialog-source-types is only used to provide a value when using an IDE tool, such as the File | Open menu command.)

*empty-rtf-string*

A Rich Text Format string (rtf string) with no content. See cg-rich-text.html for information about rich text editing in Common Graphics.

Is bound to the second item on the Lisp clipboard. =, == and === are for the convenience of users. For example, (+ = ==) adds together the top two items from the clipboard.

Warning for prolog users

Allegro Prolog also has a variable named ==. Using both the cg package and the prolog package will result in a conflict. If you want to ensure that == refers to prolog:== (the likely desire since cg:== seems to be little used), when the package using both is the current package, evaluate the following forms in order:

(require :prolog)
(shadowing-import (prolog:==))
(use-package :prolog)

===

Is bound to the third item on the Lisp clipboard. =, == and === are for the convenience of users. For example, (+ = ===) adds together the first and third items from the clipboard.

erase

error-icon

A pre-defined icon to indicate that an error has occurred. Code that might run in CG/JS mode should instead call the error-icon function.

*event-loop-processes*

The value of this variable is a list of all processes that are currently inside a call to event-loop, and which therefore can handle Windows messages.

extended-key

The value of this constant is an integer that will be passed as a bit flag component of the buttons argument to virtual-key-down or virtual-key-up if the key being pressed or released is one of several "extended keys". It is probably useful only for determining whether the righthand or lefthand version of the control key or alt key was pressed; this flag bit is passed for the righthand version only.

first-x-button

The value of this constant is the value that corresponds to the first mouse X button in a button-state argument. X buttons are found on the side of some newer mice, where the frontmost button is the "first" one. See also *ignore-mouse-x-buttons*.

gray

gray-texture

Compatibility note

green

*grid-border-mouse-slack*

The number of pixels away from a grid cell border where it can still be moused. Initial value is 6.

*grid-widget-scrollbar-thickness*

The breadth in pixels of the CG scroll-bar widgets that any grid-widget uses as internal child windows. The value is a positive integer. This may be of interest for calculating things like the width to use for a grid-section. An application could change the value to customize this for all grid widgets, though that should be done before any grid widgets are created, because the value affects calculations that CG does for all of them.

*gtk-compatibility-warning-action*

This variable is no longer used. It was related to the GTK version of CG, which is no longer supported.

hand-cursor

This variable is no longer used. It was related to the GTK version of CG, which is no longer supported.

The platform-independent way to obtain the hand cursor is to call find-cursor on the symbol :hand-cursor. This will return a CG cursor object on all platforms.

(find-cursor :hand-cursor)

help-cursor

The cursor-handle of a mouse cursor that looks like an arrow with a question mark next to it. It could be used when the mouse is over something that would provide help when clicked.

*ignore-mouse-x-buttons*

When the value of this variable is true, Common Graphics excludes bits for the two X buttons that some mice have from the button-state argument that is passed to event-handling generic functions such as virtual-key-down, mouse-left-down, and cell-click. It also excludes these buttons from the values returned by the functions mouse-button-state, down-keys, and down-key-names.

The value of this variable is true initially, to provide backward compatibility to existing Common Graphics applications that do not expect these bits. If you would like to use X buttons in an application, then you can set this variable to nil.

information-icon

The value is a pre-defined icon to accompany an informational message to the user. Code that might run in CG/JS mode should instead call the information-icon function.

invert

key-names

The value of this constant is a list of all vk-[name] virtual key names in alphabetical order. These are pre-defined constants corresponding to usually non-typable keys on the keyboard. When a Lisp function calls for a virtual key argument, one of the pre-defined constants is suitable as an argument value. The word after the hyphen names the key.

left-mouse-button

The value of this constant is the value that corresponds to the left mouse button in a button-state argument.

light-blue

One of the predefined RGB colors, equivalent to (make-rgb :red 128 :green 128 :blue 255). See make-rgb.

light-cyan

One of the predefined RGB colors, equivalent to (make-rgb :red 128 :green 255 :blue 255). See make-rgb.

light-gray

light-gray-texture

Compatibility note

light-green

One of the predefined RGB colors, equivalent to (make-rgb :red 128 :green 255 :blue 128). See make-rgb.

light-magenta

One of the predefined RGB colors, equivalent to (make-rgb :red 255 :green 128 :blue 255). See make-rgb.

light-red

One of the predefined RGB colors, equivalent to (make-rgb :red 255 :green 128 :blue 128). See make-rgb.

light-yellow

One of the predefined RGB colors, equivalent to (make-rgb :red 255 :green 255 :blue 128). See make-rgb.

line-cursor

The cursor-handle for a mouse cursor in the shape of an I-beam. It could be used over text when clicking would place the text cursor there.

*loaded-but-uncreated-windows*

This variable is required to support importing of old-style (pre 5.0) .bil files into the IDE, but has no relevance to the current IDE system.

magenta

menu-separator

The value is a menu-item which when added to a pop-up or pull-down menu gives an unselectable dashed line.

meta-key

The value of this variable is an integer that will be passed as a bit flag component of the buttons argument to various event-handling generic functions such as mouse-left-down if the Command key of an Apple Mac was down when a keyboard or mouse event occurs.

middle-mouse-button

The value of this constant is the value that corresponds to the middle mouse button in a button-state argument.

*modal-dialogs-disable-owner*

If the value of this variable is true, then when a modal dialog is shown, its owner window (if any) and all of its descendent windows are disabled so that the user cannot interact with them until they exit the modal dialog. If nil, then other windows are not disabled, though the modal dialog will still stay in front of its owner window and its descendents.

Normally the value of this variable should be true, because a modal dialog is intended to block the user from other activity. On Windows the initial value is t.

*modal-dialogs-disable-owner-js*

This is used in CG/JS mode in the same way that *modal-dialogs-disable-owner* is used in Windows desktop mode. The initial value is t. You could set it to nil if graying out other windows while showing a modal dialog is slow in CG/JS mode, but that has not been seen to be a problem.

mouse-double-click

The value of this constant is the event number associated with the mouse-double-click event.

mouse-down

The value of this constant is the event number associated with the mouse-down event.

mouse-left-double-click

The value of this constant is the event number associated with the mouse-left-double-click event.

mouse-left-down

The value of this constant is the event number associated with the mouse-left-down event.

mouse-left-up

The value of this constant is the event number associated with the mouse-left-up event.

mouse-middle-double-click

The value of this constant is the event number associated with the mouse-middle-double-click event.

mouse-middle-down

The value of this constant is the event number associated with the mouse-middle-down event.

mouse-middle-up

The value of this constant is the event number associated with the mouse-middle-up event.

mouse-moved

The value of this constant is the event number associated with the mouse-moved event.

mouse-right-double-click

The value of this constant is the event number associated with the mouse-right-double-click event.

mouse-right-down

The value of this constant is the event number associated with the mouse-right-down event.

mouse-right-up

The value of this constant is the event number associated with the mouse-right-up event.

mouse-up

The value of this constant is the event number associated with the mouse-up event.

nc-mouse-double-click

The value of this constant is the event number associated with the mouse-double-click in the frame of a window event.

nc-mouse-down

The value of this constant is the event number associated with the mouse-down in the frame of a window event.

nc-mouse-left-double-click

The value of this constant is the event number associated with the mouse-left-double-click in the frame of a window event.

nc-mouse-left-down

The value of this constant is the event number associated with the mouse-left-down in the frame of a window event.

nc-mouse-left-up

The value of this constant is the event number associated with the mouse-left-up in the frame of a window event.

nc-mouse-middle-double-click

The value of this constant is the event number associated with the mouse-middle-double-click in the frame of a window event.

nc-mouse-middle-down

The value of this constant is the event number associated with the mouse-middle-down in the frame of a window event.

nc-mouse-middle-up

The value of this constant is the event number associated with the mouse-middle-up in the frame of a window event.

nc-mouse-moved

The value of this constant is the event number associated with the mouse-moved in the frame of a window event.

nc-mouse-right-double-click

The value of this constant is the event number associated with the mouse-right-double-click in the frame of a window event.

nc-mouse-right-down

The value of this constant is the event number associated with the mouse-right-down in the frame of a window event.

nc-mouse-right-up

The value of this constant is the event number associated with the mouse-right-up in the frame of a window event.

nc-mouse-up

The value of this constant is the event number associated with the mouse-up in the frame of a window event.

no-drop-cursor

The cursor-handle for a mouse cursor that looks like a circle with a slash through it. It could be used over an object during drag-and-drop to indicate that a drop is not allowed there.

*object-editor-command-buttons*

The value of this constant is the list of all choices for the command-buttons property of an object-editor dialog.

*ocx-classes-for-focus*

This is a tentative global variable for controlling which descendent window of an ocx-widget-window receives the keyboard focus when CG programmatically moves the keyboard focus to the control. We are not clear on the proper way to do this.

By default, when a CG application programmatically moves the keyboard focus to an ocx-widget-window, CG will find the bottom-most internal descendent window of the control and place the keyboard focus there. With the few OCX controls that we have tested so far, this appears to generally be the proper window to allow the user to do such things as scroll the widget with the keyboard without needing to first click the mouse on the widget.

This variable can contain a list of OCX class names that should override the general rule. The initial value of this variable contains one exception, which is the OCX class name "Internet Explorer_Server", becase we have found that this is the class of the internal descendent window of a WebBrowser control (used by the CG html-widget) to which we need to give the focus to allow the user to scroll with the keyboard without first clicking on the control.

If you know of similar exceptions for additional OCX controls that you define, then you could push the appropriate class name strings onto this global list.

*opaque-rubber-banding*

When t, the standard dragging operations like get-line and get-shape-box will use a newer and nicer drawing style than the traditional XORing that is used when this variable is nil, as it is initially.

The opaque style has no flashing like the old XOR style, and draws with the usual colors. It may be slower, though, and may not work at all with the "shape" functions depending on how the custom draw-fn and erase-fn that are passed to those functions are written.

This variable should not be set (with setq or setf) because it doesn't work in all cases and the functions that use it are sometimes called internally. Instead, it can be bound to t around calls to the dragging functions where it is found to work well.

The opaque style is generally always used in CG/JS mode because the XOR style is not implementable in JavaScript. One exception, though, is that if one of the "shape" functions is called with a draw-fn that always redraws everything, along with an erase-fn that does nothing, then the opaque style will probably not work (and will not be needed). For those cases, you can bind this variable to :never so that the opaque style is not used even in CG/JS mode (though that kind of custom draw-fn typically means that it's not really doing XORing).

paint

*parenthesis-match-pop-up-milliseconds*

This is number of milliseconds that a parenthesis-matching mark will appear on a lisp-edit-pane when *show-parenthesis-matches-as-pop-up-window* is true. The value should be a positive integer. The initial value is 2000, to show a mark for two seconds after the text cursor has moved to a different parenthesis or double-quote character.

In release 11.0, the initial value changed from 1000 to 2000 to give the user more time to spot the parenthesis match mark before it goes away.

*paste-with-undo-limit*

The value of this obscure variable could be adjusted to manage a trade-off with a Chromium quirk when pasting text. CG/JS uses the JavaScript function execCommand by default to paste a string into a text-edit-pane, because otherwise a programmatic paste will clear the undo/redo stack that's built into the underlying HTML TEXTAREA control. But if there are more than several newlines in the pasted string, that execCommand call takes a curiously long time in Chromium. It also takes somewhat longer when the whole text buffer is large. One thing that this affects is reindenting source code in the IDE's editor.

The value of this variable is an integer that controls the cutoff point in the number of newlinews in the pasted string and the size of the text control buffer, beyond which execCommand will not be used so that it doesn't make the paste slow. Making the value larger will retain the ability to undo in more cases, though larger pastes may take overly long. Making the value smaller will keep pasting fast in more cases, while allowing undo in fewer cases. Setting it to zero would never allow undo but never slow down pasting. The default value, which is an arbitrary integer derived by a heuristic, favors speed over enabling undo and redo.

po-and

A paint operation that "erases" color from the destination stream, except for the color in the new content being drawn. More precisely, each bit in the resulting color value of a pixel on the destination stream will be set to one if the corresponding bit was already one on the destination stream and is one in the new content being drawn. See paint-operation.

For example, if you set the foreground-color of a stream to be red and set its paint-operation to be po-and, and then you draw a line on the stream, then the colors that will be produced where the line is drawn will consist only of whatever redness was already there on the destination stream.

If the stream has a palette, then the bit-combining is done on palette indices rather than on true-color values. This tends to result in palette indices of unrelated colors that are not predictable from the colors being combined.

po-dst

Pixels to be painted on a device make a reference to three separate places: the destination, the source and a texture. These pixels are combined to create the actual pixel to be placed into the destination.

Such a combination is defined by a bitwise logical operation, called the paint operation. In Allegro CL, there are 256 possible paint operations that are given numbers from 0 to 255. There are eight possible minterms (of the three places): po-dst, po-ds~t, po-d~st, po-~dst, po-d~s~t, po-~ds~t, po-~d~st, and po-~d~s~t, where d is destination, s is source and t is texture (and ~ is the logical not operation). Each minterm may be present or absent from a paint operation.

A source pixel is copied to the corresponding destination pixel whenever the minterm representing the state of that pixel in the source, destination and texture pixmaps is present in the paint operation. (The minterm is "present" if its bit is on in the paint argument.) Thus there are 256 possible operations. Minterms are given the following weights (and to aid programming, named constants set to them):

po-dst 128
po-ds~t 64
po-d~st 32
po-~dst 8
po-d~s~t 16
po-~ds~t 4
po-~d~st 2
po-~d~s~t 1

po-ds~t

po-dst 128
po-ds~t 64
po-d~st 32
po-~dst 8
po-d~s~t 16
po-~ds~t 4
po-~d~st 2
po-~d~s~t 1

po-d~st

po-dst 128
po-ds~t 64
po-d~st 32
po-~dst 8
po-d~s~t 16
po-~ds~t 4
po-~d~st 2
po-~d~s~t 1

po-d~s~t

po-dst 128
po-ds~t 64
po-d~st 32
po-~dst 8
po-d~s~t 16
po-~ds~t 4
po-~d~st 2
po-~d~s~t 1

po-erase

A paint operation that "erases" the color that is being drawn. More precisely, each bit in the resulting color value of a pixel on the destination stream will be set to one if the corresponding bit was already one on the destination stream but zero in the new content being drawn. See paint-operation.

For example, if you set the foreground-color of a stream to be red and set its paint-operation to be po-erase, and then you draw a line on the stream, then the redness will be removed from whatever colors had appeared on the stream where the line was drawn.

po-fill

A paint operation that sets every bit in the pixel values of the destination stream to one. This will always draw in white unless the window has a palette with a different color at the highest position, and so this is not a particularly useful operation. See paint-operation.

po-invert

A paint operation that has the same effect as po-xor, though perhaps the arbitrary resulting colors may be different on some platforms. See paint-operation and po-xor.

po-paint

A paint operation that merges the colors of new content that is being drawn with the current colors of the destination stream's pixels. It does this by doing an inclusive or on the bits of the pixel values. See paint-operation.

po-replace

A paint operation that draws new content without being affected by what was drawn on the destination stream beforehand. In other words, each pixel value in the destination stream is simply replaced by the pixel value of the new content. This is the default paint-operation of any graphical-stream. See paint-operation.

po-xor

A paint operation that merges the colors of new content that is being drawn with the current colors of the destination stream's pixels. It does this by doing an exclusive or on the bits of the pixel values. See paint-operation.

An exclusive or is particularly useful for drawing something temporarily and then erasing it in such a way that the original drawing remains undisturbed. This can be done by simply drawing the temporary content twice using po-xor, where the second draw does the non-destructive erasing. The rubber-banding functions such as get-line and get-shape-box use po-xor internally to erase the rubber-banding line.

The color that results with exclusive or drawing is rather arbitrary, but that is the trade-off for non-destructive erasure.

po-~dst

po-dst 128
po-ds~t 64
po-d~st 32
po-~dst 8
po-d~s~t 16
po-~ds~t 4
po-~d~st 2
po-~d~s~t 1

po-~ds~t

po-dst 128
po-ds~t 64
po-d~st 32
po-~dst 8
po-d~s~t 16
po-~ds~t 4
po-~d~st 2
po-~d~s~t 1

po-~d~st

po-dst 128
po-ds~t 64
po-d~st 32
po-~dst 8
po-d~s~t 16
po-~ds~t 4
po-~d~st 2
po-~d~s~t 1

po-~d~s~t

po-dst 128
po-ds~t 64
po-d~st 32
po-~dst 8
po-d~s~t 16
po-~ds~t 4
po-~d~st 2
po-~d~s~t 1

*pop-up-message-max-height-factor*

The value of this variable is the fraction of the screen height to use as the maximum height for the pop-up-message-dialog text-box. Provided so that a message box with lots of text that might fill the screen will instead scroll in order to avoid filling the whole screen with a message box.

*pop-up-message-max-width-factor*

The value of this variable is the fraction of the screen width to use as the maximum width for the pop-up-message-dialog text-box. Provided so that a message box with lots of text that might fill the screen will instead scroll in order to avoid filling the whole screen with a message box.

question-icon

A pre-defined icon to accompany a question to the user. Code that might run in CG/JS mode should instead call the question-icon function.

red

right-mouse-button

The value of this constant is the value that corresponds to the right mouse button in a button-state argument.

second-x-button

The value of this constant is the value that corresponds to the second mouse X button in a button-state argument. X buttons are found on the side of some newer mice, where the rearmost button is the "second" one. See also *ignore-mouse-x-buttons*.

shift-key

*secure-mode*

The value of this global variable is true if the app was run in web browser mode with the --secure command line argument, which avoids using the general file selection dialog for security reasons.

*show-console-on-standalone-error*

This variable controls whether the console window is automatically shown when an error is signaled in a standalone Common Graphics application that was generated from a project in the IDE, and that error is not trapped by the application.

This variable applies only when :allow-runtime-debug was a member of the project's build-flags, since otherwise the console does not exist at all in the standalone application. The :allow-runtime-debug flag is typically set interactively by turning on the Enable Debugging of Runtime Errors check-box on the Build tab of the Project Manager dialog.

The default value of *show-console-on-standalone-error* is t because it may not be apparent that an error has occurred in a standalone application if the console window does not appear, and because the :allow-runtime-debug flag is typically used only while testing an application before final delivery, where debugging in the console window is appropriate.

There is a special case where it may be desirable to set or bind this variable to nil. If an application implements its own error-handling but also may want to defer to debugging in the console, then setting this variable to nil would avoid showing the console during the application's custom error handling. But the console would still be available (as long as the :allow-runtime-debug flag is used), and the application could show it explicitly if and when desired by calling show-console.

This variable could be set in the on-initialization function of a project, or in a top-level form in application code that would be evaluated at load time as the standalone application is built.

*show-parenthesis-matches-as-pop-up-window*

This global variable determines the technique that is used to draw a parenthesis-matching mark in a lisp-edit-pane. When nil, the mark is drawn directly on the lisp-edit-pane at the matching parenthesis. When true, a small pop-up window is placed over the matching parenthesis. The mark should look the same in either case, though when true the pop-up window will be hidden after *parenthesis-match-pop-up-milliseconds*.

This option could be enabled on any platform, though it is true initially only on the Mac OS X platform, due to not being able to draw directly on the window. If you prefer the marks to be visible only momentarily, then you may want to set the value of this variable to true on other platforms.

When using the pop-up window technique, the parenthesis-matching-style configuration option will have no effect, and the mark will always be drawn as if that option were :color-block.

CG/JS Note: This variable is not used in CG/JS mode. CG actually calls the function show-parenthesis-matches-as-pop-up-window to determine which style to use, and that function always returns true in CG/JS mode because only the pop-up-window style is possible.

*single-cg-event-handling-process*

On platforms where Allegro does not use native operating system threads (in which case *use-single-cg-event-handling-process* will be true), the value of this variable will be the single Common Graphics process in which all events are handled. On native thread platforms, the value will be nil.

Since most application code is initiated by events, this means that virtually all application code typically will run in this process on non-native thread platforms. The name of this process will be "CG Event Handler".

sizing-cursor

The cursor-handle for a mouse cursor that shows a crossed double-headed arrow. It could be used when clicking would initiate a drag-and-drop that allows dragging both vertically and horizontally.

sizing-north-south-cursor

The cursor-handle for a mouse cursor that shows a double-headed vertical arrow. It could be used where clicking would initiate a drag-and-drop that allows dragging vertically only.

sizing-northeast-cursor

The cursor-handle for a mouse cursor that is suitable for dragging the upper-right corner of a window or other object. Assign a cursor such as this to a window by calling (setf cursor).

sizing-northeast-southwest-cursor

The cursor-handle for a mouse cursor that shows a double-headed arrow running from 1:30 to 7:30 (to use a different analogy than the name).

sizing-northwest-cursor

A built-in mouse cursor handle that is suitable for dragging the upper-left corner of a window or other object. Assign a cursor such as this to a window by calling (setf cursor).

sizing-northwest-southeast-cursor

The cursor-handle for a mouse cursor that shows a double-headed arrow running from 10:30 to 4:30 (to use a different analogy than the name).

sizing-southeast-cursor

The cursor-handle for a mouse cursor that is suitable for dragging the lower-right corner of a window or other object. Assign a cursor such as this to a window by calling (setf cursor).

sizing-southwest-cursor

The cursor-handle for a mouse cursor that is suitable for dragging the lower-left corner of a window or other object. Assign a cursor such as this to a window by calling (setf cursor).

sizing-west-east-cursor

The cursor-handle for a mouse cursor that shows a double-headed horizontal arrow. It could be used wheren clicking initiate a drag-and-drop that allows dragging horizontally only.

*start-drag-slack*

The number of pixels that the mouse must be moved with the button held down in order to trigger a drag operation. See wait-for-drag, which can be used to determine whether the mouse has moved this amount while a button is down.

*status-bar-horizontal-margin*

This variable indicates the horizontal margin of the static-text component within the Lisp status-bar.

*status-bar-horizontal-margin*\

The number of blank pixels between the left and right ends of the text in a status-bar widget and the interior edge of its border.

*status-bar-number-of-lines*

This variable provides the value that is returned by the default status-bar-number-of-lines method. The method is called when creating status-bars without passing a specific number of lines as an argument to add-status-bar.

*status-bar-vertical-margin*

This variable indicates the vertical margin of the static-text component within the Lisp status-bar.

*suppressed-ocx-properties*

This is a tentative global variable, as we are not sure how to best deal with this problem in general. This functionality is likely to change in the future.

The value of this variable is an association list mapping particular OCX control class names to some of their properties that CG will hide, because allowing the user to change their values is not a good idea. The main effect is that these properties will not appear in the inspector in the IDE.

When a CG widget is defined for an OCX control by calling def-cg-ocx-control, CG generally defines all of the control's properties, because CG does not know which ones are not actually useful or that do nothing or that are not a good idea to modify. When defining your own OCX controls, you will need to discover this from the widget manufacturer's documentation and through experimentation.

If you would like to hide some of the properties of OCX controls that you define, then you could push them onto this alist. Below is the initial value. This list exists primarily because we now provide a standard html-widget in CG, which on Windows uses the WebBrowser OCX control, and it has several properties that we wanted to hide from the user.

(defparameter *suppressed-ocx-properties*
  
  ;; Hide certain properties with which users could easily
  ;; shoot themselves in the foot.
  '(
    ("WebBrowser"
     
     ;; These are the position and size of the control within its
     ;; site, but we make it always fill the site window in CG.
     "HWND" "Left" "Top" "Width" "Height")
    
    ("Monthview" "hWnd")
    ("DTPicker" "hWnd")))

*system*

This variable contains an object that stores various global values associated with a CG application. It is a suitable argument value for a few exported functions that access some of these global values. In particular, the expression

(configuration *system*)

returns the Common Graphics configuration object that stores various Common Graphics options. See cg-configuration and configuration.

The IDE has a similar object called *ide-system* for storing some of its global values.

*template-chars*

The value of this variable is an association list describing how various characters in a template-string are to be interpreted. Each entry in the list consists of:

(
    
 ;; A space character allows the user to type any graphical
 ;; character, and initially prints a space.
 (#\space graphic-char-p #\space)
 
 ;; A "c" allows any letter or numeral to be typed, while
 ;; an "a" allows only letters.
 (#\c alphanumericp #\space)
 (#\a alpha-char-p #\space)
 
 ;; A zero requires a numeral to be typed and also displays
 ;; a zero initially.
 (#\0 digit-char-p #\0)
 
 ;; A 9 allows only a numeral, even though it initially
 ;; displays a space (which makes it clear that nothing
 ;; has been entered there yet).
 (#\9 digit-char-p #\space)
 
 ;; These two both allow either a numeral or a space,
 ;; but differ in the initially-printed character.
 (#\8 digit-char-or-space-p #\0) 
 (#\7 digit-char-or-space-p #\space) 
 
 )

*text-wrapping-delimiters*

A list of the characters at which split-string-to-width will divide a string into multiple text lines by default when *wrap-text-in-cg* is true. The initial value is this:

*toolbar-button-spacing*

Determines the spacing used in toolbars. Controls spacing between two button groups. Its initial value is 6.

*toolbar-icon-height*

The height of toolbars that are created by add-toolbar when running in Windows desktop mode. The initial value is 22 on Windows. This variable could be modified at startup time to make all toolbars be a different height, though the function toolbar-icon-height should be called to return the height in any mode.

*toolbar-icon-height-js*

The height of toolbars that are created by add-toolbar when running in CG/JS mode. The initial value is 22. This variable could be modified at startup time to make all toolbars be a different height, though the function toolbar-icon-height should be called to return the height in any mode.

*toolbar-margin*

This variable and *toolbar-icon-height* control the height of new toolbars created by add-toolbar. The initial values (38 for the height and 2 for the margin) allow room for picture-buttons that have a height of 38 pixels (which holds an image with a height of 32 plus the standard 2-pixel-thick 3d border and 1-pixel-thick outer black border), with a margin of 2 pixels around the picture-buttons.

If you want to use the smaller size of icons that use an image that is 16 by 16 pixels, you could set *toolbar-icon-height* to 22 to leave room for the borders.

~dst

~ds~t

~d~st

~d~s~t

*use-alternate-websocket-nudge*

This one is too obscure to explain, but it may make some custom dragging loops smoother in CG/JS mode. The usual value is nil, but if you have implemented some sort of custom dragging loop that's not as smooth as you would like when running in CG/JS mode, then you could test binding this variable to true around that loop, and keep that change if it happens to make the dragging smoother. Calling idle-until-the-next-event inside the loop might also help in some loops when this variable is true. See also process-pending-events about possible hangs in dragging loops.

*use-single-cg-event-handling-process*

On platforms where each Allegro thread is a native operating system thread, the value of this variable will be nil. On non-native thread platforms it will be true.

The meaning of this is that on native thread platforms (currently Windows only), each lisp process has its own event queue in which it handles events on windows that were created in that process. On non-native thread platforms, there is only a single event queue for the single operating system thread, and so the events for all windows are handled in the same lisp process, which is the value of *single-cg-event-handling-process*.

This distinction will probably not affect most applications, but if it does then you may want to decide how to do certain things based on the value of this variable at run time.

WARNING: The event-handling process on a non-native threads platform must never call process-wait. See cg-process-wait.

*utilities-directory*

The initial value of this variable is nil, but if it is set to a pathname (or path namestring) then it will be returned by utilities-directory, overriding the usual path that it returns, which is either the user's home directory or a child directory of it.

When an application stores files in the utilities-directory, this can be used to establish a custom utilities directory.

This variable can be set by passing the --utilities-directory command-line argument.

vertical-arrow-cursor

The cursor-handle for a mouse cursor that shows a vertical arrow. In Windows desktop mode there is only a single arrowhead on the top, while in CG/JS mode both ends have an arrowhead.

virtual-key-down

The value of this constant is the event number corresponding to a virtual key being down.

virtual-key-up

The value of this constant is the event number corresponding to a virtual key being up.

vk-add

There are pre-defined constants corresponding to non-typable keys on the keyboard (see key-names). When a Lisp function calls for a virtual key argument, one of the pre-defined constants is suitable as an argument value. The word after the hyphen names the key, in this case the numeric keypad plus key.

vk-alt

On the Apple Mac, vk-meta is used for the Command/Apple key and vk-alt is used for the Option/Alt key.

vk-altgraf

This constant has been removed. The symbol naming it no longer exists. This constant was redundant with vk-alt, and its name was obscure. Any usage of vk-altgraf in Common Graphics applications should be changed to use vk-alt.

vk-applications

The applications key has a picture of a menu with an arrow mouse cursor on it (not all keyboards have it). It is typically just to the left of the right-hand control key. The default handler calls pop-up-shortcut-menu.

vk-backquote

vk-backslash

vk-backspace

vk-backtab

vk-cancel

There are pre-defined constants corresponding to usually non-typable keys on the keyboard (see key-names). When a Lisp function calls for a virtual key argument, one of the pre-defined constants is suitable as an argument value. The word after the hyphen names the key, although this is an anomalous case. In Windows, vk-cancel refers to the Pause/Break key when the control key is held down. As an anomolous case, when Pause/Break is pressed while either of the two control keys is held down, the key-code argument that is passed to generic functions such as virtual-key-down will be the value of vk-cancel instead of the value of vk-pause as it would be otherwise.

vk-capslock

vk-close-square-bracket

vk-comma

vk-control

vk-decimal

vk-delete

vk-divide

vk-down

vk-end

vk-enter

Some keyboards label two keys "Enter": one just above the right shift key on the main portion of the keyboard and one which is part of the numeric keyboard to the right. vk-enter refers to Enter key which is part of the numeric keyboard to the right. vk-return refers to the Enter (or Return) key just above the right shift key on the main portion of the keyboard.

vk-escape

vk-f1

vk-f10

vk-f11

vk-f12

vk-f13

vk-f14

vk-f15

vk-f16

vk-f2

vk-f3

vk-f4

vk-f5

vk-f6

vk-f7

vk-f8

vk-f9

vk-hash

This constant has been removed. The symbol naming it no longer exists. This constant was redundant with vk-quote (indicating the single-quote key), and its name was obscure. Any usage of vk-hash in Common Graphics applications should be changed to use vk-quote.

vk-home

vk-insert

vk-lbutton

vk-left

vk-left-alt

vk-left-control

vk-left-shift

vk-left-windows

vk-mbutton

vk-meta

On most platforms there is no "extra" shift key for this variable to represent, and its value is the same as vk-alt. On the Apple Mac, vk-meta is used for the Command/Apple key and vk-alt is used for the Option/Alt key.

vk-minus

vk-multiply

vk-numlock

vk-numpad0

vk-numpad1

There are pre-defined constants corresponding to non-typable keys on the keyboar (see key-names)d. When a Lisp function calls for a virtual key argument, one of the pre-defined constants is suitable as an argument value. The word after the hyphen names the key, in this case the numeric keypad one key.

vk-numpad2

vk-numpad3

vk-numpad4

vk-numpad5

vk-numpad6

vk-numpad7

vk-numpad8

vk-numpad9

vk-open-square-bracket

vk-pagedown

vk-pageup

vk-pause

vk-period

vk-plus

vk-printscrn

vk-quote

vk-rbutton

vk-return

On some keyboards, this key is labeled "Enter" rather than "Return". Such keyboards typically label two keys "Enter": one just above the right shift key on the main portion of the keyboard and one which is part of the numeric keyboard to the right. vk-return refers to the Enter (or Return) key just above the right shift key on the main portion of the keyboard. vk-enter refers to Enter key which is part of the numeric keyboard to the right.

vk-right

vk-right-alt

vk-right-control

vk-right-shift

vk-right-windows

vk-scrllock

vk-semicolon

vk-separator

vk-shift

vk-slash

vk-space

vk-subtract

vk-sysrq

vk-tab

vk-up

vk-xbutton1

vk-xbutton2

waiting-cursor

The cursor-handle for a mouse cursor that tells the user that the current action is still busy. The image is typically an hourglass.

warning-icon

A pre-defined icon to accompany a warning message to the user. Code that might run in CG/JS mode should instead call the warning-icon function.

white

white-texture

Compatibility note

*with-cursor*

When inside a (with-cursor ...) form, the variable *with-cursor* is bound to the mouse cursor that is currently being used globally (globally meaning used everywhere regardless of which window the mouse is over) within the with-cursor form. An application could check the value of this variable to see if the app is currently inside a with-cursor form at all (if the variable is true) and if so what mouse cursor is being used globally by with-cursor.

*wrap-text-in-cg*

When this variable is true, split-string-to-width will use *text-wrapping-delimiters* by default rather than only the space character as the characters at which it will split text into multiple lines. The initial value is nil.

Apps could bind or set this variable to true so that any calls to split-string-to-width will use that alternate behavior. The only place that CG internally calls split-string-to-width internally is in the undocumented nodes-and-links facility that Franz's Gruff graph database browser uses.