Allegro CL version 8.2
Minimally revised from 8.1.

Release Notes for Allegro CL 8.1

This document contains the following sections:

1.0 Introduction
2.0 Information on changes and new stuff since the 8.1 release
3.0 Fasl files are not-compatible between versions and operating systems
   3.1 All pre-8.1 Lisp compiled files must be recompiled (old fasl files will not load)
   3.2 Fasl files may be incompatible in different Lisps on same hardware
4.0 Release Notes for installation
5.0 Release notes for specific platforms
   5.1 OS patch needed for Solaris 2.8 on Sparcs
   5.2 HP Alpha running Tru64: default stack size should be increased
   5.3 Notes of increasing the default maximum stack size on HP-UX 11 machines
   5.4 Mac OS X notes
   5.5 AIX notes
   5.6 Heap start locations
6.0 Release Notes for the base Lisp
   6.1 New features in the base Lisp
      6.1.1 Features added to Allegro CL 8.0 after the initial release of Allegro CL 8.0
      6.1.2 New features in Allegro CL 8.1
   6.2 Non-backward-compatible changes in the base Lisp
   6.3 Other changes to and notes about the base Lisp
   6.4 Base Lisp platform-specific information
7.0 Release Notes for CLIM
8.0 Release Notes for Common Graphics and the IDE
   8.1 Significant changes in Common Graphics
   8.2 Non-backward-compatible changes in Common Graphics
   8.3 Other changes in Common Graphics
      8.3.1 Grid-widget-specific changes
   8.4 IDE release notes
      8.4.1 Opening projects from releases prior to 8.1
   8.5 Functionality to handle differences between Windows and GTK
   8.6 Release notes for the winapi module
9.0 Release notes for AllegroServe
10.0 Release notes for The Emacs/Lisp interface
11.0 Availability of CLX for Allegro CL
12.0 Release notes for Orblink
Appendix A. ANSI Conformance in Allegro CL

1.0 Introduction

This document is a copy of the version 8.1 release notes taken at a time prior to the release of version 8.2. Subsequent changes are not tracked. The actual current 8.1 release notes are available at This document is included in the 8.2 documentation to allow users who happen not to have access to the internet to see changes from 8.0 to 8.1 which may affect them but which are not otherwise discussed in the 8.2 documentation.

Many sections are divided into non-backward-compatible changes (that produce different behavior in release 8.1 compared to release 8.0) and changes unrelated to backward-compatibility. Note that a bug fix is not considered a backward-incompatible change even if it does result in changed behavior because the previous behavior was erroneous.

This document describes the changes, major and minor, from 8.0 to 8.1. Please look particularly at these sections:

If you notice changed or unexpected behavior with an operator, variable, class, or facility, search for its name in this document to see whether there is an entry concerning it.

2.0 Information on changes and new stuff since the 8.1 release

There are regular documentation updates. The updated documentation is available on our website (, where you will find links to the 8.1 documentation (and links to the documentation for earlier releases) and links that allow you to download the updated docs.

Other post-8.1 releases changes include the following:

3.0 Fasl files are not-compatible between versions and operating systems

3.1 All pre-8.1 Lisp compiled files must be recompiled (old fasl files will not load)

fasl files (compiled Lisp files) created by releases of Allegro CL prior to 8.1 will not load into Allegro CL 8.1. All such files must be recreated by compiling the associated Lisp source files. An error will be signaled if Lisp attempts to load an older, incompatible fasl file.

8.1.beta fasl file will load into 8.1 final. There is no need to recompile 8.1.beta compiled files.

3.2 Fasl files may be incompatible in different Lisps on same hardware

Fasl files created on Windows x86 cannot be loaded into Linux or FreeBSD x86 Lisps

The Windows and UNIX operating systems are too different. However, FASL files (for the same Lisp version) can generally be shared between different UNIX operating systems on the same hardware. The general principles are as follows. Note that incompatibility may creep in for reasons outside our control. If fasl files are incompatible, recompile on the target machine.

Fasl files will usually be compatible between platforms when:

It is up to the user to ensure that there are no os-specific dependencies, or that features (i.e. #+/#- ) did not cause essential code to be excluded or extraneous code introduced that would cause a problem on the crossed architecture.

4.0 Release Notes for installation

  1. Except for Mac OS X, version 8.1 uses the 8.0 installation procedure: installation is described in installation.htm. Mac OS X installation is described in the section Installation on Mac OS X in installation.htm.
  2. The distribution includes 8 bit and 16 bit character images (this information is repeated from earlier Release Notes). Allegro CL has images that support 8 bit characters only, or 16 bit characters only. It is our expectation that most users will use the 16 bit images. Executables supplied with the distribution either have or do not have `8' in the name. Those with 8 in the name (mlisp8 and alisp8, e.g.) support 8 bit characters. Those without a number in the name support 16 bit characters. Image (dxl) files also come in 8 and 16 varieties. Again, 8 in the name means 8 bit character support. Character support for images and executables must match. Trying to start an executable with the wrong type of image fails.
  3. No prebuilt Allegro Composer images in the distribution (this information is repeated from earlier Release Notes). To create an Allegro Composer image, start Allegro CL and load That will produce composer and composer.dxl, or composer8 and composer8.dxl. Allegro Composer is available on Unix only.
  4. No prebuilt Allegro CLIM images in the distribution (this information is repeated from earlier Release Notes). To create a CLIM image, start Allegro CL and load That will produce clim and clim.dxl, or clim8 and clim8.dxl.

5.0 Release notes for specific platforms

Allegro CL 8.1 is known to work with the following minimal operating system versions. Allegro CL 8.1 runs on all operating system versions released (not in beta or pre-release form) April 1, 2007. See below for places to obtain information on operating systems released after that date.

Note that Allegro CL 8.1 does not run on Windows 98/Me or on Mac OS X 10.3.

32-bit platforms

64-bit platforms

Franz Inc. cannot maintain the same release schedule as the many operating system providers on the many platforms we support. Usually Allegro Common Lisp and all of its component parts will work on new Operating System versions that become available after release. But sometimes Allegro CL patches or operating-system patches, or installation tweaks, will be required before Lisp will run on an updated system.

Franz Inc. usually finds out about any such issues soon after new operating system releases appear and devises any necessary patches or compatibility procedures. We maintain current information about operating system versions on this web page: We strongly advise you to check that page before updating your operating system. If we know that the new operating system is compatible, or is compatible with certain patches, you will find the information there. Similarly if it is known to be incompatible. If the new operating system is not yet listed it may be that it has not yet been tested.

5.1 OS patch needed for Solaris 2.8 on Sparcs

A problem with Solaris 2.8 where calls to run-shell-command can cause Lisp to hang is fixed by operating system patch 108993-18 (which supersedes the earlier patch 108827-36 for this problem). On Solaris 8, it can also be fixed by adding /usr/lib/lwp to the front of your LD_LIBRARY_PATH environment variable. No fix is necessary for Solaris 2.9.

The patch can be obtained from this Sun website:

5.2 HP Alpha running Tru64: default stack size should be increased

The default stack size limit on an Alpha is 2 Megabytes, which is too low for normal stack overflow handling. Doing

 limit stacksize unlimited

in a csh shell seems to allow up to 16 or 32 Mb, and users can run that command before running Allegro CL. (That command could be put into a .cshrc file.)

However, that only solves the problem for Allegro CL processes that are started from within that shell. You can also change the default for the machine as a whole by doing something like the following. (This procedure is provided as an example of what might work. Please check your Tru64 system documentation or contact your HP service representative for the precise instructions.)

The procedure described here is best performed by a system administrator or similarly trained person. The vmunix file created and copied at the end is the UNIX kernel. Modifying it incorrectly or corrupting it can have serious consequences.

1. Log in as root. You must be root (or have superuser privileges) to perform most of the following operations.

2. Change into the /sys/conf/ directory.

  prompt# cd /sys/conf

3. Edit the file whose name is the machine name, which we will call MACHINE_NAME, as follows. (Such a file typically exists after normal Tru64 Unix install. If the file does not exist, the System Administrator will have to create one.

Change the line 

           dfssiz         2097152
           dflssiz         8388608
           dflssiz         16777216

The value of dflssiz may already be different than 2097152, which is 2 megabytes -- (* 2 (expt 2 20)). The new suggested values are 8388608, which is 8 megabytes and a good value for 32-bit Lisps, or 16777216, 16 megabytes and a good value for 64-bit Lisps.

4. Run /usr/sbin/doconfig as follows (recall that MACHINE_NAME is the file in /sys/conf whose name is the machine name):

 prompt# /usr/sbin/doconfig -c MACHINE_NAME

You should see output similar to:


Saving /sys/conf/MACHINE_NAME as /sys/conf/MACHINE_NAME.bck

Do you want to edit the configuration file? (y/n) [n]: n

	Working....Thu Oct  4 09:58:16 PDT 2001

The new kernel is /sys/MACHINE_NAME/vmunix

5. Copy the new kernel to / with a command like the following

prompt# mv /sys/MACHINE_NAME/vmunix /

6. Reboot the system.

5.3 Notes of increasing the default maximum stack size on HP-UX 11 machines

Increasing the default maximum stack size on HPUX 11 requires modifying kernel configuration parameters, then rebuilding the kernel. This process should be done by the systems administrator.

The file /stand/system is the kernel configuration file. The maxssiz and maxssiz_64bit tunable parameters need to be increased to at least 32MB each. If you don't have any references to maxssiz or maxssiz_64bit in your /stand/system file, then you can simply add these lines to the bottom of the file:

maxssiz         (32*1024*1024)
maxssiz_64bit   (32*1024*1024)

Otherwise, you'll need to modify the existing parameters so that they express a value >= 32MB.

After modifying /stand/system, the kernel needs to be rebuilt using the following command:

/usr/sbin/config -u /stand/system

The system will have to be rebooted for the changes to take effect.

5.4 Mac OS X notes

Allegro CL 8.1 is only supported on Mac OS X version 10.4 or later. It is not supported on versions 10.3 or earlier.

The Runtime Analyzer (see runtime-analyzer.htm) does not work properly on the 64-bit Mac OS X port (there is no problem on the 32-bit port).

Building shared libraries on Mac OS X

Building shared libraries on Mac OS X in foreign-functions.htm describes how to create a shared library suitable for loading into Allegro CL. We have determined that the -flat_namespace to the ld used to create the shared library is necessary, as shown in the linked section.

5.5 AIX notes

In order for Allegro CL 8.1 to run on AIX the following filesets must be installed:

These filesets should be available on the AIX installation media.

Without these filesets, Lisp will likely fail on startup. The exact nature of the failure depends of the specific dlopen() implementation. A typical failure message looks like:

dlopen(/usr/local/allegro/acl81/, mode) error: Bad address

5.6 Heap start locations

When building large new images, it is often useful to specify Lisp Heap and C-heap start locations. See the discussion of the lisp-heap-start and c-heap-start keyword arguments in Arguments to build-lisp-image 2: defaults not inherited from the running image in building-images.htm. Here are the initial locations (called `bases') in Allegro CL 8.1 as delivered. Values are Hexadecimal integers.

Operating System Lisp base C base
Tru64 32-bit 0x30000000 0x54000000
Tru64 64-bit 0x1000000000 0x2000000000
FreeBSD 0x40000000 0xa0000000
HP-UX 32-bit 0x10000000 0x64000000
HP-UX 64-bit 0x8000001000000000 0x8000002000000000
Linux (x86) 0x71000000 0xa0000000
Linux (AMD64) 64-bit 0x1000000000 0x2000000000
Mac OS X 32-bit 0x10000000 0x64000000
Mac OS X 64-bit 0x1000000000 0x2000000000
Windows 0x20000000 0x54000000
AIX 32-bit 0x30000000 0x64000000
AIX 64-bit 0x700001000000000 0x700002000000000
Solaris 32-bit 0x4000000 0x54000000
Solaris 64-bit 0x1000000000 0x10000000000
Solaris (AMD64) 64-bit 0x1000000000 0x10000000000

6.0 Release Notes for the base Lisp

This main section contains three subsections (which have additional subsections): one on new features (Section 6.1 New features in the base Lisp), one on changes which are not backwards compatible and so may require code changes, (Section 6.2 Non-backward-compatible changes in the base Lisp), and one on miscellaneous changes (Section 6.3 Other changes to and notes about the base Lisp).

6.1 New features in the base Lisp

We have added a number of new capabilities to Allegro CL. Here we give links to the documentation of the new features.

The features described in Section 6.1.1 Features added to Allegro CL 8.0 after the initial release of Allegro CL 8.0 were released originally as patches to Allegro CL 8.0, but after the initial release of Allegro CL 8.0. The features described in Section 6.1.2 New features in Allegro CL 8.1 are new in the Allegro CL 8.1 release.

6.1.1 Features added to Allegro CL 8.0 after the initial release of Allegro CL 8.0

Various additions to Allegro CL 8.0 were added after the original release of Allegro CL 8.0. We list them here. All are part of release 8.1.

  1. New features in SSL socket support. Allegro CL has for some time supported SSL (Secure Socket Layer) sockets. See the section Secure Socket Layer (SSL) in socket.htm. This facility is enhanced to support processing of certificates. The argument lists to make-ssl-client-stream and make-ssl-server-stream have been augmented to support the new feature. New methods, get-ssl-peer-certificate, get-ssl-verify-result, and ssl-do-handshake have been added. get-ssl-peer-certificate allows accessing and working with X.509 certificates. A new x509-certificate class defines objects corresponding to X.509 certificates.
  2. TCP MD5 Signature Option support (Linux platforms only). The new function set-tcp-md5-sig provides an interface to the TCP_MD5SIG (RFC2385) socket option. It sets the key to be used for TCP connections from an address. make-socket has been modified to accept new keyword arguments tcp-md5-sig-key and tcp-md5-sig-key-ef.
  3. Daylight saving time changes. Allegro CL finds out whether daylight ssaving time is or is not in effect by asking the operating system. The variable *daylight-saving-time-observed* is now ignored. (However, some operating systems have not been updated to reflect the new United States DST schedules which go into effect in 2007 (with DST starting on March 11, 2007). Allegro CL schedules have been updated. You can use the old system with the updated schedules if you set the unexported variable excl::*use-us-daylight-saving-time* to true. Then the variable *daylight-saving-time-observed* will have effect. But when your OS is updated to have correct DST information, you should use that.)
  4. New rpc update. The changes included adding a kill argument to client-exit, modifying client-exit to kill a process on a remote host, and revising symbol handling in remote references. The documentation was also updated, with significant changes particularly to the description of run-other-client. See rpc.htm for information on RPC in Allegro CL.
  5. New :anynl value for eol-convention for input-streams. The function eol-convention returns and (with setf) allows setting the End of Line convention used by a stream. You may now set the value to :anynl, which will result in any standard end of line convention being read correctly on input (the UNIX convention of a linefeed, the DOS convention of a carriage-return linefeed, or the Mac convention of a carriage-return). See the description of eol-convention for details and a discussion of what is done for output files.
  6. Variable net.uri:*strict-parse* allows parsing of some URIs that are non-compliant. RFC2396 specifies the format for URIs but many websites do not strictly follow its rules. The variable *strict-parse* controls how strictly the parser observes syntax rules and, when nil, allows parsing of many URIs which are actually non-compliant. See uri.htm for details of URI support.
  7. New net.mail package and interface for parsing and validating email addresses. The module now provides two functions in the new net.mail package: parse-email-address and valid-email-domain-p. The first (broadly following RFC2822) extracts the username and domain name from an email address while the second tries to validate domain names (because many things can go wrong with email, valid-email-domain-p is most useful when it says a domain is invalid). See The net.mail interface for parsing and validating email addresses in imap.htm for details.
  8. excl:with-underlying-simple-vector exported: the macro excl:with-underlying-simple-vector, which allows access to the underlying data vector associated with an array, is now exported and documented. (It has existed as an internal operator for a long time in Allegro CL.)
  9. New ISO 8601 date/time module: support for ISO 8601 specifications of dates and times has been added to Allegro CL. See date-time.htm for details. The functions locale-format-time and locale-print-time have also been modified to accept date-time objects as well as universal times as arguments. (The description of locale-print-time has been updated to reflect that change and also to revise the field descriptor definitions (%F, %G, %g, and %P added, %U, %W removed) and the Modified Conversion Specifications (%OU and %OW removed), the removed definitions/specs were never in fact supported.)
  10. New module provides PAM support on some platforms. The pam module provides a Lisp wrapper around the PAM API on Linux, Solaris, and some other unixlike operating systems. PAM (Pluggable Authentication Modules) is described in See PAM support in Allegro Common Lisp in miscellaneous.htm for details. PAM is not supported on Windows and some UNIX platforms. The PAM documentation lists the platforms where PAM is not supported.
  11. New FAQ replaces old FAQ. We have a new FAQ (Frequently Asked Questions) document. It is only available online (so you will always see the latest version). It is located at The version of our FAQ previously included with the documentation in the doc/faq/ directory has been discontinued and removed (all files now simply contain a link to the new FAQ).
  12. New Emacs-Lisp-Interface command fi:insert-arglist (C-c i): the fi:insert-arglist command, when invoked after typing '(<fun> ', inserts the argument list template into the code being typed. See Argument lists in eli.htm for details.

    Also, a problem with using Gnu Emacs on Windows compiled with Cygwin has been fixed.

  13. New optimized variants of read-line. Two new functions, simple-stream-read-line and read-line-into were added to provide optimized variants of read-line, with little or no consing and less copying of characters (because the target strings are provided in the function call). simple-stream-read-line allows (optionally) specifying a target string but will create a new string if necessary. read-line-into always requires a target string and will use it regardless. It is therefore always more efficient but it does require correct bookkeeeping to be used correctly. Both are documented on their own pages. The read-line-into page has numerous examples.
  14. double-sided option for pop-up-printer-job-dialog. A new option, double-sided, has been added for printer support. See pop-up-printer-job-dialog.
  15. Minor IP address handling upgrade. The function dotted-address-p returns true if its argument is a string in dotted IP address form. See Host naming in socket.htm where the dotted form is described with examples.
  16. sys:update-allegro now allows specifying proxy username and password. There has long been a proxy keyword argument to sys:update-allegro, the function that downloads updates and patches for Allegro CL. This argument allows downloading when using a proxy. However, sometimes the proxy also needs a username and password. A new keyword argument, proxy-basic-authorization, allows these to be specified as well. See sys:update-allegro.
  17. ntservice facility provided: you can make your application a service on Windows. See Turning your application into a Windows Service in delivery.htm. There is an example (after the update is complete) in examples/ntservice/.
  18. jLinker revisions. There are changes in jlinker-listen (new :abort value for the stop argument); jlinker-init (new report keyword argument); def-java-class (new possible value for the name); def-java-constructor (documentation clarification); jlinker-slot (new value for the key argument); and a new variable *jlinker-deprecated-warnings*. (Also minor changes in jarray-set, jdo-call, jmake-new, jcons, jmeth, jget-cons, jget-meth, and jarray-set.)

    Additionally, jlinker-init now has an end-function keyword argument which, if supplied, should name a function that will be called when jLinker stops. jlinker-listen now behaves differently when jlinker-init fails: before jlinker-listen would exit when jlinker-init failed. Now, the function specified as the value of the process-function is called and it is its responsibility to decide whether to stop or continue when jlinker-init returns a failure message.

  19. RPC changes. There are some some modifications to the rpc module (see rpc.htm for a description of the module). The affected operators were client-end-all (new optional arguments) and run-other-client (new line-limit keyword argument). Also, there were significant documentation changes to run-other-lisp and rpc-close.
  20. New command-line argument +P. If +p (lowercase p) appears on the command line, +P (uppercase P) undoes its effect. (+p may be present in the command-line resource for the executable. +P allows cancelling the +p in such a case.) See Command line arguments in startup.htm for a list of command-line arguments accepted by Allegro CL.
  21. New support for constructing MIME messages. See MIME support in imap.htm for more information. See particularly the new function make-mime-part. send-letter, send-smtp, and send-smtp-auth have been enhanced to allow files or streams (as well as a string) as the value of the message argument. send-letter also now accepts an attachments keyword argument.
  22. Changes to mail functions allows specifying the mail server port number. Changes to the handling of the mail-server argument to send-smtp, send-smtp-auth, and send-letter allows you to specify the mail server port number. Prior to this change, port 25 was always used. See the function descriptions for details.
  23. New support for pipe streams: See make-pipe-stream, make-function-input-stream, and with-function-input-stream. (The new pipe streams are somewhat more flexible than the one provided by pipe.)
  24. New function base64-encode-stream. See the description of base64-encode-stream and see Base64 Support in miscellaneous.htm for information on Base64 and Base64 support in Allegro CL. Also, base64-decode-stream now accepts keyword arguments which can control the error behavior and the number of bytes read.
  25. New ability to invoke Lisp within a bat file on Windows. You can now execute Lisp programs contained within a bat file on Windows so the bat file will invoke Lisp, run specified forms, and then exit (optionally pausing before exiting). The function lisp-to-bat-file supports this new facility. It writes an appropriate bat file when given a Lisp file of forms to execute and provided some additonal information (such as what image file to use). Also added are two new command-line arguments --bat and --bat-pause. (See Command line arguments in startup.htm for a list of command-line arguments accepted by Allegro CL.) This Tech Corner entry talks about the bat file feature and gives an example.
  26. New Oracle-direct interface function cancel-cursor. The function cancel-cursor allows you to cancel retreiving values via a cursor before you're read all the values.
  27. update.exe replaces update.bat for updating images on Windows. This was done in a 8.0 patch but not previously documented. You run update.exe (rather than update.bat) to create new images with patches included after downloading patches with sys:update-allegro or with the Download Patches dialog.

6.1.2 New features in Allegro CL 8.1

  1. Support for gdb/dbx/windbg debuggers. Support for using these debuggers (on appropriate platforms) has been added on some platforms. See gdb (or dbx or windbg) interface in debugging.htm for details. That section has a list of supported platforms.
  2. New Iref8 compiler explanation: provides an explanation that an argument to svref or ssvref is apparently of the wrong type. A compiler warning is also issued, but this explanation during compilation may be helpful. Compiler explanations are described in compiler-explanations.htm. Iref explanations are described in the section ;Iref labels in that document.
  3. concatenate-system now returns a list of filenames. The function concatenate-system, part of the defsystem utility (see defsystem.htm) previously returned t. It now returns a list of namestrings of the files concatenated, in the order in which they appear in the concatenated fasl file.
  4. make-foreign-pointer has new aligned keyword argument. If the aligned keyword argument to make-foreign-pointer is specified true, then the address is interpreted as an aligned address and is shifted to become a machine integer before storing. (Aligned pointers are described in Aligned Pointers in ftype.htm.)
  5. Apparent misspelling in declarations now cause warnings. Consider this code:
    (defun foo (x1 y1) (declare (fixnum x2 y1)) (+ x1 y1))

    The variable x2 is declared to be a fixnum, but is not actually lexically visible. Presumably the author meant to declare x1 to be a fixnum and just mistyped. This error will make no difference to the code execution, though it might make a difference to how the code is compiled. Allegro CL will now warn about the unknown variable in the declaration. Note that this code will (likely) cause two warnings

    (defun bar () (declare (fixnum y1)) (+ 1 y1))

    Here y1 will be assumed to be special and (if y1 is otherwise not known about) a warning saying that y1 is assumed special will be signaled as will the warning that a declaration refers to an unknown variable.

    See Warnings are signaled for misspelling in type declarations in compiling.htm.

  6. Semaphores implemented for gates. The functions get-semaphore and put-semaphore can be applied to gates to control when a gate is opened or closed and by which process. Gates are described in Gates in multiprocessing.htm.
  7. Registered addresses of Lisp functions (for foreign callbacks) now never move. When you want a Lisp function called from a foreign function, you have to register it with register-foreign-callable (and define it with defun-foreign-callable). register-foreign-callable returns the address of the Lisp wrapper function which is what is actually called from the foreign code. In earlier releases, this address was valid after a gc but was not valid after a dumplisp. Starting in release 8.1, it is always valid. register-foreign-callable also returns an index into a table that can be used to find the address. In earlier releases, we instructed users to use the index to avoid having an invalid address after a dumplisp. That is no longer necessary but using an index does have the advantage that it is always a fixnum while the address may be a bignum.
  8. with-auto-zoom-and-exit and zoom function now defined in Lisp. There is a new top-level.debug package and autozoom module with two operators: the macro with-auto-zoom-and-exit and the function zoom. In earlier releases, with-auto-zoom-and-exit was defined in a source file but was not part of Lisp as delivered. These functions allow you to get debugging information programmatically. See Getting a backtrace programmatically in debugging.htm.
  9. New foreign-functions macros with-static-fobject and with-static-fobjects. with-static-fobject and with-static-fobjects, like the existing with-stack-fobject and with-stack-fobjects, allocate foreign type objects during the evaluation of a body of code. The existing macros had the problem that when run interpreted, the objects might be moved by the garbage collector. The new macros can guarantee that will not happen. See also the note about changes to with-stack-fobject and with-stack-fobjects in Section 6.2 Non-backward-compatible changes in the base Lisp below.

6.2 Non-backward-compatible changes in the base Lisp

  1. Errors are signaled more often for floating-point underflows and overflows. Code which used to simply return 0.0 (in an underflow situation) or excl::*infinity-single*) in an overflow now may error, signaling a floating-point-underflow or floating-point-overflow error as appropriate. This change (which is compliant with ANSI) allows users to control more precisely what they want in these cases: 0.0, least-positive[something]-float, to switch from singles to doubles, or whatever. But code which depended on the older more tolerant behavior will now break. (for example, (read-from-string "4.9e-324") signals an error rather than rturning 0.0 and (expt most-positive-single-float 2) signals an error rather than returning excl::*infinity-single*.) See Floating-point infinities and NaNs, and floating-point underflow and overflow in implementation.htm for more information and sample handler code to cath the errors. See also read-tiny-float which can be used to read small floats safely. As mentioned in Section 6.3 Other changes to and notes about the base Lisp, the infinity and NaN constants are now exported.
  2. sys:*current-thread* is now a symbol-macro. Any reference to sys:*current-thread* (except by symbol name) is automatically transformed into a call to functionality which accesses and returns the current thread object. This implementation is much more efficient. User code should not have to be changed except for references to the symbol name where the value is in some fashion used (so applying boundp to 'sys:*current-thread* returns nil and applying symbol-value to it results in an error.
  3. lisp_init() arguments changed. The quiet argument has been replaced by the tls_slot_index. See main.htm for a list of arguments and a discussion of this change. (quiet was in fact unused. The discussion is about the new argument.)
  4. Foreign-functions macros with-static-fobject and with-static-fobjects have changed argument lists. The old argument list was ((var type &etc) &rest body). The new one is ((var type &key allocation size) &rest body). The etc argument was never documented and it is unlikely that user code will be affected, but this is a non-upward-compatible change. The new keyword arguments allow you to say where the objects should be allocated and how big they should be (though specifying size means the objects will not be stack allocated). See also the entry on the new related macros with-static-fobject and with-static-fobjects in Section 6.1.2 New features in Allegro CL 8.1 above.

6.3 Other changes to and notes about the base Lisp

  1. Changes to the base64 conversion functions. usb8-array-to-base64-string, string-to-base64-string, base64-string-to-usb8-array, and base64-string-to-string all have new start and end keyword arguments that allow specification of only a portion of the input for conversion. string-to-base64-string and usb8-array-to-base64-string formerly accepted an optional wrap-at-column argument. Now it is a keyword argument. The old style is still accepted for compatibility (but is strongly discouraged; other keyword arguments cannot be specified if the optional argument calling style is used). string-to-base64-string and base64-string-to-string now accept an external-format keyword argument. For compatibility, the default external format used is (crlf-base-ef :latin1). base64-string-to-usb8-array accepts a new keyword argument output which specifies the buffer to use for the result. If output is nil, or if it is not large enough to hold the result, a new usb8 array will be allocated and returned. base64-string-to-usb8-array returns a second value: the number of bytes added to the result usb8 array.
  2. New keyword arguments to to excl.osi:with-open-temp-file. with-open-temp-file has new filename and delete leyword arguments. filename, if specified, must be a symbol, which will be bound to the actualy filename used for the temp file during the executaion of the body. delete, if specified true, causes the temp file to be deleted when the body completes.
  3. SOAP changes: there are some relatively minor change to SOAP (which is described in soap.htm). These changes are also backported to Allegro CL 8.0 and 7.0.
  4. SOAP addition: new method wsdl-add-form. wsdl-add-form allows application code to add to the generated code.
  5. Infinity and Nan constants are now exported. See Floating-point infinities and NaNs, and floating-point underflow and overflow in implementation.htm. Also see *negative-infinity-single*, *infinity-double*, *infinity-single*, *negative-infinity-double*, *nan-double*, and *nan-single*. Floating-point overflows and underflows now error more often (see Section 6.2 Non-backward-compatible changes in the base Lisp), so code like (expt most-positive-single-float 2) designed to return infinity will now error. Now *infinity-single* can be referenced directly.
  6. open runs significantly faster. Opening files with open is about twice as fast in 8.1 as it was in 8.0. You can verify this by running the following function in both versions:
    (compile (defun test ()
       (dotimes (n 50000)
         (with-open-file (f "/etc/passwd"))))))
  7. Warning is signaled for unused flet functions. Allegro CL has issued warnings for unused labels functions for some time. It now also issues them for unused flet functions. The function can be declared ignore or ignorable using the #' notation -- i.e. (declare (ignore #'my-flet-function) -- in either labels or flet.
  8. sequence argument to read-vector and write-vector can now be an aligned pointer. The sequence (the required) argument to read-vector and write-vector can now also be an aligned-pointer, or a foreign-pointer with an address component that is word-aligned. If it is a pointer, the end keyword argument must also be specified (so the function can know how long the vector is).
  9. lisp-implementation-version now returns two values, the second identifying the shared library build number. That detail may be useful in assisting Franz in debugging a problem. See cl:lisp-implementation-version in implementation.htm. The first return value of cl:lisp-implementation-version is a string identifying the version number, the platform, and the date the product was created.
  10. Condition file-incompatible-fasl-error exported and documented. This is the condition signaled when you try to load certain inappropriate fasl files into a Lisp image (such as fasl files compiled in previous versions). The associated error has always been signaled, but the condition, file-incompatible-fasl-error was not previously exported (from the excl package).
  11. New feature :verify-stack and new compiler switch verify-stack-switch. On platforms with :verify-stack on the *features* list, checking whether the stack pointer has gone beyond the stack cushion is expensive. (A stack cushion is an artifical stack limit. If Lisp can detect when this limit is reached, it can warn that the stack is about to be exhausted -- if the stack truly runs out, Lisp will fail.) On such platforms, the verify-stack-switch controls whether stack cushion checking is or is not done in compiled code.
  12. console-control now has a title keyword argument. With it, console-control (a function only available on Windows) can set the title of the Allegro CL console window.
  13. fasl file headers have more (readable) information. See Fasl files in compiling.htm. There are 10 readable lines at the top of a fasl file. The UNIX head() command will print the readable head of a fasl file.
  14. The address adjustment phase of a garbage collection has been sped up. The user-visible effect is in faster performance, but the improvement is noticeable in images with a lot of data (test case showed a 10x speed up, from several seconds to less than 0.3 seconds).
  15. sys:update-allegro will tell you if there is a newer version of AllegroCache or AllegroGraph available. sys:update-allegro does not itself download the newer version, but it does tell you how you can get it.
  16. Length and offset can be specified for mapped files. Mapped files are of stream class mapped-file-simple-stream. They are created by specifying :mapped t to open. open with :mapped t now accepts offset and length keyword arguments. The offset is the number of bytes beyond the start of the file where the mapping begins, and the length is the length of the mapping. (The mapped keyword argument is an Allegro CL extension to open and is described on the mapped-file-simple-stream page.)
  17. run-shell-command has a new keyword argument :share-open-files. This new argument to run-shell-command, for Windows only, allows you to ensure that files opened by a call to run-shell-command are not shared.
  18. match-re now opencodes even when :regexp2 has not been required. match-re has a compiler-macro, but prior to 8.1, it wasn't used unless the :regexp2 was required before the compilation. Now, such compilation of match-re causes the proper expansion to inline code.
  19. The documentation file glossary.htm removed. This file contained several definitions of terms used in the documentation but on balanace was not useful.

6.4 Base Lisp platform-specific information

There are no entries at this time. Information may be placed here in documentation updates after the initial Allegro CL 8.1 release.

7.0 Release Notes for CLIM

The CLIM manual has not been updated (other than minor corrections) for the 8.1 release. There have been no significant changes to CLIM functionality compared to 8.0, though there have been bug fixes and performance enhancements.

(Repeated mostly from 8.0 Release Notes.) The documentation for CLIM is in an online PDF file, clim-ug.pdf.

On Linux and FreeBSD, Allegro CLIM works with Open Motif 2.1 and 2.2 (2.2 was released in early 2002). Open Motif 2.2 is available at no charge from Allegro CL 8.1/Allegro CLIM will work with either version. Redhat Linux 7.2 is supplied with Lesstif, a version of Motif that does not work with CLIM. See the Linux architecture specific information in the Allegro CL FAQ for information on how to install Redhat Linux 7.2 without lesstif and how to uninstall lesstif if already present. On all other Unix platforms, CLIM uses the platform-supplied Motif.

Certain CLIM demos on Solaris 64 bit give segv or otherwise fail when displaying over the network, language environment must be set to C. This is a problem when running any Sun GUI (such as the CDE environment or the Gnome 2.0 interface) on a Solaris64 machine. When bringing up the environment, set the language/locale to "C". (On the login screen, there's an "Options" button, which displays a menu that has a "Languages" submenu. Choose "C". Note: the default value is typically "en_US".) The "C" setting can process all of the 64-bit font sets. However, difficulties arise when displaying over the network. If you are displaying on the monitor of the machine running Allegro CL (and CLIM), the demos work as long as the language/locale is "C". They typically do not work when displaying on a monitor over the network. As of this writing, there is no fix for the problem.

8.0 Release Notes for Common Graphics and the IDE

The first subsection describes changes to Common Graphics and the IDE that are non backward-compatible. Please review this section and make whatever necessary changes to your code to obtain the desired behavior in release 8.1.

The second subsection describes other changes to Common Graphics and the IDE. These should not require code changes (please tell us if any do, because that may indicate a bug), but note that certain function and argument names have been deprecated in favor of new names, and that new code should reflect these changes, and old code should be revised at some point.

The section Section 8.4 IDE release notes and its subsections provide information about the IDE.

8.1 Significant changes in Common Graphics

New chart drawing utility

A new widget allows drawing bar charts or equivalent line charts. See cg-chart-widget.htm.

New object-editor and class-grid widgets

These allow you to edit classes and instances. See class-grid and object-editor and also cg-object-editor-and-class-grid.htm. There are many additional classes and operators associated with these classes. They are linked to from the class description pages.

8.2 Non-backward-compatible changes in Common Graphics

  1. The cg-user package no longer uses the ide package. To avoid certain name conflicts, the cg-user package no longer uses the ide package. Therefore, ide functionality must be package-qualified when called from the Debug window when the current package is cg-user (as it is when the Debug window is first displayed). This note is repeated in the IDE section.
  2. Incompatible find-window change. The function find-window now looks only for a child window by default, rather than for either a child or owned window. To look for an owned window you must specify the new owned-p keyword argument as true. This is for efficiency, to avoid looking at all top-level windows in the system when calling find-window on a top-level window. (For finding IDE windows, see the new IDE function find-ide-window.)
  3. Incompatible default for the proportional property of grid subsections. The default for the proportional property of a grid-subsection (either a grid-column or grid-row) has changed from t to nil. This item is repeated, with more details, in Section 8.3.1 Grid-widget-specific changes below.
  4. An obscure change to the value returned by pop-up-message-dialog. For consistency, when there is only a single choice in pop-up-message-dialog and the user cancels the dialog, it now returns 1 rather than 2 (and therefore ask-user-for-choice will return the single choice rather than nil).
  5. The value property of static-picture can no longer be used to set the pixmap. As a long-time backward compatibility, you could set the value property of a static-picture to be a pixmap to specify the image to display. This property is now used for something else (see pixmap-alist), and so you must use the pixmap, pixmap-name, or pixmap-icon property for the image, as documented.
  6. 6.0 project tab control widgets may not display properly. Widgets on tab-controls may be hidden if the code that creates them was generated for a form in a project and the code has not been generated since the 6.0 release. If this happens it can be fixed by removing :state :shrunk initargs in the code that creates the widgets.
  7. define-project is now named by a common-graphics symbol. In earlier releases, define-project was named by an ide package symbol, but for technical reasons the symbol has been moved to the common-graphics package. See the description of define-project.

8.3 Other changes in Common Graphics

There are many changes to grid-widget functionality. They are listed in Section 8.3.1 Grid-widget-specific changes below.

  1. The IDE and generated CG applications will now use Microsoft Visual Styles by default, for the newer Windows look. To disable this feature for a generated application, set the include-manifest-file-for-visual-styles property of the project to nil. To disable the feature for the IDE, rename the file allegro.exe.manifest in the main Allegro directory to something else and restart the IDE. The new function a-visual-style-is-active returns whether a visual style is currently in effect, and selected-tab-color returns the background color of the body of a tab-control (which can now differ from the system-dialog-background-color). Applications may want to change the background-color property of existing button widgets to t so that the background just outside of their rounded corners will match the color of the parent window or tab-control.
  2. lamp widget improvements including support for placing lamps on grid-widgets. There are a number of changes to the lamp widget. The most important is new support for placing lamps in cells of a grid-widget. See the description of the lamp widget for details.

    Other changes include allowing arrays of lamps to have individual on-colors and off-colors. The default for lamp-height and lamp-width is now 10 pixels. It is no longer computed using other factors.

  3. New initial-focus argument to pop-up-message-dialog. The function pop-up-message-dialog has a new initial-focus keyword argument that gets passed directly to pop-up-modal-dialog. It specifies which widget on the pop-up dialog will have ficus, and its possible values include :default (for the leftmost button), :cancel (for the rightmost button), or :buttonn, for button numbered n (see the function description for exact details).
  4. Menu bars are now possible on child windows on the Windows platform. There are some caveats. They are discussed in the description of menu.
  5. New function menu-bar-height. The menu-bar-height function returns the standard height of a menu bar. Because child window menu bars (see previous entry) are not part of the window's frame, they must be placed in the user coordinate system of the window. Widgets in the window must be placed so they do not overlap the menu bar. You use this function to know how much space to set aside.
  6. return-crlf argument to various functions no longer has any effect. The rather obscure return-crlf keyword argument of the user functions text-range, get-text, and rich-edit-range has been deprecated and no longer has any effect. It did not appear feasible to implement it with the newer version of the RichEdit control that CG now uses, and should no longer be useful now that the control internally uses a single character for each newline. The argument had been offered as a way to cause the character indexes of a string that's read from the control to match their indexes in the control itself, but that is now true in the normal case.
  7. New menu facility for many choices. The new function pop-up-menus-for-many-sorted-choices takes a potentially huge list of pre-sorted choices and presents them to the user as a series of pop-up menus. This makes it feasible to select one of many choices by letting the user select each successive unique character of the name of the choice from further pop-up menus.
  8. New scrolling-static-text widget. The scrolling-static-text widget allows you to easily place into a dialog a block of text that automatically wraps at spaces at the widget's width and which also scrolls vertically as needed. This had been possible to achieve previously by using a multi-line-editable-text and setting properties such as read-only to true, border to :none, and background-color to t (to match the parent window), but on GTK it was not possible to change the background color from white. Pertinent properties of this widget include value (the string to display), horizontal-justification, vertical-justification, margin-around-text, draw-focus, border, and border-color.
  9. The text-editing widget uses a newer version of Microsoft's RichEdit control. On Windows, the CG text-edit-pane and rich-edit-pane windows (and the multi-line-editable-text and rich-edit widgets that use them) now use version 2 or 3 (depending on the version of Windows) of Microsoft's RichEdit control, rather than version 1 as before. This newer version features multi-level undo and redo (for which the IDE has a new Edit | Redo command, and CG has the new user function redo-command). It may have better support for Input Method Editors and be more robust generally. If necessary, an application could revert to RichEdit version 1 by setting excl::*richedit-v2* to nil, or even revert to the US NT4.0 version of RichEdit version 1 that we ship by also setting excl::*use-aclre32.dll* to true; please tell us if you find either of these steps necessary so that we can retain these deprecated options as needed.
  10. Faster mouse wheel scrolling in the text-editing widget. CG overrides the new slower style of mouse wheel scrolling that Microsoft uses in newer versions of the RichEdit control with faster standard mouse wheel scrolling.
  11. HTML-browsing on GTK uses a third-party browser rather than a CG widget. On GTK, invoke-html-browser and invoke-private-html-browser will no longer defer to using a CG html browser, due to the unpredictability of the Mozilla GTK widget on which it is built. Instead, invoke-private-html-browser will first attempt to invoke a standalone Firefox HTML browser program by using run-shell-command, and if that fails it will simply place the URL or file path onto the system clipboard for the user to paste into an HTML browser by hand. And invoke-html-browser will skip the Firefox attempt altogether and use the clipboard directly.
  12. New functions return the available coordinate space across multiple monitors. The new functions virtual-screen-left, virtual-screen-top, virtual-screen-width, and virtual-screen-height return coordinates that denote the extent of all monitors in a multiple-monitor system. They will return 0, 0, (screen-width), and (screen-height) for single-monitor systems as well as for all systems on GTK. The new functions virtual-exterior and nvirtual-exterior return a box that combines these four values (when called on the screen; they are the same as exterior and nexterior when called on a window). The virtual-screen-left may be negative when a secondary monitor is configured to the left of the primary monitor.
  13. Other functions for the usable coordinate space work better with multiple monitors. The new functions usable-left and usable-top will return zero for windows. For the screen, they will return (virtual-screen-left) and (virtual-screen-top) for a multiple monitor system, or the left and top of the interior of the screen for a single monitor system. The pre-existing functions usable-width and usable-height will still return the page-width and page-height of a window, or interior-width and interior-height of the screen in a single monitor system, as before; but for the screen of a multiple-monitor system, they will now return (virtual-screen-width) and (virtual-screen-height).
  14. Tooltips are placed correctly on a secondary monitor that's on the left. A tooltip that should appear on a secondary monitor that is configured to the left of the primary monitor (in negative coordinates) had gotten moved to the primary monitor.
  15. The new function frameless-topmost-p may be useful on GTK. frameless-topmost-p is an overridable generic function that should return true if and only if instances of a window class should use the GTK_WINDOW_POPUP style on GTK. This is the only known way on GTK to make a non-child window that has no button in the taskbar. This property also forces the window to be frameless and topmost (in front of all non-topmost windows in all applications), and so is suitable only for true temporary "pop-up" windows such as menus and tooltips. This generic function has no effect on the Windows platform. To make a top-level window on Windows that has no taskbar button, either give it an owner window or specify its border property as :palette. (You can optionally eliminate the palette frame by also specifying the title-bar property as nil.)
  16. You can now grab the image from a hidden window. Calling get-pixmap on any window whose double-buffered property is true now works when the window is covered or shrunk, by grabbing the pixels from the backing store rather than from the screen.
  17. New options for the directory dialog. There is a new show-initial-directory-children argument for ask-user-for-new-or-existing-directory. There is also a search-network-globally argument to specify whether to search the network globally or only in the current context to find the machines to list. This argument is passed to win:network-machines, where it may affect performance or which machines are included.
  18. pop-up-lettered-menu has a new sort-key keyword argument. This new argument allows you to specify a key function for the sort-predicate function. It acts like the key argument to sort. See pop-up-lettered-menu.
  19. New show-help-string-under-mouse property; help-string property added to hotspots. The new widget/window/hotspot property show-help-string-under-mouse determines whether the object's help-string is shown in a status-bar whenever the mouse is over it. And the existing help-string property has been added to hotspots.
  20. New hidden-buttons property for multi-picture-button. The hidden-buttons property can be a list of button names to hide on a multi-picture-button when they are not applicable in the current context. This is simpler than replacing the entire list of button-info objects in the range property, and retains the order of the buttons when they are added back.
  21. New function require-cg-acache. require-cg-acache will load the newest version of AllegroCache that you have downloaded (unless AllegroCache is already loaded), and then load the CG module that depends on AllegroCache. This function is exported in case this loading is not always done automatically when needed.
  22. A generic function for hiding properties. The function property-hidden is now exported, similar to other attributes of property objects such as property-reader and property-read-only. Methods could be added that determine whether particular user-defined properties (see defproperties) appear in the inspector.
  23. The template-string facility has been improved. There are new choices in *template-chars* for a template-string. The new function digit-char-or-space-p can be used as a template char predicate function. Handling of the Delete, Backspace, Home, and End keys is more useful. Typing with the text cursor at the rightmost position will now insert characters and shift existing characters leftward; the Delete key in this position will shift characters rightward. The on-change function is no longer called on every keystroke of an editable-text that has a template string and whose delayed property is true. Selecting text with the shift key down is now allowed to work as usual. Typing a character while all text is selected now first clears the string to its default print string before inserting the typed character. There is no longer a break when the current widget value is not the same length as the template-string. Pasting into the widget will coerce the string to fit the template. The new template-allows-sign property allows the user to type a plus or minus character to the left of all non-whitespace characters.
  24. New standard light colors. The new global variables light-red, light-green, light-blue, light-yellow, light-cyan, and light-magenta have been added to go with existing color variables like red and dark-red.
  25. New extendable generic function screen-resolution-changed. screen-resolution-changed will be called whenever the size of the screen has changed, such as when using Remote Desktop or attaching a second monitor. An application could add a method that moves or resizes windows at this time.
  26. Moving edited text with the mouse. The control-left-click gesture in a lisp-edit-pane (such as in the IDE editor) to copy the expression at the click position to the text cursor position will now reindent the copied lines. And a new control-shift-left-click command will move the text rather than copying it.
  27. Static-picture widgets and the new pixmap-displaying grid cells allow cycling through a set of pixmaps. A static-picture widget can now draw a pixmap that is mapped from an arbitrary user value to a pixmap by the new pixmap-alist property. (This is also a feature of the new pixmap-displaying grid cells.) The new property user-modifiable determines whether the user is allowed to cycle through the pixmaps, which they do by clicking the widget or grid cell or by pressing the spacebar when it has the keyboard focus. The new pixmap-value-test property determines whether a new user value matches an entry in the pixmap-alist. A static-picture widget now has the draw-focus property like picture-button, as well as the tabstop property.
  28. above-parent property of outline-items and handle-above-parent property of outlines. Both these properties were available in release 8.0 but not documented. They now are documented. They allow specifying whether an outline-item is displayed above its parent (when above-parent is set to true and the handle-above-parent property of the outline is also true).
  29. New arguments avoid consing RGB objects. The functions make-rgb, effective-background-color, and effective-foreground-color take a new scratch-rgb keyword argument, which can be used to prevent the function from ever consing a new RGB object.
  30. Outline-items can be placed above their parent items. The outline widget has a new option to position some child items above their parent items. This might be useful for indicating that a child item is special in some way. The child outline-item's above-parent property must be true, and the outline's handle-above-parent property must be true. This feature can slow down the redisplay of a large outline, but only when the outline's handle-above-parent option is turned on.
  31. New function scroll-window-into-parent. The new user function scroll-window-into-parent scrolls a parent window so that the specified child window is fully visible (when possible).
  32. Using get-screen-box without drawing the box. The function get-screen-box has a new no-draw keyword argument that avoids drawing the rubber-banding box. The function get-screen-pixmap also has this new argument, which may be needed if the screen is being redrawn in some way as you select the region to capture.
  33. Timers remember their next fire time. The new timer-universal-time property of the timer class stores the universal time at which the timer is currently set to go off, or nil when the timer is not set. (Not useful for sub-second times.)
  34. New macros with-fill-texture, with-background-texture, and with-line-texture. The new macros with-fill-texture, with-background-texture, and with-line-texture temporarily sets the fill-texture/background-texture/line-texture of a stream, similar to existing macros for other drawing attributes such as with-foreground-color and with-line-width.
  35. It is easier to add keyboard scrolling behavior to an arbitrary window. You can enable the new handle-scrolling-keys window property by passing handle-scrolling-keys initarg to make-window or by calling (setf handle-scrolling-keys) later. If the user types PageUp, PageDown, or an arrow key, and no more-specific virtual-key-down method intercepts the keystroke, then a built-in method will now scroll the window by the amount returned by a call to scroll-increment. (The type argument to scroll-increment will be :page for the PageUp and PageDown keys, or :line for the arrow keys.) If the control key is held down, then the window will scroll horizontally, and otherwise it will scroll vertically. Previously you needed to write a custom virtual-key-down method to gain this behavior. The handle-scrolling-keys value may be t to handle all page and arrow keys, :vertical to exclude the horizontal arrow keys, or :page to exclude all arrow keys.
  36. The initial-focus argument to pop-up-modal-dialog is more flexible. initial-focus argument may now alternately be the name of the widget rather than the widget itself. And when the initial-focus widget is a regular button, it will now also be the initial acting default button (as with set-default-button). See pop-up-modal-dialog.
  37. You can determine if the user selected the Print To File option. If the user selects the Print To File option of a printer driver's Print Job dialog, then the filename property of the printer stream will be t rather than nil to indicate that a print-to-file was done. (It does not appear feasible to find the actual path that the user specified interactively.)
  38. list-widget-set-index can now trigger the on-change function. It has been inconsistent that calls to list-widget-set-index do not cause the widget's on-change function to be called, so you can now pass the new trigger-on-change keyword argument to make that happen. It is nil by default for backward compatibility, though it is typically best to pass it as true.
  39. New aid for displaying a document in a third-party program. The new Windows-only function windows-command-for-document-type returns a command-line string that can be used with run-shell-command to invoke whatever program is registered for handling files of a specified file type. The setf can even be used to register a particular program for some file type.
  40. Additional def-cg-ocx-control arguments for the Components Toolbar. The function def-cg-ocx-control has the new keyword arguments toolbar-after, toolbar-tooltip, and toolbar-help-string. These arguments are passed through to add-to-component-toolbar.
  41. New drawing functions let you avoid creating position objects. The new functions draw-box-x-y, draw-by-x-y, draw-line-x-y, fill-box-x-y, erase-to-x-y, erase-by-x-y, erase-box-x-y, erase-contents-box-x-y, erase-line-x-y, and invert-box-x-y allow drawing lines and boxes without first creating position objects from the x and y coordinates.
  42. You can check whether certain objects have user modifications to save. The newly-exported generic function modified returns whether an object has unsaved user changes. Applicable classes in which an application may be interested include text-edit-pane, rich-edit, grid-widget, and object-editor.
  43. There is a new macro to temporarily allocate a color. The newly exported macro with-rgb allows temporarily using an RGB object rather than consing one.
  44. Rich-edit opening and saving can handle plain text. The function rich-edit-open takes a new allowed-types argument to pass to ask-user-for-existing-pathname. The function rich-edit-save takes a new format argument like that of rich-edit-range, which allows saving the contents as plain text rather than rich text. The function rich-edit-save-as takes both of these arguments, where allowed-types defaults to (("Rich text" . "*.rtf")) when format is :rich-text or to (("Text" . "*.txt")) when format is :text.
  45. Keystrokes to open descendent items of an outline-item and cancelling opening. Control-clicking the icon of an outline-item in an outline widget or selecting the item and pressing control-right-arrow opens all descendents. If there are very many (or perhaps the items loop), this can take a long time and can be canceled with the Escape key. See range-on-open.
  46. Drawing functions are now generic. Drawing functions (which are mostly named draw-something or erase-something though there are additional ones) have been a mix of generic functions and non-generic functions, and not for any particularly good reason. They are now generic functions. The following have been changed from regular to generic in release 8.1: draw-by, draw-by-x-y, draw-line, draw-line-x-y, draw-to-x-y, erase-box, erase-box-x-y, erase-by, erase-by-x-y, erase-circle, erase-circle-arc, erase-circle-sector, erase-contents-box, erase-contents-box-x-y, erase-contents-circle, erase-contents-circle-sector, erase-contents-ellipse, erase-contents-ellipse-sector, erase-contents-polygon, erase-contents-rounded-box, erase-ellipse, erase-ellipse-arc, erase-ellipse-sector, erase-line, erase-line-x-y, erase-polygon, erase-polyline, erase-rounded-box, erase-to, erase-to-x-y, move-by, move-by-x-y, move-to-x-y, pixel-x-y.
  47. undo-command now works on GTK as well as Windows. See undo-command.

8.3.1 Grid-widget-specific changes

  1. New grid-widget utility functions invalidate-whole-section and cross-section-box. The new function invalidate-whole-section invalidates a grid section or subsection, while cross-section-box returns a box for the intersection of a row or row-section with a column or column-section.
  2. New grid-widget properties cache-cell-values and delay-write-cell-value. When cache-cell-values is true, cell values are cached, allowing them to be retrieved more quickly. You can also use delay-write-cell-value to wait until a number of changes (often on a dialog) are made and then write them all at once or cancel them.
  3. The function delete-selected-subsections is more modifiable. The grid-widget function delete-selected-subsections now calls the exported generic functions delete-row and delete-column for each deleted subsection so that you can add wrapper methods for side effects, such as deleting the data-object of each deleted row.
  4. Minimum size is implemented for grid-widget sections. The existing minimum-size property is now also a property of grid-row, grid-column, grid-row-section, and grid-column-section. It can have the value nil for those objects, which means inherit from the value for the whole grid-widget.
  5. New grid-column properties. The grid-column class now implements the existing properties horizontal-justification, vertical-justification, single-line, and on-print. It also defines the new properties horizontal-padding and vertical-padding. Some of these can be given to a grid-column instance instead of defining methods on column and row classes for generic functions such as cell-horizontal-justification and cell-horizontal-padding.
  6. New data-slot property of grid-column. A grid-column may now be given a data-slot property as an alternative to the data-reader property. This is useful when the slot does not have a reader and/or writer function or those functions are not known.
  7. delete-selected-subsections returns a meaningful value. The return value from the grid-widget function delete-selected-subsections is now the list of subsections that were deleted. This is nil if no subsections were selected or if the user canceled the confirmation dialog.
  8. New grid-widget cell type for displaying choices as pixmaps. The new pixmap-column-mixin class can be used for displaying pixmaps in grid cells. Multiple pixmaps can be supplied to represent various possible user values. Clicking the cell (or pressing the spacebar when the cell has the keyboard focus) will cycle to the next pixmap and write the value that it represents back into user data. This class is similar to existing classes like editable-text-column-mixin.
  9. New extendable grid-widget generic function subsection-sequence-changed. An application could define methods on the new generic function subsection-sequence-changed in order to catch any time that the sequence of rows or columns in a grid-section has changed. It is called when the user interactively slides rows or columns to change their order, and when the sequence is changed by calls to (setf subsections), add-row, add-column, delete-row, and delete-column.
  10. Centered check-boxes in grid cells. If a check-box grid column has no title-reader, meaning that there will never be text in the cell, then the check-box will now be centered horizontally.
  11. Grid-widgets show unavailable status. A grid-widget will now be drawn by default with a gray foreground color when its available property is nil.
  12. The template-string facility now works in grid-widgets. The editable-text-column-mixin class and the combo-box-column-mixin class now have a template-string property to make type-in work as with the existing template-string facility of an editable-text widget.
  13. Incompatible default change for the proportional property of grid subsections. The default value for the proportional property of a grid-subsection (either a grid-column or grid-row) has changed from t to nil, because it is typically more useful to create them at a size that fits their content rather than making them stretch to fit the parent grid-section. The default for grid-section is still t. Any application code that did not specify this property for grid columns or rows and depends on it to be true should add :proportional t initargs to the calls to make-instance that create the columns and rows.
  14. Moving to the very end of a grid-section with PageUp and PageDown. When scrolling a grid-widget section with the PageUp and PageDown keys, if the section is already scrolled to the end then a further keystroke will move the focus to the endmost subsection. This makes it easier to move all the way to the end subsection when the Home and End keys won't do it because the focus is in an editable text cell.

8.4 IDE release notes

  1. Non-backward-compatible change: you may need to qualify IDE symbols. The cg-user package no longer uses the ide package, to avoid a problem where a local variable in user code that has the same name as an exported IDE symbol would be written into the user's fasl file as the symbol in the ide package. This would break in a standalone application where the ide package does not exist. This change means that when in the cg-user package in the IDE, you must add an ide: package qualifier to any IDE symbols that you use programmatically. (This item also appears in Section 8.2 Non-backward-compatible changes in Common Graphics above.)
  2. The IDE now uses a parent window rather than an owner window. The use-ide-parent-window IDE configuration option is now turned on by default on the Windows platform (as on GTK before), now that we have implemented a way for form windows to have menu-bars when they are child windows. The IDE's main window also has scrollbars to allow arranging IDE tool windows into a larger space than will fit on the screen. Using an IDE command to select an IDE tool window will automatically scroll it fully into view. There are also commands on the View | Manage Windows menu whose keyboard shortcuts can be used to scroll the entire IDE with keystrokes at any time.
  3. There is a new Class Interface Editor dialog in the IDE. The Class Interface Editor dialog allows you to interactively set up an object-editor dialog or class-grid widget (which are new in CG) for editing the slot values of the instances of some class, typically from a database. You can specify which slots should have widgets or grid columns as well what type of widget to use for each slot. This creates the edited-slots property for an object-editor or class-grid interactively so that you don't need to remember the format of that large property value and write it by hand.
  4. New Redo command for the editor. There is a new Redo command on the Edit menu (on the Windows platform only). The keyboard shortcut for the File | Compile command has changed from control-Y to control-shift-Y so that the new Edit | Redo command can use control-Y to follow the usual convention.
  5. The name of the IDE options file now includes the lisp version. The name of the options file (aka preferences file) will now include the major and minor version numbers of the lisp, as in allegro-prefs-8-1. This is to avoid a problem where exiting one version of lisp and then starting an older version could break because new configuration options saved by the newer version do not exist in the older version. This means that if you want to use an existing options file when you install a new release of Allegro, you will need to rename the options file accordingly.
  6. New utility functions for debugging output to an IDE listener. The newly-exported macro with-output-to-ide-listener and function format-debug make it convenient for application code to write debugging output to the currently selected IDE listener.
  7. eval-in-listener-thread has new funcall option and a new trap-errors keyword argument. The function eval-in-listener-thread has a new keyword argument to funcall (rather than eval) the main argument (which should be a funcallable object that will be passed no arguments). Another new keyword argument is trap-errors. It controls handling of errors signaled while the main argument is being evaluated or funcalled.
  8. The positioning of the Debug Window and Editor has changed. The IDE's Debug Window and Editor now default to a larger size and are placed side by side (though overlapped to make each one adequately wide).
  9. No Startup Action dialog until there are recent projects to reopen. The Startup Action dialog will now appear at IDE startup only if the ask-for-action-at-ide-startup option is enabled (as before) and there is at least one previously opened project that can be offered in the list of recent projects to reopen.
  10. You can avoid the confirmation dialog for unqualified symbols. The new IDE configuration option ask-before-assuming-package determines whether a confirmation dialog will appear if you invoke an IDE command in a text control where there is a string that does not name a symbol in the current package, but does name a symbol in some other package. The default value is nil, meaning that the IDE will proceed to act on that symbol without showing the confirmation dialog. To restore the 8.0 behavior, where a dialog will ask whether you intended to act on the found symbol, set this option to true. The Find In Files dialog will never pop up a dialog about the package, as many users found that was more annoying than useful in this dialog.
  11. Complete History Expression can now retrieve earlier matches. If you type the first part of a previously-evaluted form into an IDE listener and then invoke the Complete History Expression button (typically by typing its shortcut, alt-L), but the form that's copied to the prompt is not the one that you're looking for, then you can invoke the command repeatedly until the desired match appears at the prompt.
  12. The IDE will rescue windows that get moved off the screen. If you somehow manage to move an IDE tool dialog so that it is completely off the screen, then the IDE will automatically move it into view the next time you invoke the dialog with its usual command. (Selecting the window in the View | Window List window already did this.)
  13. The patches dialog can handle firewall proxies. The Download Patches dialog now has widgets for specifying an HTTP proxy when needed. These values (except for the password) are saved into the new default-http-proxy IDE configuration option to remember the values in future IDE sessions.
  14. New function selected-listener-pane. The function selected-listener-pane has been exported for returning the currently-selected IDE listener pane. It may be desirable to print debugging output to this particular stream.
  15. A new macro for printing to the IDE listener. The macro with-output-to-ide-listener is handy for directing stream output to the currently selected IDE listener window (though IDE Listener processes do that already). It finds the proper window and also has options for first moving to the end of the text and for printing a fresh prompt or scrolling to the top of the output after printing.
  16. Building a distribution lets you overwrite an existing subdirectory. The File | Build Project Distribution command now allows replacing an existing directory with the new distribution directory as long as the specified directory is a subdirectory of the project's default directory. Replacing an existing directory had been totally disallowed for safety reasons, but made it inconvenient to reuse multiple distribution directories or to reuse a single distribution directory after deleting the preferences file.
  17. Build Project Distribution no longer does a purify by default. The purify option is no longer turned on by default for a standalone application that is generated for a project, to remove the additional .pll file from the distribution and avoid a possible conflict with its positioning in memory at run time.
  18. New widgets on the toolbar. The Components Toolbar has new buttons for creating the new chart-widget and class-grid controls. (It is more feasible to develop a class-grid on a form than it has been for the general grid-widget.)
  19. A new menu of definitions in the current buffer. The new editor keystroke Control-comma will show a menu of all definitions in the buffer, and selecting one jumps to that definition. Control-alt-comma does the same thing except also sorting the definitions by their names.
  20. A new function for finding IDE windows. The new function find-ide-window may be called to find an IDE window from its name. This may be useful if you are extending the IDE by operating on its windows programmatically. This function will work regardless of the value of the use-ide-parent-window configuration option. It may especially be needed due to the incompatible change to find-window.
  21. Resizing grid sections on a form. You can now interactively resize grid-widget sections and subsections on a form window just as you would on the running window. (This is most useful with the new class-grid control, which is feasible to develop on a form.)
  22. New keyboard shortcuts on a form window. You can now show a form window's shortcut menu by pressing the spacebar (as an alternative to right-clicking). And you can deselect all selected widgets by pressing the backspace key (which complements using the Tab key to select successive widgets).
  23. New icons in the Project Manager. The Edit Dialog Form and Edit Source Code buttons in the Project Manager dialog have new icons to make it easier to tell them apart.
  24. Different keyboard shortcuts in the Project Manager. The Project Manager's right-button shortcut menu has different keyboard shortcuts that don't conflict with menu-bar accessors and that are hopefully easier to remember.
  25. Better default directory for adding a subproject. When using the Project Manager's Add button to add a subproject, the file selection dialog now begins in the parent project's directory rather than in the directory that was last used in the file dialog.
  26. Project Manager buttons disabled when inapplicable. The Project Manager's toolbar buttons are now disabled when they are not applicable to the currently selected tab or to the module that's selected in the list of modules.
  27. You can show the Project Manager's menu with the spacebar. When the keyboard focus is in the Project Manager's list of modules, you can now show its right-click shortcut menu by pressing the spacebar. Also, pressing the Enter key in this widget will emulate the View Selected Code button in the toolbar.
  28. The Options Dialog includes several addtional configuration options and several have been removed. The new and removed options on the Options dialog include query-os-exit and ask-before-assuming-package (a new one) on the IDE 1 tab, use-cg-html-browser (titled Show IDE Help Within the IDE) and move-ide-windows-on-screen-resize (another new one) on the IDE 2 tab, and project-parent-directory on the Project tab. scroll-while-tracing has been removed because it is on the Trace Dialog. class-graph-initial-depth has been removed due to obscurity. There are still some options that are not on the dialog, but they generally are either obscure or have other interfaces in the IDE for controlling them.
  29. Window positions and sizes are now remembered for each screen resolution. The IDE's options file will now save a distinct set of positions and sizes of the IDE tool windows for each different screen resolution at which the IDE is run. When first creating each tool window after starting the IDE, it will be created at the position and size that it had when the options file was last saved at the current screen resolution, if any, and otherwise it will be created at its default position and size. In addition, the new move-ide-windows-on-screen-resize configuration option determines whether the IDE will automatically move and resize its tool windows in this way when the screen resolution changes while the IDE is running. (This can happen, for example, when switching to or from a Remote Desktop session or when attaching or removing an auxilliary monitor.) This option is enabled by default.
  30. Interrupting reindentation in the editor. It is now possible to interrupt the Edit | Reindent command by pressing the Escape key. (That command can take a while for a long form.) The form may be left partially reindented, though.
  31. Newline added after pasting blocks of text. Pasting multiple lines of text into the middle of line of text in a lisp-editor-pane (such as an IDE editor pane) will insert a newline afterward automatically.
  32. An obscure directory dialog option. The new IDE configuration option directory-dialog-searches-network-globally determines the value that the IDE will pass for the search-network-globally argument of ask-user-for-new-or-existing-directory whenever an IDE command presents the directory-selecting dialog. This value may affect performance or which machines are listed.
  33. A distinct options file for the Express version. The string "-express" is now included in the options file name for the Express release to distinguish it from an options file for a non-Express product on the same machine.
  34. Listener panes now list restarts. The IDE debugger will now print the available restarts into the listener pane to match the behavior of a non-IDE lisp.
  35. A new function tells you where IDE preferences are saved. The function ide:options-path returns the path to which the IDE would save its file of user preferences. The user-specific argument can be passed as true or nil to find the path that would be used for each value of the save-options-to-user-specific-file option. The default value of this argument is true (as is the default value of the save-options-to-user-specific-file option).
  36. The keyboard shortcut for Close Pane is more convenient. The shortcut for the File | Close Pane command is now control-alt-X instead of control-F4, because the latter is harder to reach. Control-F4 still works, though, because it's been added to the IDE's global keyboard shortcuts for backward compatibility (and because that keystroke is a semi-standard Windows keystroke).
  37. More useful Enter key handling in the Trace Dialog. Pressing the Enter key in the Trace Dialog will now do something reasonable for the widget that currently has the keyboard focus (generally whatever double-clicking it does), instead of invoking whichever button widget most recently had the focus.
  38. Copying evaluated forms from the editor to the listener. When using the numeric keypad Enter key (or the main Enter key with the Alt key held down) to evalaute the form after the text cursor in the editor, the evaluated form will now be copied to the IDE listener if the control key is held down. This helps to see the context of a series of evaluated forms, though on the other hand it can clutter up the listener when evaluating large forms.
  39. No snapping to the grid when dragging widgets on a form window. The snap-to-grid option of form windows is now off by default because it makes it more difficult to align widgets with each other rather than to the arbitrary grid.
  40. Find In Files reports total matches. The Find In Files dialog now reports the total number of matches found in all files (or editor panes) that were searched.
  41. A project can handle an on-initialization function in an unrelated package. A package problem should no longer occur when opening or loading a project if the .lpr project definition file contains a symbol (such as the on-initialization function) that's in a non-built-in package that is also not the project's default package.
  42. The autoload-warning property of a project is no longer on by default. Autoload-warning is now nil initially to match the generate-application default and because it causes a break if you do not have permission to write to the lisp installation directory. This doesn't affect the value for existing projects.
  43. define-project is now named by a common-graphics symbol. In earlier releases, define-project was named by an ide package symbol, but for technical reasons the symbol has been moved to the common-graphics package. See the description of define-project.

8.4.1 Opening projects from releases prior to 8.1

Allegro CL 8.0 projects should open without problem in Allegro CL 8.1.

8.5 Functionality to handle differences between Windows and GTK

For complete information on the differences between Windows and GTK, please see cggtk-relnotes.html.

Common Graphics and the IDE now run on Windows and Linux with GTK. Certain differences between the two operating systems and windowing systems mean that some things do not work the same in Windows as in GTK and vice versa. The functionality listed here tries to handle the differences. Some of the variables/operators/etc. are only available on one of the two platforms.

Known bug with menu-items and buttons

GTK Only: all-black menu-items and half-black buttons. There is still a mystery on the GTK platform where all button widgets can turn half black along a diagonal line, and all menu-items on some platforms will be totally black. This seems to happen only when opening a project from the Startup Action dialog, though, so a workaround is to not reopen a project from that dialog and instead to use the Recent menu or File | Open Project just afterward. We have tracked the problem down to the use of transparent-pane windows such as the frame-child of a form window, but beyond that it is a total mystery.

Mozilla support

The system needs to know the directory where the GTK control supplied by Mozilla to support the html-widget resides. (On windows, the widget is implemented in another way.) It may not be practical to search for the location automatically. See mozilla-library-path, *mozilla-library-path*, and find-mozilla-gtk-path.

Event handler processes

Because Linux currently does not use native threads and Windows does, on Windows, all windows handle events in their own thread associated with the window while on Linux/GTK, there is one event-handling thread. default-application-window-subkey, *use-single-cg-event-handling-process*, and *single-cg-event-handling-process* allow distinguishing behavior when necessary. cg-process-wait should be used on GTK instead of process-wait in event handlers. See also process-pending-events-if-event-handler.


8.6 Release notes for the winapi module

The winapi module contains certain functions, in the windows package, that perform OS-related tasks. See The Windows API and a Windows API program with windows but without CG in cgide.htm for more information. The following changes were made in this module in release 8.1.

  1. Some foreign functions in the winapi module have been changed from :release-heap :when-ok to :release-heap :never. This was done mostly for efficiency reasons, to avoid the overhead of releasing the heap for functions that would clearly never call back into another lisp process. There is a slight chance that one of these functions actually will call back into another lisp process, leading to a deadlock. This has not happened in our testing, and so we do not expect it to be a problem. (See the release-heap keyword argument to def-foreign-call for information on releasing the heap.)
  2. New global keyword argument for win:network-machines and win:network-shares. The functions win:network-machines and win:network-shares each have a new keyword argument called global. When true, the entire network is searched. When nil, only the "current and default network context" is searched. In 7.0 and 8.0 these functions always behaved as if global was true, but the default has now been changed to nil to avoid waiting on parts of the network that might have a significantly delayed response. To match the earlier behavior, you must pass this argument explicitly as true.
  3. New return-tree keyword argument to win:network-machines. The function win:network-machines has a new return-tree keyword argument. When this argument is true and the new global keyword argument is true (see above), the returned list will be a tree structure similar to the My Network Places tree in the Windows File Manager. When nil (the default), a simple list of all machines will be returned as before.
  4. New allowed value for machines argument to win:network-shares. The value of the required machine argument to win:network-shares has an additional possible value, which is the symbol :tree for returning the set of all networked machines and their shares as a tree rather than a list (when the new global argument (see above) is true.
  5. Behavior of win:network-machines and win:network-shares when there is an error. If an unknown error occurs in win:network-machines or win:network-shares while trying to access a particular machine, then the symbol :unknown-error will be returned rather than signaling an error. (For win:network-shares, this symbol would replace the list of shares for a particular machine in the returned list.) This is similar to returning :access-denied when a machine does not allow access.

9.0 Release notes for AllegroServe

10.0 Release notes for The Emacs/Lisp interface

11.0 Availability of CLX for Allegro CL

CLX (Common Lisp X) provides an interface between Common Lisp and the X window system. All versions of Allegro CL include a compiled version of CLX with the distribution. The fasl file is code/clx.fasl, loaded by evaluating (require :clx). The Allegro CL products CLIM and Allegro Composer use CLX. Users wanting low-level access to an X server in Lisp may also want to use CLX. CLX is not supported by Franz Inc.

The sources to CLX are supplied with the regular Allegro CL distributions in the contrib/clx/ directory. Note that during installation, you are asked whether you wish to install the contrib/ directory and the default is not to install it. The contrib/ directory is not included in the Trial distribution, but Trial users can download the CLX sources from the Franz Inc. website as described next.

The sources to CLX are also available on the Franz Inc. web site (, at the location

12.0 Release notes for Orblink

No significant changes.

Appendix A: ANSI Conformance in Allegro CL

We discuss ANSI conformance in Conformance with the ANSI specification in implementation.htm. Elsewhere in implementation.htm we discuss specifics of our implementation of certain Common Lisp functionality.

Copyright (c) 1998-2016, Franz Inc. Oakland, CA., USA. All rights reserved.
This page has had minimal revisions compared to the 8.1 page.
Created 2016.6.21.

Allegro CL version 8.2
Minimally revised from 8.1.