ide operators

Arguments: component-class-name pixmap-or-title &key after tooltip help-string

This function allows developers to extend the IDE to include their own classes. It adds a new button to the IDE's Component Toolbar to allow a specified control class to be interactively instantiated onto a form. The control class is also added to the list of component classes presented by the Form | Add Component menubar command. If the class is already represented on the Component Toolbar, then no button is added.

The new button will remain on the toolbar only as long as the current invocation of Allegro is still running, rather than being added back automatically the next time that Allegro starts up. If a project defines a custom control class, you may want to add a call to add-to-component-toolbar to one of the project's .cl source code files as a top-level form --- then the control class will be added to the toolbar if needed whenever the project is loaded. Alternately, a call to add-to-component-toolbar could be placed in the startup.cl file or in an *ide-startup-hook* function. (See About IDE startup in cgide.html.)

component-class-name is either the name of a control class to be added or the symbol :gap. Specifying :gap inserts a small gap (with a thin bar drawn in it) between groups of buttons, as usual with a multi-picture-button range. A multi-picture-button will automatically filter out multiple contiguous gaps, so an application does not have to worry about whether a gap is already where one is desired.

Example:

;; Define a custom single-item-list.
(defclass pretty-item-list (single-item-list)()
  (:default-initargs
   :background-color cyan))

;; Define a pixmap to represent the custom control class.
(cache-pixmap
 (make-instance 'pixmap
   :name 'pretty-item-list
   :bits-per-pixel 4
   :colors (default-palette-vector *system*)
   :contents
   '(( 7  7  7  7  7  7  7  7  7  7  7  7  7  7  7  7)
     ( 0  0  0  0  0  0  0  0  0  0  0  0  0  0  0  0)
     ( 0 14 14 14 14 14 14 14 14 14 14 14 14 14 14  0)

     ( 0 14  0 14  0 14  0 14 14 14 14 14 14 14 14  0)
     ( 0 14 14 14 14 14 14 14 14 14 14 14 14 14 14  0)
     ( 0  0  0  0  0  0  0  0  0  0  0  0  0  0  0  0)
     ( 0  0 14  0 14  0 14  0 14  0  0  0  0  0  0  0)
     ( 0  0  0  0  0  0  0  0  0  0  0  0  0  0  0  0)
     ( 0 14 14 14 14 14 14 14 14 14 14 14 14 14 14  0)
     ( 0 14  0 14  0 14  0 14 14 14 14 14 14 14 14  0)
     ( 0 14 14 14 14 14 14 14 14 14 14 14 14 14 14  0)
     ( 0  8  8  8  8  8  8  8  8  8  8  8  8  8  8  0)

     ( 0 14 14 14 14 14 14 14 14 14 14 14 14 14 14  0)
     ( 0 14  0 14  0 14  0 14 14 14 14 14 14 14 14  0)
     ( 0 14 14 14 14 14 14 14 14 14 14 14 14 14 14  0)
     ( 0  0  0  0  0  0  0  0  0  0  0  0  0  0  0  0))))

;;; Add a button using the above pixmap to instantiate the custom control.
(ide:add-to-component-toolbar 'pretty-item-list
 (find-pixmap 'pretty-item-list) :after 'single-item-list)

additional-build-lisp-image-arguments

Returns a plist of build-lisp-image keyword argument names and values that will be used when generating a standalone application for the specified project. The setf of this function may be called to set the value. This project property is supplied as a catch-all for any build-lisp-image arguments that are not covered by more specific project properties.

The initform for this project accessor is (list :read-init-files nil). This is a rather arbitrary default value, being non-nil largely so that the required format in the Project Manager dialog (see next paragraph) will be apparent.

There is a widget on the Advanced tab of the Project Manager dialog for specifying these arguments. The widget should contain only the argument names and values, without any surrounding parentheses, and so the default value will appear in the widget like this:

after-functions

Returns the after-functions of project. After-functions are functions of zero arguments called after a project is compiled. You might, for example, use a before function (see before-functions) and an after function to reset compiler optimizations to values appropriate to your application but not wanted as the current values.

all-files

Arguments: project &key subprojects-later include-editable-files include-distributed-files

Returns a list of the files of a project and its subprojects. All files are included except as indicated otherwise below.

By default, the returned list contains the project's files in the same order that they would be listed in the Project Manager dialog, which is also the order in which the loadable files are loaded. But if subprojects-later is true, then a project's own files will always be listed before the files of its subprojects.

Editable files of the project (files that are neither loaded nor distributed) are excluded unless include-editable-files is true. See editable-files.

Distributed files are excluded unless included-distributed-files is true. See distributed-files.

all-projects

Returns a list of all projects defined in the current Lisp invocation. The argument must be a project but does not affect the result.

all-runtime-modules

Returns a list of keywords that name all Common Graphics modules. A subset of this list could be passed to (setf runtime-modules) to specify which modules to include in the standalone CG application that is generated for a project. (Typically this is specified interactively instead on the Include tab of the Project Manager dialog.)

Each module is a fasl file in the code/ subdirectory of the main Allegro directory, and could be loaded directly into a base Lisp. Each module will automatically load any other modules on which it depends.

Note that any periods in a CG module name are replaced by dashes in the corresponding file name, due to a restriction of logical pathnames. So if require is called to load a CG module, it should be of this format:

allow-component-overlap

If this property is true, controls on a dialog can overlap one another (so one partially covers another). If the property value is nil, controls cannot be placed so they overlap while designing a form with the Integrated Development Environment. (If you try to position a control over another, the one being positioned moves when you release the mouse.) However, controls can always be repositioned programmatically (with, say, (setf left) or (setf top)). This property does not affect programmatic repositioning. It only affects the design of forms.

ask-before-assuming-package

This property controls whether a confirmation dialog will appear if you invoke an IDE command on 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 the found symbol without showing the confirmation dialog.

ask-before-auto-saving

Returns (or sets with setf) whether a Save All confirmation dialog will appear whenever unsaved files are about to be saved automatically. If true, then the files will be saved only if you agree to save them. If nil, the files are simply saved (though you will still be prompted for a save pathname for any file that has not yet been saved). When there are no unsaved changes, the dialog will never appear and no saving will be done.

Automatic file saving is done when exiting the IDE, running a project or form, opening a project, creating a new project, closing the current project, generating a standalone executable or distribution, or using the Find Required Common Graphics Modules button on the Include tab of the Project Manager dialog. These are times when it is usually desirable to save everything before continuing the operation. Auto-saving affects only files related to the current project except when exiting the IDE, when it also affects other unsaved editor buffers.

The dialog has the following three buttons: Yes to save files and then proceed, No or Discard to skip saving files and proceed anyway, and Cancel to skip saving files and cancel the operation that initiated the saving. The second button says Discard when selecting it would cause any unsaved changes to be lost, and No when it would simply leave unsaved changes that may be saved later. Discard will appear when opening a project, creating a new project, or closing the current project, since choosing it would discard unsaved changes to the old project. Discard will also appear when exiting the IDE, since choosing it would discard all unsaved changes.

Initially all files that would be auto-saved are shown selected in a list widget, but you may deselect some of the files in order to save only the remaining selected ones.

There is a check-box for this property on the IDE 1 tab of the Options dialog. This property is on by default.

ask-for-action-at-ide-startup

Returns whether a dialog appears when the IDE starts up, asking whether to open a recently-used project, open some other project, create a new project, or proceed without a current project. The setf of this function may be called to set this option for future invocations of the IDE. This option appears on the IDE 1 tab of the Options dialog (displayed with Tools menu | Options) as the check-box labeled Ask for Action at IDE Startup. It may also be turned off by unchecking the check-box titled Show this dialog at IDE startup time at the bottom of the Startup dialog itself.

An exception is that the dialog will never appear if there are no known projects to offer for reopening. This will be the case if you have never created a project, or if you have deleted your IDE preferences file since using any projects.

Example

autoload-warning

Returns the value of the autoload-warning property of the specified project. The value is normally set by clicking on the Autoload Warning check-box on the Advanced tab of the Project Manager dialog (or perhaps by editing the .lpr project definition file of the project).

If true (the default), an autoloads.out file is created to tell you what autoload fasl files you may need to distribute with your application. If nil, this file is not created.

The value may be a string naming a pathname (though such a value cannot be specified in the Advanced tab of the Project Manager dialog). In that case, the autoload information will be written to the specified file rather than to the file autoloads.out.

backtrace-frames-to-show

This IDE user option controls the number of frames (function calls) that a backtrace will initially show when you go into the debugger. This is also the number of frames that will be added (when there are any) when you scroll to the bottom of the backtrace or select the bottommost frame that's already displayed. The initial value is 30.

This option is not on the options dialog, but you could set it programmatically with a form like this one:

backtrace-print-circle

This generic function has been renamed to dialog-print-circle. The symbol ide:backtrace-print-circle no longer names an operator.

backtrace-print-length

This generic function has been renamed to dialog-print-length. The symbol ide:backtrace-print-length no longer names an operator.

backtrace-print-level

This generic function has been renamed to dialog-print-level. The symbol ide:backtrace-print-level no longer names an operator.

backtrace-safe-mode

This user option could be enabled if the IDE's debugger fails to present a backtrace when you press the Debug button on the Restarts dialog after an error. It checks for various unexpected conditions while producing the backtrace so that it will likely then succeed. (See Debug Window after an Error for information on the Restarts dialog.)

You could then use the bug report button above the backtrace to generate a bug report file to send to us, which may help us track down the problem with showing the backtrace. The backtrace itself may show special messages about the nature of the problem.

The default value of this option is nil, and the option is not on the Options dialog, because it hopefully won't be needed. But if it is needed, you can enable it by evaluating this expression:

before-functions

Returns the before-functions of project. Before functions are functions of zero arguments called before a project is compiled. You might, for example, use a before function and an after function (see after-functions) to reset compiler optimizations to values appropriate to your application but not wanted as the current values.

browser-keychords

Returns a list of strings for the set of keystrokes that CG's JavaScript code will pass through to the web browser for its built-in behavior. See the Project Manager option below for more information.

This CG/JS option is typically set with the Browser Keychords widget in the CG/JS tab of the Project Manager dialog in the IDE. But it could be set programmatically like this (where this example is simply the default values):

(setf (ide:browser-keychords
        (cg:cgjs-options (ide:current-project)))
      '("F11" "Control+0" "Control+-" "Control+="
        "Control+Meta+F" "Meta+0" "Meta+-" "Meta+="))

browser-server-port

Returns either nil or a number for the port at which a web browser can connect to the CG application server. See the Project Manager option below for more information.

This CG/JS option is typically set with the Browser Server Port widget in the CG/JS tab of the Project Manager dialog in the IDE. But it could be set programmatically like this:

build-flags

Returns a list of keyword symbols indicating whether each of several boolean properties of the specified project is enabled. The valid keywords for the list are:

The setf of this function may be called to establish the set of build-flags for a project programmatically, but these values are usually viewed and set interactively on the Build tab and the Advanced tab of the Project Manager dialog instead. Note that not all checkboxes on those tabs correspond to build flags.

Here is a table that shows the Project Manager tab and widget label of the widget that corresponds to each build-flags keyword:

build-flags keyword	Tab	Widget label in the Project Manager	Effect
`:allow-runtime-debug`	Build	Enable Debugging of Runtime Errors	Causes the console window to be available in the standalone application for debugging until the application is ready to ship. See the section Enable Debugging of Runtime Errors on the page for Build tab of the Project Manager dialog for details.
`:allow-build-debug`	Build	Enable Debugging of Build Error	Allows interactive debugging of an error that occurs in the lisp that is generating the standalone application. Note that the build console may not close itself when this option is selected.
`:purify`	Advanced	Purify	Use the purify option
`:runtime-bundle`	Advanced	Deliver a Runtime Bundle	Include the runtime bundle (see Including all desired modules in delivery.html).
`:us-government-use`	Advanced	For US Government use	Causes an additional copyright notice (specifically for the United states Government) to be displayed.

Generally, if the check-box widget in the dialog is checked, then the associated keyword will be present in the build-flags list.

build-project

Arguments: project &key distribution-directory replace-if-exists exe-only autoload-warning completion-dialog (increment-build-number t) full-compile

Calls either build-lisp-image or generate-application, passing various properties of the project as arguments in order to build a standalone executable for the project. This is the programmatic equivalent of the File | Build Project Distribution and the File | Build Project Exe menu commands. This function also emulates certain other functionality of these IDE commands that is not provided by build-lisp-image or generate-application, such as embedding the project's icon file in the generated executable, and recompiling it with :runtime-system in the *features* list if the project's full-recompile-for-runtime-conditionalizations property is turned on. This function may be useful for automating the building of standalone executables for a project.

The Build tab and the Advanced tab of the Project Manager dialog allow you to specify additional arguments and other aspects of the project distribution build. There are also generic functions which can set these values, like additional-build-lisp-image-arguments.

Automating a Project Build Using the startup.cl File

Here's a technique to automate starting up an IDE, loading a project, generating a standalone distribution, and exiting: Place code similar to the following at the top of your startup.cl file. (If this file does not exist, simply create one. startup.cl is used here because it is loaded only after the IDE has finished coming up.) This particular example will make a distribution for the IDE's form-building tutorial.

(in-package :cg-user)

(when (member "build-tutorial" (sys:command-line-arguments
                                :application t)
              :test #'string-equal)
  (let* ((project (ide:load-project
                   (merge-pathnames
                    "gui-builder-tutorial/final/interface-builder-tutorial.lpr"
                    (translate-logical-pathname "sys:"))
                   :compile nil))
         (destination "c:/tutdist/"))
    (ide:build-project project
                   :distribution-directory destination
                   :replace-if-exists t))
  (exit))

The above code will run whenever "build-tutorial" is passed as an "application argument" in the command line that is used to start up lisp. ("Application arguments" are all those following a "--" in the command line.) Such a command line, which could either be placed in a .bat batch file to be double-clicked or be used in a Windows Start Menu command, could be as simple as this ("XX" means the version indicator, e.g. "acl81"):

To build your own projects this way, simply replace the pathnames and command-line argument name in the sample code above, or customize it further as desired. Multiple application arguments could even be used to build the distributions for a set of projects automatically.

If an automated build fails to complete: An automated build might fail to complete, leaving the build console window on the screen, if you have turned on the "Enable Debugging of Build Errors" option for the project at some time on the Build tab of the Project Manager dialog. If this happens, you could either turn that option back off in the Project Manager, or else make the build script ensure that the option is off during the automated build by adding a line of code like the following to the build script just before it calls build-project:

Automating a Project Build Using a Make File

If you use a make facility on your system, then you could use an alternate approach that employs a makefile and one or more script files for one or more projects. This approach allows typing a briefer command line to build a particular project.

Your makefile could have a simple rule for each project, where it starts the IDE and passes the name of a script file to load for that project:

Then the script file build-sample.cl could contain the following code that loads and builds the project.

One tricky point is that it must first wait until other processes have finished starting up the IDE. (That's not necessary when using the startup.cl approach because that file is loaded only after the IDE has finished starting up.)

(in-package :cg-user)

;;; Wait until other processes finish starting up the IDE.
(loop (when ide:*ide-is-running*
        (return))
      (sleep 0.1))

;; Load a project and generate its standalone application.
;; (You could load and build multiple projects here if desired.)
;; Using in-cg-process avoids problems if an error in this code
;; tries to display an error message in a CG window.
(in-cg-process ()
  (let* ((project-directory "c:\\allegro-projects\\sample-project\\"))
    (ide:build-project
     (ide:load-project (merge-pathnames "sample-project.lpr" project-directory))
     :distribution-directory (merge-pathnames "dist3" project-directory)
     :replace-if-exists t))
  
  ;; Exit the lisp automatically when the build is done.
  (exit))

Then in a Windows command window or Unix shell you can move to the directory that contains the makefile and simply enter make sample to build the standalone application for that project.

cg-tree-font

cgjs-logging

Returns a boolean value for whether the CG/JS server window will have a child window that displays logging information, such as whenever a user connects or disconnects. See the Project Manager option below for more information.

This CG/JS option is typically set with the Show CG/JS Logging Window widget in the CG/JS tab of the Project Manager dialog in the IDE. But it could be set programmatically like this:

class-graph-font

class-graph-initial-depth

Determines the number of levels that will initially be shown in a class graph when the Tools | Graph Subclasses or the Tools | Graph Superclasses command is used. The value may be either nil or a positive integer. nil means to show all descendant or ancestor classes; a positive integer means to show only the specified number of levels. A value of 1 would initially show only the specified class; a value of two would show the specified class along with its class-direct-subclasses or class-direct-superclasses.

If not all levels are shown initially, additional nodes may be opened by right-clicking individual leaf and root nodes and selecting "Include Children" or "Include Parents" from the shortcut menu. The graph does not indicate which nodes may have additional subclasses or superclasses, however, except in the IDE status-bar message when a node is selected.

close-current-project

This function closes the project that is currently being edited in the IDE. This project is the value returned by the function current-project, and was opened by either the File | Open Project command or the File | New Project command, or by calling open-project directly.

Closing the current project causes its forms and their running windows (if any) to be closed. If the project's .lpr project definition file is being edited in the IDE editor, this editor pane is closed as well. There will then no longer be a current project until another one is opened or created.

If you are no longer using the current project, then closing it may result in some IDE dialogs behaving more conveniently, such as not asking whether to add a new editor file to the current project, or not defaulting the file selection dialog to the project's directory. The Project Manager dialog's toolbar contains a button with a red X that calls close-current-project.

It is not necessary to explicitly close the current project before opening or creating another one, because the File | Open Project command and the File | New Project command automatically call it to clear the previous project out of the way.

close-inactive-listeners

Returns the value of the configuration property that determines whether an IDE listener (also called a debug pane) will be closed automatically when it becomes inactive.

A listener typically becomes inactive when it is created to debug an error in a thread that does not normally have a listener, and then the process is aborted or continued from the error. In these cases, the process has either been killed or is no longer in a read-eval-print loop, and so the listener cannot function.

The default value of this property is nil, so that the user can still reference the information that was printed into the listener while it was active. An inactive listener will have the word "(inactive)" in its tab at the top of the Debug Window, and it will be grayed to indicate that it is not currently available for interaction. If a later error in the same thread is debugged, the listener will be reactivated.

There is a disadvantage to having this property turned off (that is, value nil). A lot of listeners can accumulate in the Debug Window for processes that have been killed, requiring the user to use the File | Close Pane command to get rid of the excess panes. If this becomes annoying, the property can be turned on to automatically close the listener panes whenever they become inactive.

This property can be found on the IDE 2 tab of the Options dialog, or (as with all configuration options) via the Tools menu | Inspect System Data | IDE Configuration Options command.

close-project-close-editor-buffers

Returns whether closing the current project will automatically close any unmodified editor buffers that are displaying files of the project. Note that the current project is closed automatically whenever a new project is created or an existing project is opened.

The default value is nil, since it may be disconcerting if editor buffers disappear unexpectedly, but turning this option on can be useful for automatically clearing away editor buffers that are not in current use. An editor buffer that has unsaved changes is not closed in either case.

This option appears on the Project tab of the Options dialog (displayed with Tools menu | Options), and may also be set by calling the setf of this function.

Example

code-file-pretty-print-columns

Returns the width (number of columns) used by a configuration when printing code files. The argument (configuration *ide-system*) (see configuration and *ide-system*) returns the value currently in effect. code-file-pretty-print-columns is a property of the configuration class.

comment-indent

Returns the value of the comment-indent property of configuration. The current development configuration is the value of (configuration *ide-system*) (See configuration and *ide-system*.) In the :host editor mode, the Control-; gesture inserts a semicolon at the comment-indent column and places the text cursor after the semicolon.

compilation-unit

Returns the value of the compilation-unit property of project. When true (the initial value), project compilation is performed inside a with-compilation-unit macro.

The setf of this function could be used to programmatically set the value of this property, though typically you would set set it interactively with the Verbose Compile and Load check-box on the Options tab of the Project Manager dialog.

compile-files-as-utf8

If the value of this IDE configuration option is true, then compiling a project or using one of the file compiling and loading functions on the File menu (except when in the editor) will pass :utf8 as the external-format argument to compile-file or load. Otherwise :default will be passed.

This variable has no effect when using the File menu commands on an editor buffer, or when doing an incremental compilation in the editor. In those cases, the external format that was determined for the file when loading it into the editor will be used for compilation. (That may depend on the value of the load-utf8-if-no-bom option. See also external-format-for-saved-files.)

This variable has no effect if :utf8 is the default external format in the current environment.

The initial value is nil, for backward compatibility with source code that conatins Latin1 characters, though switching to UTF8 would allow characters of any language in source code, including characters of multiple languages in the same application.

This option appears as a check box widget on the IDE 2 tab of Options dialog, displayed by Tools menu | Options.

compile-project

Compiles any source code files of the specified project that do not have up-to-date fasl files, and loads all of the fasl files. Returns true if the project was successfully compiled and loaded, and nil otherwise. This function is called by the Tools | Compile Project command.

comtab-report

Arguments: &key (stream *terminal-io*) (comtab-list (list *text-edit-comtab*)) (max-column-width 40) (include-menu-bar t) (include-global t) include-help-strings extra-help-string-spacing

Generates a table of all keyboard shortcuts used by the IDE, including menubar shortcuts, comtabs, and global accelerators. If stream is nil, then the report is shown in a list-view control in a dialog (this is what the Help menu | Shortcut Keys command does). If stream is a stream, then a textual version of the report is printed to the stream. The default value of stream is the current value of *terminal-io*, which typically will print the output to a listener window.

Arguments other than stream

concatenate-project-fasls

Returns the value of the concatenate-project-fasls property of a project, such as the current-project. The value may be set by calling the setf of this function, though typically you would set the value interactively using the Concatenate Project Fasls check box on the Options tab of the Project Manager

confirm-exit

Returns a boolean value for whether the web browser will prompt the user for exit confirmation when they try to close the web browser tab for the CG/JS application or reload the web page.

This CG/JS option is typically set with the Confirm Exit widget in the CG/JS tab of the Project Manager dialog in the IDE. But it could be set programmatically like this:

context-sensitive-default-path

Returns the value of the context-sensitive-default-path property of configuration. The current development configuration is the value of (configuration *ide-system*) (see configuration and *ide-system*).

Whenever ask-user-for-new-pathname or ask-user-for-existing-pathname is called without passing an initial directory as the value of the host argument, then this property determines how the initial directory to display in the standard file selection dialog is chosen. If (1) this property is true and (2) a pathname is returned when the function file is called on the window that was passed as the stream argument, then the directory of that pathname is used. Otherwise the directory of the file that was most recently selected from the file selection dialog is used. The IDE editor is presently the only window for which file normally returns a pathname. So by default the directory displayed in the file selection dialog is sticky (that is, the most recent value is used) except in the editor, where it defaults to the directory of the file in the selected buffer. Turning this property off makes the file selection dialog sticky everywhere.

Note that the file selection dialog is also used by various IDE commands such as Open and Open Project (on the File menu). Most of these commands do not specify a host argument, and so this property affects these IDE commands.

context-sensitive-default-path is a property of the ide-configuration class.

current-project

Returns the project that is currently being edited in the IDE. This project was opened by either the File | Open Project command or the File | New Project command, or by calling open-project directly.

There is at most a single current project at any time, and opening a project causes the previous current project, if any, to be closed. See close-current-project. If there is no project open, current-project returns nil.

debug-font

Returns the font that's used in the lisp listeners of the Debug Window. The setf of this function could be called to set the value, though typically you would set it on the Fonts tab of the Options dialog.

debug-history-limit

Returns (or sets with setf) the maximum number of recent evaluations that will be kept in the Debug Window's history list for possible re-evaluation later. When the list has more items than this maximum, older items are pushed off the bottom.

default-command-line-arguments

Returns a string indicating the command-line arguments that will be embedded in the resources area of the standalone executable that is generated for the specified project. This allows various command line options to be used when the user double-clicks the .exe file in the File Explorer, for example, as opposed to selecting a Start Menu item or shortcut that specifies the command-line arguments itself.

This project property is normally specified by entering it into the Command Line Args widget on the Advanced tab in the Project Manager dialog dialog (or perhaps by editing the .lpr project definition file of the project). NOTE: When entering a default-command-line-arguments string into the Project Manager widget for it, do not include quote marks around the string.

Example: If the string is +c -- +option3, then double-clicking the .exe file that you generate for the project will start up the application with the +c option to not create a console window. And calling command-line-arguments in the running standalone application will return a list that includes the string +option3.

default-http-proxy

Returns the value of the default-http-proxy property of ide-configuration. The current IDE configuration is the value of (configuration *ide-system*); (see configuration and *ide-system*).

This property can be used for downloading patches if your site requires an HTTP proxy. The value is typically specified in the Download Patches dialog, in the four HTTP Proxy widgets in the lower right corner, just before using the dialog to download patches. It could also be set by calling (setf default-http-proxy).

The value is a list of four values for the proxy host name, port number, username, and password. Each element may be either a string or else nil to not specify a value.

The Download Patches dialog will never store the password, always leaving the fourth element as nil, for security reasons. It is highly recommended that this element never be set programmatically either, since this configuration option is saved with all of the others in the IDE's preferences file. The fourth element exists for a possible enhancement where it could hold an encrypted version of the password.

define-project

Creates a project object as specified by the arguments. (Not usually called by programmers. The call to this function is generated by the project manager.)

The functionality associated with this symbol is IDE functionality. It is named by a symbol in the cg package for technical reasons. This function should not be called in any application as it will likely not work except when the IDE is present.

dialog-print-array

This user option determines the value to which *print-array* will be bound when the IDE is printing arbitrary Lisp values into widgets in various tool dialogs. The default is nil to avoid using too much of the limited space in widgets for arrays, and possibly to avoid delays while printing huge arrays; but you might want to set it to true to see some elements of arrays. See the related option dialog-print-level for more information.

dialog-print-circle

This user option determines the value to which *print-circle* will be bound when the IDE is printing arbitrary Lisp values into widgets in various tool dialogs. See the related option dialog-print-level for more information.

dialog-print-length

This user option determines the value to which *print-length* will be bound when the IDE is printing arbitrary lisp values into widgets in various tool dialogs. See the related option dialog-print-level for more information.

dialog-print-level

This is one of a series of operators which determine the values of various printer variables for use on IDE dialogs. All values can be set on the IDE 2 tab of the Tools | Options. This operator determines the value of *print-level*. Other operators include dialog-print-length (*print-length*), dialog-print-circle (*print-circle*), and dialog-print-array (*print-array*). The general description on this page applies to all the operators (replacing -level appropriately) and so pages describing those operators simply link here.

This user option determines the value to which *print-level* will be bound when the IDE is printing arbitrary Lisp values into widgets in various tool dialogs. The affected dialogs include the backtrace pane (which appears when you elect to debug an error that is signaled), the listener's drop-down history, the Inspect dialog, Trace dialog, and some widgets in the Stepper dialog.

Typically you would modify this option interactively on the IDE 2 tab of the Tools | Options dialog, though you could also set it programmatically with a form like this one:

A small value is typically desirable because it usually affects how values are displayed on a single line in a widget where there's not a lot of room. To see a longer representation, you could for example use Tools | Return Selected Object to return a selected value to the listener, where it will be printed using the value of tpl:print-level and associated variables in the top-level package. Or use Tools | Inspect Selected Object to see more information about the selected value in the inspector.

It is likely a bad idea to set this variable to nil, and likewise for dialog-print-length and dialog-print-circle, due to delays that could occur if arbitrary lists that the IDE encounters are circular or deeply nested or extremely long. You might set it temporarily to nil, though, if needed for a specific purpose.

disallow-running-in-non-default-mode

Returns a boolean value for whether an application that is built to run in web browser mode by default will be prevented from being run in desktop mode with a command line argument, or vice versa. See the Project Manager option below for more information.

display-form-grid

Returns whether a grid of dots is displayed on any form window that's used for interactively arranging widgets for a dialog in a project. The grid may help with aligning widgets with each other more accurately.

The setf of this function could be called to set the value, though typically you would set it interactively on the Form tab of the Options dialog.

display-status-bar

Returns whether the IDE's status bar is currently present at the bottom of the IDE. The setf of this function can be called to show it or hide it, though typically you would toggle it interactively on the View menu.

display-toolbars

Returns whether the IDE's main toolbars are currently present, just below the menu bar at the top of the IDE. The setf of this function can be called to show them or hide them, though typically you would toggle them interactively on the View menu.

The toolbar commands are all also in the menu bar, so you could save some space by turning off the toolbars and using the menu commands instead.

distributed-files

Returns or sets with setf the list of distributed files in a project. These files will be copied to the distribution directory when a distribution is created from the project (with the File | Build Project Distribution command), but they will not be loaded into the built image nor will any attempt be made to compile them (so they need not even be Lisp source files). See the description of the Project Manager dialog.

Each element of the list should be a path namestring. If a namestring names a directory rather than a file, then that directory along with its entire contents will be copied to the project's distribution directory.

The setf of this function could be called to set the list of namestrings programmatically, but typically you would instead select the files and directories with the New File button at the left end of the Project Manager dialog, specifying either distributed file or distributed directory as the type of module to add to the project.

distribution-directories

Returns an association list that maps project names to the directories that were most recently specified for their standalone distributions when using the File | Build Project Distribution command. This list is saved in the allegro-ide-options.cl file along with the other configuration options, and is used to determine the default directory when File | Build Project Distribution is used again.

This list is normally managed internally, but it may be useful to modify it explicitly to change the default distribution directories for a set of projects. The setf of this function may be called to set the value. The format of the list is

where a project-name is a symbol and a directory-pathname is a pathname. For example:

editable-files

Returns the list of editable files of a project. An editable file is a file that is neither compiled and loaded (like a source code module or form module) nor distributed with the project's standalone application (like a distributed file or directory), but which may nevertheless be searched and edited as part of the project. A to-do or readme text file might be handy as an editable file, for example.

Specifically, an editable file is listed on the Modules tab of the Project Manager so that you can invoke the IDE Editor on it from there, and the Find In Files dialog will search the file whenever it is searching the current project.

The setf of this function could be used to establish the list of editable files, but typically you would add the files using the Add File button at the left end of the Project Manager's toolbar.

A source code file whose file type is txt will actually be treated as an editable file (mostly for backward compatibility).

editor-font

The behavior of this function depends on the optional argument. If default is nil, this function returns the current value of the editor-font property of configuration. The current development configuration is the value of (configuration *ide-system*) (See configuration and *ide-system*.) If default is specified true, a hard-coded default font is returned regardless of the current value of the property.

editor-mode

Returns the editor-mode of development-configuration. The currently in force configuration is the value of (configuration *ide-system*) (See configuration and *ide-system*.)

The editor-mode specifies which set of editor keystroke definitions (that is, which comtab) to use in the editor and debug-window. Allegro provides three sets of keystroke mappings either to follow Windows conventions (:host), to provide basic emacs commands (:emacs), or to provide a minimalist command set (:brief). The editor-mode may be selected on the Editor tab of the Options dialog. The variable *text-edit-comtab* holds the comtab that defines the commands for the current editor-mode, as well as any additional commands that you may have been added explicitly.

A drawback of :emacs mode is that many of the menubar shortcuts are removed due to conflicts. Emacs enthusiasts may prefer the emacs-lisp interface to the real emacs editor for heavy-duty editing, while staying in :host mode in the windowized environment to maximize the number of keyboard shortcuts.

editor-string-search-lines-of-padding

This IDE configuration option specifies the number of text lines that are scrolled into view both above and below a string match in the IDE's editor when a string search is done. This affects commands on the Search menu such as Find Forward and Search | Replace, and allows the user to see additional context around the string match. The default value is 6.

This option can be found on the Editor tab of the Options dialog, and may be modified programmatically with a form such as this one:

eval-in-listener-thread

Evaluates an arbitrary lisp form in either an IDE listener thread or the IDE GUI thread. Optionally waits for the evaluation to complete, returning the result of the evaluation. This function may be useful when customizing the IDE if it is necessary to evaluate a form in a thread other than what the IDE would use by default.

The IDE creates its tool windows in the IDE GUI thread, and runs the code for those windows in that thread. On the other hand, user code that is evaluated in an IDE Listener or with the Tools menu | Graph Subclasses and Tools menu | Incremental Evaluation command is run in an IDE Listener thread. This multi-threaded design allows IDE tool windows to respond while an evaluation of user code is still busy. In certain cases, this may result in code being run in an inappropriate thread. For example, if you define a global keyboard accelerator (see add-global-keyboard-accelerator) and use it in an IDE tool window, then its code will run in the IDE GUI thread that created that window. If that code should instead run in an IDE Listener thread in order to run in the same environment as other user code, then this can be achieved by calling eval-in-listener-thread in the global keyboard accelerator code.

form is the Lisp form to be evaluated. Note that because this argument is evaluated by the reader (as are all arguments to functions), the value of form should evaluate to the Lisp form to be evaluated. This is done in the examples below by quoting the desired form.

If wait is true, then eval-in-listener-thread does not return until the specified thread has finished the evaluation, at which time eval-in-listener-thread returns the values that were returned by calling eval on form.

If wait is nil (the default), then eval-in-listener-thread returns immediately after posting a notification to the specified thread, and the returned value is undefined. An exception is that if the specified listener indicates the current thread, then eval is called on form directly, and so eval-in-listener-thread does not return until the evaluation is done even if wait is nil.

listener indicates the thread in which the evaluation will be done. It must be either :selected (the default), :initial, or :gui. :selected means to evaluate the form in the thread of the IDE listener pane that is currently selected in the Debug Window. This is the same thread in which forms that are typed into the Debug Window are evaluated, and the thread in which IDE commands such as "Tools | Incremental Eval" and "File | Load" evaluate user code. :initial means to evaluate the form in the thread of the "Listener 1" listener, which is always present in the IDE (it cannot be closed except by exiting the IDE). :gui means to evaluate the form in the "IDE GUI" thread, which is not a listener thread at all but rather a special IDE thread that handles mouse and keyboard events in IDE windows. It is probably not usually appropriate for user code to be evaluated in the IDE GUI thread, except for IDE customizations that manipulate IDE windows (which are created in the IDE GUI thread).

If funcall is true, form is passed to funcall rather than to eval. form must then be a suitable argument to funcall and will be passed with no arguments.

If trap-errors is true, then any errors that are signaled are ignored. If wait is also true and an error is signaled, then eval-in-listener-thread will return two values: (1) the keyword symbol :eval-in-listener-thread-error and (2) the error condition.

Note that this function is useful only in the IDE, rather than in standalone CG applications. The IDE creates a particular set of threads and has conventions for which thread to use for particular tasks. These conventions may not be suitable for some IDE customizations, and so this function is provided to avoid any such problems. A standalone CG app that uses multiple threads, on the other hand, must handle its own thread management.

Examples:

(ide:eval-in-listener-thread
  '(mp:process-name sys:*current-process*)
  :wait t :listener :initial)
==> "Listener 1"

(ide:eval-in-listener-thread
  '(mp:process-name sys:*current-process*)
  :wait t :listener :gui)
==> "IDE GUI"

exit-ide

Exits the IDE without exiting lisp. The IDE's windows will be closed and the IDE's processes will exit.

start-ide could later be called to run the IDE again in the same lisp session. But it would not work to run the IDE one time in Windows desktop mode, and another time in CG/JS mode (by passing a :run-in-web-browser argument to start-ide).

exit-server-on-client-exit

Returns a boolean value for whether the CG/JS application server will exit automatically whenever the last client has disconnected. See the Project Manager option below for more information.

exit-tests

Returns the value of the exit-tests property of ide-system, where ide-system is the current value of *ide-system*.

The value is a list of the names of functions that are called when a gesture is made to exit the IDE. If any function returns nil, then the exit is canceled and the remaining functions are not called. Otherwise (when all functions return true) the IDE proceeds to exit (and the entire Lisp exits as well).

A function in the initial list returns nil if the user cancels out of the dialog asking whether to first save unsaved files, for example.

The setf of this function sets the value. You should not remove any of the function names that are in the list initially, but may push additional function names onto the list. Each function should take no arguments, and return nil only if it decides to prevent the IDE from exiting.

fanatical-followers

Returns a list of the dialog-items that will delete themselves whenever the dialog-item specified by the component argument is deleted from a form. Probably of interest only to programmers who design their own lisp-widgets, who may want to add a fanatical-followers method.

The built-in methods are the same as for followers (the controls on a tab-control, the up-down-control that is the buddy-widget of a single-line editable-text control, the set of controls that lie within a group-box), except that a group-box's followers are not also fanatical-followers.

file-dialog-source-types

This option has been deprecated and is no longer used. It has been replaced by the simpler option ide:source-file-types.

This configuration option determines what types of files are listed in the file-selection dialog when the IDE requests a lisp source code file. Specifically, when the File | Open, the File | Save, or the File | Compile command on is invoked, the value returned by this function is passed as the allowed-types argument to ask-user-for-existing-pathname or ask-user-for-new-pathname. (For the Save command, this applies only in the editor.)

The setf of this function may be called to set the value of this option, or use the Tools menu | Inspect System Data | IDE Configuration Options menu command. For example, if you would like text files to be listed along with lisp source code files when using the File | Open command, the following call would make that happen:

(setf (file-dialog-source-types (configuration *ide-system*))
  '(("Lisp files" . "*.cl;*.lsp;*.lisp;*.jil;*.txt")
    ("All files" . "*.*")))

find-again-after-replace

Returns the value of the find-again-after-replace property of configuration. The current development configuration is the value of (configuration *ide-system*) (See configuration and *ide-system*.)

If this configuration property is turned on, then whenever the user does a replace operation in the in-lisp editor, the cursor will immediately be moved to the next occurrence of the find string (if there is one). This allows the user to see the next occurrence that they may want to change, without doing a separate find-again command. On the other hand, if only a single change is desired, then the cursor may annoyingly be moved to some arbitrary position later in the editor window after the single replace is done. This property may be turned off to avoid that behavior, in which case the cursor will remain at the replaced text after each replace operation.

find-ide-window

Returns an IDE tool window from its name. This may be useful if you are extending the IDE by operating on its windows programmatically, though we do not document how to do that.

name should be the symbol that names the topmost window of some IDE dialog. This name could be discovered by using the IDE's Tools menu | Get Component command and clicking on the title-bar of the IDE dialog, then calling name on the returned window.

find-in-files-file-list-portion

This IDE configuration option is used internally to maintain the proportion between the heights of the two lower widgets in the Find In Files dialog, which list the files that have matches followed by the matching lines in the selected file. It causes the two widgets to maintain the same relative heights across multiple IDE sessions and when the user resizes the dialog. Dragging the split-bar between the widgets changes the proportion.

This symbol is exported mostly to follow the general rule where all configuration options are exported, though there is typically no need to modify the value explicitly. If modified, the value of should be a real number between 0.0 and 1.0, indicating the portion of the total height of the two widgets that will be used for the height of the upper widget.

find-in-files-search-subprojects-later

This user option controls whether the Search Subprojects Later checkbox on the Find In Files dialog is initially checked when the dialog is first shown in an IDE session. The default value is true. The existence of this option simply lets you avoid remembering to check or uncheck that widget in each IDE session.

This option does not appear on the Options dialog, but it can be toggled by simply clicking the Search Subprojects Later check box on the dialog and saving the options to the options file, either at once of when the IDE is exited, assuming options are saved on exit. See The user options file allegro-ide-options.cl for information on the options file.

find-in-files-show-html-files-in-browser

This IDE configuration option is used when a search in the Find In Files dialog searches any files of type .htm, .html, or .shtml and finds matches in any of those files. When this option is enabled, as it is by default, then opening a matching HTML file will show the file in an HTML browser rather than in the IDE's editor. (The option use-cg-html-browser determines whether that will be done in the IDE's own HTML help window or in your preferred third-party web browser.)

If you would like to edit HTML files in the IDE's editor, then you may want to turn this option off. This option does not appear on the IDE's Options dialog, but you can turn it off programmatically with this expression:

find-module

Returns the module of project with name name. Modules in a project correspond to the forms being designed. Their names are typically keywords like :form6 and (after the programmer has supplied a better name by modifying the name property) :curve-dialog. Certain functions, such as finder-function and maker-function, operate on module objects. See also modules.

find-project

Returns a project that has been loaded into the current lisp session by load-project or open-project, if one can be found from the specified object. object may be either the name of the project, the pathname of the .lpr project definition file, or a module of the project.

find-required-modules

This function returns a list of Common Graphics modules that must be included in a standalone application that is generated either for the current project or for an arbitrary set of source code files. It determines the required modules based on the home packages of the exported Common Graphics symbols that are found in the application files.

If files-to-search is nil, find-required-modules searches all of the source code files of the current project.

If files-to-search is non-nil, then it should be a list of files to search. That list of files is then searched instead of the current project's files. This can be useful to find the required Common Graphics modules of an application that does not use the IDE's project system.

The Find Required CG Modules button on the Project Manager Include Tab of the Project Manager dialog calls this function with files-to-search being nil.

find-window-configuration

Returns a plist of properties for window that has been saved into the allegro-ide-options.cl options file. If no properties have been saved for window, then nil is returned. At this time, only the exterior of each standard IDE window is included. When the allegro-ide-options.cl file is saved, the exterior of each IDE window is saved if the window exists, it is not iconized or maximized, and the overridable generic function keep-configuration returns true for the window.

The information is still saved for windows that have been shrunk, which is the case for most IDE windows that have been "closed". See user-close and state.

finder-function

When an application window is designed in the IDE using a form, several functions associated with the form/window are defined in a .bil file. The .bil file is automatically generated, so it can be examined but should not be edited (as the edits will be lost when the file is next generated). One of the functions in the .bil file is the maker function, which creates the window, and the other is the finder function, which finds the window (returning it, after calling the maker function to create it if it is not already created). See IDE User Guide, Chapter 4: Projects for more discussion on this point.

This function returns the name (a symbol) of the finder function associated with the form/window named by module. maker-function returns the name (a symbol) of the maker function. maker-function and finder-function may be called only in the IDE, where the projects facility exists. Application code should instead directly call the functions that are returned by maker-function and/or finder-function, and you can determine the names of these functions based on a form's name, as described below. So there is usually no need to use these functions, though they may be useful in utility code that you might write for use in the IDE. A related function that may be called in a standalone application is main-window-maker.

module should be either a form window or the module associated with the form. You get the module object by calling find-module with argument the project containing the form and the form name. Form/window names are typically keywords. When a new form is displayed in the IDE, to be used to design an application window, its name is something like :form6. The programmer typically changes the name to something more meaningful for the application, such as :curve-dialog (to use an example from the tutorial).

The names of the finder function and the maker function are determined by the following rules:

The name of the finder function is a symbol with the same name as the form but in the package of the form (which is typically the same as the project package). See project-package-name and form-package-name.

Therefore, if the form is named :form6 and the package is my-package, the finder function is named my-package::form6. Assuming the project containing the form is the current project,

If the name of the form is :curve-dialog and the package is common-graphics-user, finder-function called with the :curve-dialog module object as an argument returns the symbol common-graphics-user::curve-dialog.

The name of the maker function is the finder function's name with make- prepended, my-package::make-form6 and common-graphics-user::make-curve-dialog in the examples above.

The finder function (whose name is returned by finder-function) returns a window that has already been created from the form if one exists, otherwise creating (by calling the maker function) the window and returning it. The maker function (whose name is returned by maker-function) always creates a new window and returns it.

The finder function takes no arguments, and always creates the window (when it does create one) as a non-owned top-level window with the properties that were specified at design time.

followers

Returns a list of the dialog-items that will move along with dialog-item whenever dialog-item is dragged on a form. Probably of interest only to programmers who design their own lisp-widgets, who may want to add a followers method.

In the default methods, the followers of a tab-control are the controls on all of its tabs; the followers of a single-line editable-text are the up-down-control for which it is a buddy-widget (if any); and the followers of a group-box are the set of dialog-items that lie completely within the group-box's box.

form-file

Returns the .bil file of module. That file contains information on how to construct the window associated with the form.

form-package-name

Returns either a keyword symbol naming the package that is used for source code that is auto-generated for the specified form, or nil to default to the project-package-name of the form's project. If all of the forms of a project should be in a single package, then it is better to use project-package-name than this function. The setf of this function may be called to set this value programmatically.

The package that is named either by form-package-name or project-package-name is used at the time that source code for a form is auto-generated. There are two cases of this: (1) Whenever a form is saved, the .bil file is generated in its entirety, and contains the finder-function and maker-function that an application may call to create the running window of a form. The names of these functions will be in the package that's in effect for the form when it was last saved. (2) The first time that you click in the inspector on the small button at the right side of an event-handler property for a widget that's on a form, a new .cl source code file for the form will be created to hold auto-generated skeleton code for a new event-handler function. This file will have an in-package expression at the top that uses the package that's currently in effect for the form. If this happens before you have set the form's package as you want, you can simply edit this in-package expression later.

A package mismatch may occur when changing a form's package if event-handler functions have already been defined for widgets on the form. The reason is that the references to the functions in the form's auto-generated .bil file will now be in the new package, though the definitions of the functions in the associated .cl file will still be in the old package. So it is generally a good idea when changing a form's package to also edit the .cl file so that it is in the same package. The .cl is loaded into an Editor buffer when you click the View Selected Code button on the Project Manager. (The change to the .cl is not done automatically because this file is not auto-generated as a whole, and so it may not be appropriate for any in-package forms in the file to automatically be modified.)

format-debug

This is a convenience function for printing debugging output to the currently-selected IDE listener. Its arguments are the same as the arguments to format except that there is no stream argument. (stream is the first required argument to format.)

full-compile-project

Compiles and loads all of the source code files of the specified project, even when their fasl files are already up-to-date. Returns true if the project was successfully compiled and loaded, and nil otherwise. This function is called by the Tools menu | Full Compile command.

If load-project-file is true, then the .lpr project definition file is first loaded (to update the project if that file has changed). Otherwise it is not loaded.

If there are compiler warnings and the show-dialog-on-compiler-warnings IDE configuration option is true, then a dialog will display the warnings. If the include-cancel-button argument is true, then this dialog will include a Cancel button in addition to the usual OK button. If the user presses the Cancel button (or the Escape key), then full-compile-project will return nil to indicate that the compilation is considered to have failed. This value can be used to decide whether to proceed with some further action, such as running the project.

full-recompile-for-runtime-conditionalizations

If this property is on, then when the File | Build Project Distribution command or the File | Build Project Exe command is used, the project will be fully recompiled just before creating the executable, with :runtime-system added to *features* during the compilation. This feature is needed only if the project source code contains #-runtime-system or #+runtime-system reader conditionalizations to make the application work somewhat differently in the IDE than it does as a standalone executable. This property is off by default, since it is expected that applications typically will not use such conditionalizations. When the property is on, a second full recompilation is done after building the executable, with :runtime-system no longer in *features*, so that the project ends up once again compiled correctly for running in the IDE. When the property is off, a "regular" compile is still done just before creating the executable file, to ensure that all fasl files are up-to-date. (A regular compile compiles all source code files that have been saved since they were last compiled.)

graph-child-windows

Displays a graph in a separate window of the children (actually, all descendants) of window. Returns nil.

grid-x-spacing

Returns the value of the grid-x-spacing property in development-configuration. The current development-configuration is the value of (configuration *ide-system*) (See configuration and *ide-system*.)

grid-y-spacing

Returns the value of the grid-y-spacing property in development-configuration. The current development-configuration is the value of (configuration *ide-system*) (See configuration and *ide-system*.)

handle-home-key-shortcuts-in-ide-outlines

Whether all of the outline widgets in the IDE will use the handle-home-key-shortcuts option to make the J and K keys move to the next or previous item, and the F and D keys open and close the current item. When true, this allows navigating an outline widget without reaching for the arrow keys. But it also conflicts with the ability to jump to an item by typing the first one or more of its characters, and so this option is off by default. In earlier releases this behavior was hard-wired on in the IDE.

handle-multiple-packages-in-buffer

This IDE configuration option specifies whether commands such as Tools menu | Incremental Compile and Tools menu | Incremental Evaluation will read source code in the correct package even when the editor buffer contains multiple in-package forms for different packages. This takes somewhat more time to locate the in-package form that is associated with an individual definition that is being compiled or evaluated, but is needed when a buffer uses multiple packages. The extra time may be substantial for a very large buffer.

The default value is true, so that the correct package is always used. If you usually edit very large files that each use only a single package, then you may want to set this option to nil to eliminate a delay with searching for multiple in-package forms.

This option can be found on the Editor tab of the Options dialog, and could be set programmatically with a form like this one:

highlight-selected-editor-tab

Returns whether the IDE editor will always highlight the tab of the currently-selected buffer. This IDE configuration option is enabled by default because otherwise the visual indication of the currently selected tab is rather subtle.

This option does not appear on the Options dialog, but it does appear in the list of all IDE configuration options that is shown in the inspector by the Tools menu | Inspect System Data | IDE Configuration Options menu command.

icon-file

Returns the file (as a pathname or path namestring) containing the application icon for a project.

When a standalone application is generated from the project with the File | Build Project Distribution command, the icon from the file will be displayed in various places when the standalone application is run (but not when the project is run in the IDE). These places include:

The value may also be nil, in which case the Franz bust icon (as seen in the IDE) will be used. Otherwise, the value should be the pathname or path namestring of a .ico icon file.

An icon file on Windows may contain multiple images, which typically are the same logical image at different sizes. Generally it is best if the file contains at least one 32 by 32 image for use in places like the alt-tab window, and at least one 16 by 16 image for use in places like window title bars, the taskbar, and the file manager. If the file contains only a large icon, then a smaller icon is derived from it automatically, but it typically does not look as nice as a separately designed small icon.

You may find that some icon files but not others will work as application icons, depending on the version of the underlying operating system. In particular, most icons that have a depth of 4 (that is, using 4 bits per pixel) that worked on Windows XP appear not to work on Windows Vista; you may need to use an icon with a depth of 8 instead.

The setf of this function may be used to specify a new icon file for a project programmatically, though this is typically done interactively on the Build tab of the Project Manager dialog instead.

ide-auto-font-changing

This IDE configuration option determines whether editor and listener panes will automatically switch to a different font when needed, especially for Asian-language characters. There is a check box widget for this option on the Editor tab of the Tools menu | Options dialog. See the Common Graphics function automatic-font-changing for more information.

ide-dual-fonts-for-languages

This IDE configuration option determines whether editor and listener panes will use two fonts to mix Asian and English characters (according to Microsoft). See the Common Graphics method dual-fonts-for-languages for more information.

ide-evaluator-listener

Returns the listener window for the "Listener 1" thread. This thread and listener always exist while the IDE is running. (Other listeners may be closed with the File | Close Pane command, but not this one.)

This window occupies one tab of the top-level tab-control on the single IDE Debug Window. The frame-child of this listener is the actual text control that may be printed to. For example, the following form, when run in any thread, should print to the "Listener 1" listener:

ide-exterior

This IDE configuration property is used only when the use-ide-parent-window option is turned on, as it is by default.

This value is an IDE configuration option so that it will be saved into the IDE's options file, and then restore the IDE to its previous size the next time it is run. You would normally not need to call this function programmatically yourself.

ide-html-history

Returns the list of URL and filename strings that are currently in the history drop-down widget of the IDE's Help Window.

This configuration property exists so that the list of recently-visited pages is saved into the IDE's options file and restored in subsequent IDE sessions. There is normally no need for a user to access this value programmatically.

ide-implementation-version

Returns as a string the version identifier of the currently running implementation of the Integrated Development Environment (IDE).

ide-inspect

Arguments: object &key new-window-p new-window-name tabs initial-tab existing-inspector-only no-expose-p not-if-same-object additional-objects initial-property on-the-screen

This function invokes the IDE's inspector to examine an arbitrary specified object.

Typically you do not need to call this function. Instead would use one of the commands Tools menu | Inspect Selected Object and Tools | Inspect Returned Object. Or you would call inspect in an IDE listener, which will invoke the IDE's inspector because this function (ide-inspect) is the value of inspect::*inspector-hook* in IDE processes.

But it might be useful to call this function directly for the options that its keyword arguments provide. It might also be useful to set the value of the (internal) global variable inspect::*inspector-hook* to this function in non-IDE processes where it is not already the value, to cause calls to inspect in those processes to invoke the IDE's inspector.

ide-inspect-standalone

This function simply calls ide-inspect, always passing the on-the-screen argument as true to use an inspector window that is independent of the IDE. Specifically, the owner of the inspector window will be the screen rather than the main IDE window.

This function could be called in a Lisp where the IDE is loaded but not running, to use the IDE's inspector by itself without showing the rest of the IDE. See ide-inspect for a description of the arguments that may be passed.

You could also bind or set the value of the (internal) global variable inspect::*inspector-hook* to the name of this function to cause any calls to inspect to invoke the IDE's inspector (though independent of the IDE).

ide-page-size

An IDE configuration option that specifies whether the main workspace area of the IDE is scrollable, and by how much if so. A scrollable workspace allows arranging the various IDE tool windows into an area that's larger than the screen, and then scrolling different subsets of the tools into view. The current ide-configuration is the value of (configuration *ide-system*) (See configuration and *ide-system*.)

The workspace scrollbars will exist only if the use-ide-parent-window option is true, because otherwise there is no single main IDE window to contain the scrollbars.

The value should be a list of two non-negative integers, where the first integer is the page-width of the IDE workspace window, and the second integer is the page-height. Each scrollbar will appear only if the corresponding integer in this list is greater than the interior size of the IDE workspace window in that direction.

The initial value is (0 0), and so the workspace scrollbars do not appear by default. The scrollbars could be enabled by evaluating a form similar to this one:

When the scrollbars are used, commands at the bottom of the View | Manage Windows submenu, such as Scroll IDE Down can be used to scroll the IDE workspace. Typically you would use the keyboard shortcuts for those commands.

ide-priority

This IDE configuration property determines the process-priority of the IDE GUI process. This is the process that handles user gestures in IDE tool windows. The default value 8 so that it is higher than other processes that default to a priority of zero. This makes the IDE responsive to user gestures while user code is actively running in an IDE Listener process.

A higher priority for the IDE GUI process can make other applications less responsive in some cases. For example, music playback may not work smoothly during a dragging operation in the IDE on Windows, such as when dragging widgets on forms. If this is a problem, and you don't need to use IDE tool windows during long-running evaluations of user code, then you could set this value to zero.

The menu command Run | Prioritize IDE Response toggles this value between 8 and 0, where the priority is 8 when the menu item is checked. You can also change the value programmatically with a form such as this one (See configuration and *ide-system*):

ide-prompt

Returns the value of the prompt property of configuration. The current development configuration is the value of (configuration *ide-system*) (see configuration and *ide-system*).

ignore-package-name-case

The configuration option ignore-package-name-case no longer has any effect. Currently it simply does nothing (for compatibility with allegro-ide-options.cl options files that were written before release 7.0), but this function likely will go away in a future release. This function used to set the value of *ignore-package-name-case*. Now that value should be set directly.

in-break

Returns true if process is in a break level (i.e. has had a call to break, either directly or because of an error, which has not been cleared).

include-dead-locals-in-backtraces

Returns (or sets with setf) whether backtraces will show the values of local variables that are dead. The default value is nil because dead local variables are typically not of interest. This option is not on the Options dialog, but it could be set interactively with Tools menu | Inspect System Data | IDE Configuration Options, or set programmatically like this:

The values of dead locals will probably be interesting only if you first say (excl::set-process-debug [some-process] t) on the process that breaks, and then run the test that breaks. Otherwise the garbage collector will turn dead locals into non-lisp objects.

include-flags

Returns a list of keyword symbols indicating certain arguments that will be passed to either generate-application or build-lisp-image when the File | Build Project Exe or File | Build Project Distribution command is used to generate a standalone application for the specified project. The list may contain any combination of the symbols (:top-level :debugger :compiler :local-name-info). The default value is (:top-level :debugger).

The setf of this function may be called to establish the set of flags programmatically, but typically these values are set interactively on the Include tab of the Project Manager dialog instead, which has an individual check-box for each of the possible values, labeled Include the Top Level (for :top-level), Include the Debugger (for :debugger), Include the Compiler (for :compiler), and Save Local Name Info (for :local-name-info).

When :compiler is included in the list and the runtime-build-option property of the project is :dynamic or :partners (rather than :standard, which is the default), then the :discard-compiler argument to generate-application is passed as nil to include the compiler in the standalone application. (The appropriate Allegro license is required for this.) When :compiler is excluded from the list or when the runtime-build-option property of the project is :standard, the :discard-compiler argument is passed as t.

When :local-name-info is included, the :discard-local-name-info argument to generate-application or build-lisp-image will be nil, and otherwise will be t. When :top-level is included, the :include-tpl argument will be t, and otherwise will be nil.

include-local-variables-in-backtraces

An IDE user option that controls whether backtraces in the debugger will show local variables, in addition to the function arguments that are always shown.

Typically you would toggle this option by pressing the button for it in the toolbar at the top of a backtrace pane. The button has an uppercase L on it, and appears depressed when the option is on.

Alternately you can set the value programmatically, such as with this form that would turn the option on:

When you "open" the item for a function call in a backtrace by clicking its arrow icon on the left (or pressing the right arrow key), only the arguments that were passed to the function will be shown when this option is off. When it is on, the local variables (mostly from let bindings) are also shown after the arguments.

This option if off by default, though prior to release 10.0 local variables were always shown.

include-manifest-file-for-visual-styles

Returns true if the generated application for the specified project will have the newer "Visual Styles" look and feel on the Microsoft Windows platform; otherwise nil is returned. The value may be set by calling (setf include-manifest-file-for-visual-styles) or by using the check-box for this project property on the Build tab of the Project Manager dialog. (The illustration on that page uses a new visual style.) The default value is t. This property is ignored on platforms other than Microsoft Windows.

If the value is true, then the application will use the look and feel of the theme that the end user has selected in Windows Control Panel | Display | Themes. If nil, the "Windows Classic" look and feel will always be used. (The end user can also disable Visual Styles for all applications by selecting "Windows Classic" in the list of themes in Control Panel.)

This option is implemented by distributing a "manifest file" with the application. This file will have a name like "foo.exe.manifest" for an application name foo, and its XML contents tell the operating system that it's OK to enable the newer Windows look and feel.

Visual Styles are enabled by default for the IDE as well. To disable this feature for the IDE, rename the file allegro.exe.manifest in the main Allegro directory to something else and restart the IDE.

A note about button widget background color: When Visual Styles are used, a button widget's background-color property is used in a thin area just around the visible border, especially at the rounded corners. This property generally should be t so that this small area is drawn in the same color as the widget's parent window or tab-control, to make the color match. The default background-color for button is now t, but in the past (when the color was never used) it was nil. The background-color property of a button that was added to a form window before version 8.1 will therefore probably still have a background-color of nil, and the small border area will be drawn in white. To ensure that the color matches the parent background, change the property value to t.

include-modules-for-cgjs-logging

Returns a boolean value for whether the generated application should always include Common Graphics code modules that are needed when the CG/JS server uses a logging window. See the Project Manager option below for more information.

include-modules-for-starting-local-client

Returns a boolean value for whether the generated application should always include Common Graphics code modules that are needed when the CG/JS server automatially starts a local client. See the Project Manager option below for more information.

incremental-search

Returns the value of the incremental-search property of configuration. The current development configuration is the value of (configuration *ide-system*) (see configuration and *ide-system*). This property determines whether to use an emacs-like string search that does not pop up a dialog. Applicable to text windows only.

In the host editor mode when incremental-search is turned on, control-F will initiate a search similar to control-S in emacs, where you may begin typing a search string which will be located after each character is typed. The backspace key may be used to back up to previously-found substrings within a given search. Control-G will do a find-again similar to pressing control-S twice in emacs. The search direction must be set independently rather than using a separate command like control-R in emacs to search in reverse.

initial-package

This configuration option determines the initial current package of IDE Listeners. More specifically, initial-package returns a symbol whose symbol-name is the name (or a nickname) of the package that will initially be the value of *package* in any IDE Listener processes that are subsequently created.

(setf initial-package) may be called to establish the package to be used in the future (with a form like (setf (initial-package (configuration *ide-system*)) :mypackage), replacing :mypackage with a keyword naming the package you want), or the value may be set interactively in the list of all configuration options displayed by the Tools menu | Inspect System Data command. The value must be a symbol (not a package object); a keyword is recommended.

The default value is :cg-user, for the common-graphics-user package. IDE Listeners are in this package by default instead of the more traditional common-lisp-user package. The cg-user package is similar to the cl-user package, but additionally uses the common-graphics package so that Common Graphics code in that package does not have to qualify exported Common Graphics symbols.

When the allegro-ide-options.cl options file is loaded at IDE startup time, the value of this option is restored before any IDE Listener processes are created. Therefore, initial-package may be set in any IDE session to establish the initial current package of all IDE Listeners in future IDE sessions. If you would rather start in the common-lisp-user package, for example, then set initial-package to :common-lisp-user (or :cl-user).

If no package with the specified name is found when (setf initial-package) is called, a new "empty" package with that name is created at that time. At IDE startup time, the package could be more fully defined later in the startup.cl file or in the source code of a project that is being initially loaded. This allows the "Listener 1" process to start up in the desired package and then to load application code that fully defines the package.

The current development configuration is the value of (configuration *ide-system*). (See configuration and *ide-system*.)

initial-search-directories

Returns (or sets with setf) the list of directories that will initially appear in the Find In Files drop-down list of search directory choices.

This property is used only when the Find In Files dialog is created, and will have no effect if setf'ed later. It is useful mostly for automatically restoring the search directory choices that were used in the previous Lisp session (or whenever configuration options were last saved).

inspector-name-font

inspector-number-of-hash-table-values

Returns (or sets with setf) the number of hash table keys and values that are shown in the IDE's inspector when inspecting any hash table. Those values that are shown directly on the top inspector page for a hash table are intended as samples that show the kind of keys and values that are in the table.

inspector-style

Returns the style of the inspector in configuration. The current development configuration is the value of (configuration *ide-system*) (see configuration and *ide-system*). The style affects how the left (name) side of an inspector pane looks and what action is required to inspect the value associated with the name. Possible values for the style include :single-click-with-underscore, :single-click-without-underscore, and :double-click. The meanings of these values are:

inspector-value-font

Returns the font used in development-configuration for values in an Inspector window. If default is supplied, it should be a font and that font will be used instead.

internally-loaded-files

This generic function returns a list of application source code files that the Project Manager's Find Required CG Modules button will search in addition to the official source code modules of the project. The default value is nil, but (setf internally-loaded-files) may be called to change the value.

This project property is useful for a project that loads some of its files in its own source code rather than having a project module for each file. This can be true of projects that use defsystem (see defsystem.html) or a custom system to manage and load its files; perhaps a system that was already being used for the application before an IDE project was created for it.

The Find Required CG Modules button searches each source code file that you have added as a project module. This is sufficient in the usual case where each source code file of an application is a project module. But if a project module contains source code that loads other lisp files that are not modules of the project, then Find Required CG Modules will not know about these files and therefore will not search them. This can cause needed CG modules to be excluded from the standalone application that is generated by File | Build Project Distribution. Adding the files to the project's internally-loaded-files will avoid that problem.

Each file in the list may be either a pathname or a path namestring, and may be either an absolute path or relative to the project directory. Find Required CG Modules will ignore any paths for which the file does not exist, rather than signaling an error, so care should be taken to specify the paths correctly.

Example

There is no widget on the Project Manager dialog for this property, but the value could be edited interactively in the inspector after pressing the Project Manager's Inspect Project button.

javascript-files-to-import

Returns a list of the name strings of JavaScript code files that CG will automatically import at run time. See the Project Manager option below for more information.

keep-configuration

Returns (or sets with setf) whether the position and size of window will be saved in the allegro-ide-options.cl file, so that when a window with the same name is created in a successive invocation of the lisp development environment it will be created at this former position and size. The default methods return true for most Allegro development environment windows.

libraries

Returns a list of library modules of project. libraries is a property of the project class.

limit-connections-to-same-machine

Returns a boolean value for whether a web browser will be able to connect to the CG/JS application server only if it's running on the same machine as the server. See the Project Manager option below for more information.

lisp-message

Print to the main status bar the message specified by the format string and arguments.

lisp-message-print-length

This user option determines the value to which *print-length* will be bound when the IDE is printing arbitrary lisp values to the status bar at the bottom of the IDE. See the related option lisp-message-print-level for more information.

lisp-message-print-level

This user option determines the value to which *print-level* will be bound when the IDE is printing arbitrary lisp values to the status bar at the bottom of the IDE. Specifically, it affects all calls to the exported function lisp-message, which the IDE itself uses for status bar messages.

Typically you would modify this option interactively on the IDE 2 tab of the Options dialog, where it is labeled Status Bar print-level. But you could also set it programmatically with a form like this one:

lisp-warning

Like lisp-message, prints to the Lisp status bar the message specified by the format string and arguments. Also beeps.

load-cg-source-file-info

Loads source file information for the Common Graphics and/or IDE source code, which allows the Find Definitions facility to locate particular CG or IDE definitions and display them in the editor. This may be useful when writing a Common Graphics application if you need to see exactly what CG itself is doing.

This function will work only if the CG and IDE source code has been obtained from Franz and installed at the standard location, which is in new src/cg/ and src/ide/ subdirectories of the main Allegro directory.

The system keyword argument may be either :cg to load only the CG source file info, :ide to load only the IDE source file info, or :all to load both. The default is :all. The IDE code is probably of less interest, because an application would normally never call IDE code.

If you use the Search | Find Definition (or Search | Quick Find Definition) command to edit a CG or IDE definition without first calling this function, then a dialog will appear that explains the situation. If you have already installed the CG/IDE source code, the dialog offers to call load-cg-source-file-info for you. After calling the function, you will need to do the Find Definitions command again to locate the source code.

load-ide-patches

You will not likely need to call this function because (1) the patches will be included in the IDE when you rebuild all images after downloading patches, and (2) doing a (require :ide) in a base lisp will call this function automatically at the end. But this function is exported in case there are any atypical situations in which it may be useful.

load-project

Loads all of the files of a project without making it the current project for editing. This may be useful for loading utility projects for use in the IDE while working on another project, or simply for running multiple projects in the IDE rather than making standalone executables from them. load-project can also be used in conjunction with build-project to programmatically generate the standalone application for a project, without the overhead of opening the project for development.

To further develop an existing project, call open-project instead (or, more typically, use the File | Open Project command).

If compile is true, then each source code file is first compiled unless it already has an up-to-date fasl file, and then the fasl file is loaded; if compile is nil, then source code files are loaded rather than fasl files.

A project may also be loaded interactively by using the File | Load command. Note that the .lpr file type may be selected from the drop-down list on the file selection dialog invoked by the File | Load command to make it easy to browse all project definition files. When a .lpr file is chosen with the File | Load command, load-project is called internally to load the project.

loaded

Returns true if the files associated with project have been loaded into Lisp. loaded is a property of the project class.

main-form

Returns (or sets with setf) the name of the function that is called to find or create the running window of the main form of a project (see finder-function). This form is run by the default on-initialization function, which is default-init-function. (The on-initialization function of a project is run when the Run | Run Project command is invoked or when a standalone application starts up.)

The main form may be specified in the IDE either interactively in the Main Form widget of the Options tab of the Project Manager dialog, or programmatically by calling (setf main-form). main-form will always return either (1) the finder-function of a form-module or (2) nil if the project has no main form (in which case a custom on-initialization function needs to be created for the project).

Note that no actual forms will exist in a running standalone application. But maker-function may still be called on the main-module or any other form-module to find the function for creating the module's running window. This may be useful in a custom on-initialization function.

main-ide-window

Returns the owner window of the various IDE tool windows. This window depends on whether the IDE is using a parent window or an owner window. See use-ide-parent-window.

main-module

Returns the main module of a project, which is the module whose form is run by the default on-initialization function, which is default-init-function. (The on-initialization function of a project is run when the Run | Run Project command is invoked or when a standalone application starts up.)

The main module may be specified in the IDE either interactively in the Main Form widget of the Options tab of the Project Manager dialog, or programmatically by calling (setf main-form)).
(main-module is not setf'able but if the main-form is changed, the main-module will be changed as well.)

main-module will always return either (1) a form-module or (2) nil if the project has no main form (in which case a custom on-initialization function needs to be created for the project).

maker-function

This function returns the name (a symbol) of the maker function associated with the form/window named by module. finder-function returns the name of the finder function. maker-function and finder-function may be called only in the IDE, where the projects facility exists. Application code should instead directly call the functions that are returned by maker-function and/or finder-function, and you can determine the names of these functions based on a form's name, as described below. So there is usually no need to use these functions, though they may be useful in utility code that you might write for use in the IDE. A related function that may be called in a standalone application is main-window-maker.

module should be the module associated with the form. You get the module object by calling find-module with arguments the project containing the form and the form name. Form/window names are typically keywords. When a new form is displayed in the IDE, to be used to design an application window, its name is something like :form6. The programmer typically changes the name to something more meaningful for the application, such as :curve-dialog (to use an example from the tutorial).

The names of the finder function and the maker function are determined by the following rules:

The name of the finder function is a symbol with the same name as the form but in the package of the project (more precisely, the package of the form, but that is typically the same as the project package). Therefore, if the form is named :form6 and the package is my-package, the finder function is named my-package::form6. Assuming the project containing the form is the current project,

If the name of the form is :curve-dialog and the package is common-graphics-user, then if finder-function is called with the :curve-dialog module as an argument, it returns the symbol common-graphics-user::curve-dialog.

The name of the maker function is the finder function's name with make- prepended, my-package::make-form6 and common-graphics-user::make-curve-dialog in the examples above.

The finder function takes no arguments, and always creates the window (when it does create one) as a non-owned top-level window with the properties that were specified at design time.

The maker function, on the other hand, has a number of keyword arguments that allow creation of the window as an owned or child window of any other window and with a custom position, size, name, title, and/or border. The names of the maker function's keyword arguments are owner, child-p, exterior, interior, name, title, and border. These arguments have the same meanings as they do with the function make-window. The interior argument is provided with a default value (the size of the interior of the form used to design the window). The exterior has no default value. The interior argument is provided with a default value (the size of the interior of the form used to design the window). The exterior has no default value.

If the arguments that are supplied with a maker-function are not adequate for creating the window in the desired way at run time (because the maker-function does not have all of the arguments of make-window), a solution is to change the state property of the form to :shrunk so that the window is not yet visible when it is created. Then at run time you can modify the window after calling the maker-function to create it, and then call (setf state) to set the window's state to :normal when it is ready to be seen.

max-clients

Returns a positive integer for the maximum number of clients that can connect to the running CG/JS server at the same time. See the Project Manager option below for more information.

This CG/JS option is typically set with the Max Clients widget in the CG/JS tab of the Project Manager dialog in the IDE. But it could be set programmatically like this:

maximize-ide

This IDE configuration property is used only when the use-ide-parent-window option is turned on, as it is by default.

Returns whether the IDE parent window (if used) is currently maximized. Calling (setf maximize-ide) will maximize or unmaximize the IDE parent window.

This value is a configuration option so that it will be saved into the IDE's options file, and then restore the IDE to its previous maximized or unmaximized state the next time it is run. You would normally not need to call this function or its setf programmatically yourself.

maximize-ide-background-window

Returns (or sets with setf) whether the optional IDE background window covers the whole screen when it is toggled on. If true, it will cover the whole screen; if nil, it will resize itself automatically as needed so that it always just contains all of the currently open IDE windows.

Interactively, the background window may be double-clicked to toggle this property. An item on the background window's right-click shortcut menu also toggles this property.

maximum-symbol-completion-choices

Returns (or sets with setf) the max number of symbol completion choices that will appear in a pop-up menu before a modal dialog is used instead. The default is 25, in which case there is a unique shortcut letter for each choice in the pop-up menu. (If there are more completions than this maximum, a dialog window rather than a menu is displayed.)

min-pixels-between-widgets

Returns the value of the min-pixels-between-widgets property of configuration. The current development configuration is the value of (configuration *ide-system*) (see configuration and *ide-system*). This property determines the minimum allowable distance between components on a dialog. It is ignored if the allow-component-overlap property is true.

module-p

Returns true if the argument is an instance of the module class; otherwise returns nil.

modules

Returns a list of all form and source modules in project. modules is a property of the project class.

move-ide-windows-on-screen-resize

If this option is true, and the use-ide-parent-window property is true, and the IDE is maximized, and then the screen size changes while the IDE is running, then the IDE will move and resize its tool windows for the new screen size. (Otherwise nothing is done.) Each window will be moved and resized to where it was when IDE options were most recently saved at the new screen resolution, if such a value has been saved, or else to the default position and size for the new resolution.

Even when this property is nil, starting up the IDE will still restore the IDE tool windows to where they were when options were saved at the current screen resolution, since the options file remembers a distinct set of locations for each screen resolution.

mozilla-library-path

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

new-project-create-form

Returns whether creating a new project will automatically also create an initial form module in the project. This option appears on the Project tab of the Options dialog (displayed with Tools menu | Options) as the check-box labeled Create a Form in the New Project group-box. The value may also be set by calling the setf of this function.

The initial value is nil because it is trivial to use the File | New Form command to create a form whenever desired, and also because the new form window (as well as the New Form dialog that first appears asking for the form name and class) may be an annoyance if no forms are desired in the new project initially. (A project may be used to write an application where all windows are created programmatically without using form windows, or even to write a batch application that uses no windows at all.)

Example

new-project-show-editor

Returns the value of the new-project-show-editor property in development-configuration. The current development configuration is the value of (configuration *ide-system*) (see configuration and *ide-system*).

This property determines whether creating a new project will cause the IDE's source code editor window to appear, with an empty buffer for beginning a new source code file. The default is true. The value of this property can be set on the Project tab of the Options dialog, using the Show Editor check-box in the New Project Action group.

new-project-show-form

This option is no longer used. Its value is ignored. It has been replaced by new-project-create-form, which determines whether a form should be created for a new project. This option is kept to preserve backward compatibility but new-project-create-form should be used to specify the desired behavior.

Returns the value of the new-project-show-form property in development-configuration. The current development configuration is the value of (configuration *ide-system*) (see configuration and *ide-system*).

In earlier versions, this property determined whether a new project (including the project created when Allegro CL started up) included an initial blank form. As said above, this option no longer does anything. It is replaced by new-project-create-form.

new-project-show-project-manager

This property determines whether creating a new project will cause the Project Manager dialog to appear. This includes the project that is created when Allegro starts up, so setting this property to nil will prevent the Project Manager dialog from appearing at startup time. (The initial value is t.) The value of this property can be set on the Project of the Options dialog.

new-space-size

Returns the value of the new-space-size property in project. This is new-space-size used by project when building an application. There is an entry on Advanced tab of the Project Manager for this value.

old-space-size

Returns the value of the old-space-size property in project. This is old-space size used by project when building an application. There is an entry on the Advanced tab of the Project Manager for this value.

on-initialization

on-initialization returns a symbol naming a function (of no arguments) that is called when the standalone application for the project is started up, or when the Run | Run Project command is invoked for the project in the IDE.

The function should first perform whatever initialization is necessary to present the initial interface to the end user. Then it can either return or perform the work of the application.

Typically, the on-initialization function should return the main window of the application. A main window should be the window with the property that closing it ends the application. When the on-initialization function returns a window, the system will enter an event-handling loop that exits when that window is closed, causing the application as a whole to exit.

When anything other than a window is returned, the application exits as soon as the on-initialization function returns. Thus, if there are no windows in the application, then the on-initialization function should run everything that the application is intended to perform before it returns.

In an application (as prepared by File | Build Project Exe or File | Build Project Distribution) the on-initialization function is called by do-default-restart, which is supplied as the value of *restart-init-function*. That function initializes Common Graphics and calls the on-initialization function. If a window is returned, do-default-restart loops, processing events, until that window is closed (or the application is exited in some other fashion). If something other than a window is returned by the on-initialization function, the application exits immediately.

If there are windows in the application but there is no clear main window to return, then the on-initialization function should end with an event-handling loop of its own, which it exits upon determining that the application should exit. Here is a code sketch of such an on-initialization function, which calls some dummy functions that might be supplied by an application:

(defun my-custom-initialization-function ()
  (decide-what-windows-to-create-and-create-them)
  (do-some-additional-predetermined-processing)

  ;; Loop until it's time for the application to exit.
  (loop

    ;; Call process-single-event to handle each event
    ;; on the application's windows.
    (process-single-event)

    ;; When it is determined that the end user wants to close
    ;; the application, return from this event-handling loop
    ;; and therefore from the on-initialization function so that
    ;; the standalone application will exit.
    (when (time-for-this-application-to-exit?)
      (return))))

Note that the entire loop form in the example above could be replaced with a call to event-loop.

See default-init-function (the default value of the on-initialization property) for an example of the more typical case where the on-initialization function returns a main window rather than doing its own event loop.

The default function will probably suffice for most applications. But if a custom function is to be used, it may be specified interactively in the Init Function component on the Options tab of the Project Manager dialog, or programmatically by calling (setf on-initialization) on the project.

Creating a Standalone Application Without the Project System

It's possible to generate a standalone Common Graphics application with a direct call to generate-application, without using the IDE's project system at all. But note that a project's on-initialization function is not a suitable value for the :restart-app-function argument or the :restart-init-function argument to generate-application. Instead your restart function must be augmented to perform various bookeeping and initialization tasks that would otherwise be done automatically by the project system.

on-restart

on-restart is a property of an IDE project. Its value is the name of the function that is called internally to start up a standalone application that has been generated from the project. Normally the value is do-default-restart, though it may be changed to facilitate the debugging of a standalone application that is not successfully starting up and reaching a point where it could be debugged by pressing the BREAK key to enter the debugger in the console window.

This simply shows the console window Lisp listener, in which you can evaluate expressions to set up an initial environment for debugging. Then evaluate (do-default-restart) in the console to run the project code in the customized environment.

Alternately, you could change the on-restart property to the name of some other function that programmatically customizes the environment. An on-restart function should take no arguments. After setting things up for debugging, it should then either call do-default-restart (with no arguments) or else start up the application by hand. The application is started by hand by calling initialize-cg, then calling the project's on-initialization function, and finally calling event-loop to handle events.

Note that the way to customize the way a standalone application for a project really starts up is to use the project's on-initialization property. on-restart, in contrast, is intended only for debugging the standalone application.

You can inspect the current project by invoking the View | Project Manager command and then clicking on the Inspect Project button in the Project Manager's toolbar. The "Events" tab of the inspector will then show the on-initialization and on-restart properties of the current project.

open-files-in-gnu-emacs

The value of this configuration property can be nil, :open-only, or any other true value. If this configuration property is true and the Emacs-Lisp Interface is running, then the IDE will open lisp source code files in GNU emacs. Otherwise it will open them in the IDE editor. The :open-only value affects the behavior of File | Save All menu command, as described below in a way different from its modified behavior when this propert is true but not :open-only. This property affects the following commands:

When this option is enabled, the IDE's File | Save All command will tell Emacs to save all of its modified buffers (in addition to Save All's usual functionality). As a special case, if the value of this option is the keyword :open-only, then the IDE will open files in Emacs but never tell emacs to save modified buffers.

A check box for this configuration property is located on the Editor tab of the Options dialog.

The property is off by default. The special value :open-only cannot be specified on the Options dialog, but it could be set by evaluating the following form:

open-project

This function opens a project (identified by the arguments) for further development in the IDE. The project becomes the current project (as returned by current-project). This function returns the project that was opened, unless no project is opened for some reason (such as failure to specify an existing project definition file), in which case nil is returned. If the project is opened successfully, then the function current-project will continue to return the project until another opened project (or a new project) takes its place. (Therefore, if this function fails to open a project, the previously open project remains the current project.)

Projects are typically opened interactively by using the File | Open command (which calls this function), but it may be useful to call this function directly (for example) in the startup.cl file, perhaps as part of code that conditionally decides which project to initially open in the IDE. (startup.cl is loaded during IDE startup. See About IDE startup in cgide.html.)

When calling open-project programmatically, it's probably best to do so inside a call to eval-in-listener-thread as follows. This will ensure that the code runs in the IDE GUI process, just as when using the menu command, so that form windows and the project manager will get created in that process as usual. See eval-in-listener-thread for more information.

To simply run an existing project in the IDE without further developing it, or to load it before calling build-project, call load-project instead. There should be no need to call load-project and build-project specifically in the IDE GUI process.

Arguments

pathname-or-namestring may be either a pathname or string naming a .lpr project definition file that was automatically created by saving a project in the IDE. It may alternately be nil, in which case the file-selection Common Dialog is invoked to prompt for the .lpr file to open.

open-project-action

Returns (or sets with setf) whether all files, no files, or the out-of-date files are compiled when a project is opened. Valid values are

Radio-buttons for this option appear in the Open group-box of the Project tab of Options dialog.

open-project-show-files-in-editor

Returns whether opening a project in the IDE automatically opens an IDE editor buffer on each source code file of the project. The default is nil.

This option appears on the Project tab of the Options dialog (displayed with Tools | Options), and may also be set by calling the setf of this function.

When this option is not used, the files of the current project may still easily be found and opened from the General tab of the Project Manager dialog.

Example

open-project-show-project-manager

Returns whether opening a project in the IDE automatically shows the Project Manager dialog. The default is true.

This option appears on the Project tab of the Options dialog (displayed with Tools | Options), and may also be set by calling the setf of this function.

Example

options-path

Returns a pathname that indicates where the IDE will save its configuration options, and where it will look for an options file to read when it starts up. If there is a need to delete the current options file, this function could be used to find the file to delete.

If user-specific is true (as it is by default), then the returned path will be the one that will be used if the save-options-to-user-specific-file configuration option is true. If nil, then the path is the one that will be used if that option is nil.

partner-types

Returns a list of symbols indicating the types of partners that widget might have. Values in this list are suitable as values for the type argument to partners.

partners

Returns a list of controls that are associated, in a way specified by type, with the control specified by the widget argument. Type is a symbol indicating the particular type of association. The function partner-types takes a control as its argument and returns the types of partners possible for that control. Any item in the list returned by partner-types is suitable as a value for type.

For example, the up-down-control partners of an editable-text widget can be a list of one up-down-control (if the editable-text widget has one) or nil. The tab-control partners of any control is a list of the tab-control on which this control lies, if any.

patch-reminder-interval

Returns a value that indicates how often the Check for New Patches dialog will appear when the IDE is started up, to periodically remind you to check for new patches. The setf of this function may be called to change the value, and the drop-down list at the bottom of the dialog allows selecting a new value from a handful of choices.

The value may be nil, in which case the Check for New Patches dialog is never shown. Otherwise it should be a positive integer that indicates a number of days; when the IDE is started up, if it has been at least that many days since the Patch Reminder dialog was last shown, then it is shown at that time. The default value is 30, to provide a monthly reminder about patches. Here are a couple of possible setf's of this function:

;;  Evaluating this form will disable the Check for New Patches dialog:
(setf (patch-reminder-interval (configuration *ide-system*)) nil)
;;  Evaluating this form will cause the Check for New Patches dialog
;;  to appear weekly:
(setf (patch-reminder-interval (configuration *ide-system*)) 7)
;;  Evaluating this form will cause the Check for New Patches dialog
;;  to appear every three months:
(setf (patch-reminder-interval (configuration *ide-system*)) 90)

You can download patches at any time either with the Download Patches dialog (displayed with Install | New Patches or by calling sys:update-allegro directly, so you may want to set this configuration option to nil if you have no trouble remembering to check for new patches.

patch-reminder-previous-time

Returns the absolute universal time at which the Check for New Patches dialog was most recently shown. It is probably not useful to view or modify this value; it is exported primarily to follow the general rule of exporting all configuration options that are saved in the allegro-ide-options.cl file.

pretty-printer

Returns the value of the pretty-printer property of development-configuration. The current development configuration is the value of (configuration *ide-system*) (see configuration and *ide-system*).

This property determines whether to re-wrap lines of text when re-indenting (by choosing Edit | Reindent. The value can be :reindent and :pretty-print.

If the value is :reindent, the indentation of each line will be adjusted without rearranging words onto different lines.

If the value is :pretty-print, the whole expression will be re-pretty-printed, which may change which words are grouped together on the same line. Warning: when the value is :pretty-print, any internal comments in a top-level form will be lost whenever the Edit | Reindent command is used on it, because this option causes the form to be read and then pretty-printed anew into the editor window. Also, the :pretty-print option will not properly reproduce the original source code if the code contains reader macro calls that return objects that do not print readably; for example, #.(make-position 0 0) would be reprinted non-readably as #<position 0 0>. (Use of such position constants is deprecated; see with-positions.) Therefore, this option is probably useful only for uncommented plain vanilla source code that needs to be re-wrapped.

You can examine and change configuration options in general with the inspector. Choose Tools menu | Inspect System Data | IDE Configuration Options.

If pretty-printer is :reindent, choosing Edit | Reindent while the form is selected produces:

If pretty-printer is :pretty-print, choosing Edit | Reindent while the form is selected produces (notice that the comment has disappeared):

print-generate-application-call

Returns (or sets with setf) whether generating a standalone application will print the call to generate-application or build-lisp-image. The default value is nil, but you could turn on this option to check whether all of the arguments were passed as intended. This applies when using the interactive commands Build Project Executable and Build Project Distribution on the IDE's File menu, and also when calling build-project programmatically.

printer-font

Returns (or sets with setf) the font in which the contents of IDE editor windows will be printed on a printer by the File | Print command. This may be changed interactively on the Fonts tab of the Options dialog.

process-trace-color

Returns either an RGB color object (see make-rgb) or nil, indicating the background color to use in the Trace Dialog outline for traced calls that occur in process, which must be a process (see process-name-to-process). The initial value is nil, indicating that the default window background color (normally white) will be used.

The setf of this function may be called to set or change the trace color of any process. This may be helpful for finding relevant trace output when traced functions are being called in multiple processes. (The Trace Dialog already uses its title-bar to indicate the process of the currently selected item, but adding color to all of the items gives a more immediate overview.) As usual, the Trace Dialog must be present when traced functions are called in order for it to collect the trace output.

Of the standard IDE processes, only the IDE GUI thread has an initial trace color, which is the very pale blue returned by (make-rgb :red 240 :green 240 :blue 255). Calls in this thread typically do not involve application code, and so are likely to be of little interest to application developers. Trace colors generally should be pale to contrast with the black text. For example, the following form would cause all subsequent traced calls in the current process to appear in the Trace Dialog with a pale red background:

profiler-included-node-types

The value is a list of symbols indicating which types of nodes are not to be filtered out of a runtime analyzer outline and graph. This list is best set interactively by clicking on the Filter button of the Runtime Analyzer Results dialog.

project

Returns the project of which module is a part. project is a property of the module and form-module classes.

project-file

Returns the pathname of the project (.lpr) file of project. project-file is a property of the project class.

project-file-version-info

Returns a property list containing version (and other) information about the distributed application for a project. This information is used by the Windows operating system, and ignored on other platforms.

The plist keys are the same as the keyword argument names of the function win:set-file-version-info, and the plist values are strings.

The setf of this function could be used to establish the values, though typically you would instead fill in the widgets on the Version Info tab of the Project Manager dialog. See the documentation for that tab for more information.

project-package

Returns the default package of project. The value is displayed on the Options tab of the project manager. When a file associated with the project is created by the Integrated Development Environment, (in-package [name of project-package]) is placed at the top. See project-package-name for more information.

project-package-name

The default method for this generic function returns a keyword symbol naming the default package that is used for source code that is auto-generated for the forms of a project. This package is used for all forms whose form-package-name is nil, as it is by default; in other words, it is used for all forms that do not explicitly override this project-wide default. The value of this property for the current project is displayed on the Options tab of the Project Manager dialog. The setf of this function may be called to change the default package of the project.

When creating a new project, we strongly recommend that you decide on a package name for the project and specify it in the Project Manager before creating forms or source code for the project (unless you're content with using the default cg-user package). When changing the package later, it can be tedious to find all of the places where you may need to update package references in the project's source code, including the .bil files that are generated automatically for forms.

When running the complete application, either by using the Run | Run Project command or by using the File | Build Project Distribution command, the variable *package* will initially be set to the project's default package. This is not done by the Run | Run Form command, though, because no new process is created for a running form.

The package must exist before setf'ing this value. The package is created automatically if needed when you enter a project package name on the Options tab of the Project Manager dialog. The next File | Save All command will then save the .lpr project definition file to contain a minimal defpackage form for the package to allow the .lpr file to load without error and to allow all of the project's source code files to be "in" the project's package, including any project file where you may have specified a more complete defpackage form.

project-parent-directory

Returns a directory that will be used when you create a new project and are asked to specify a default directory for the project's source code. This parent directory will initially be selected in the directory-choosing dialog as the suggested parent directory for the new project's directory.

Typically, this value is set only once when creating a new project for the first time. At that time, the directory-choosing dialog asks for this default parent directory for all future projects, and the path is stored with the other configuration options in a allegro-ide-options.cl file. If the value needs to be changed later, the setf of this function may be called to do so.

It is recommended that all project code be placed outside of any particular Allegro installation, so that it can remain there when installing a new version of Allegro and perhaps uninstalling older versions.

Example

projects

Returns a list of all subprojects of project. projects is a property of the project class.

property-starter-code

A function that takes an object and an event-handler property name and returns information for constructing an initial skeleton version of a function definition to be used for that event handler. Two values are returned, (1) the argument list for the definition, and (2) a string representing the body of the definition. The string excludes the first line of the definition containing the name of the method and the parameter list.

This skeleton code is generated in an editor when the user selects extended editing in the inspector for an event-handler property whose value is not yet a user function name.

If new event-handler properties are created to extend the IDE, then the starter code cannot be specified in a defproperties or defcomponent expression. Instead, one or more property-starter-code methods should be written for the new property.

query-exit

Returns (or sets with setf) whether a confirmation dialog appears when you attempt to exit the IDE. If true, the IDE will not exit if you do not confirm that you really want to exit the IDE. If nil, the IDE will simply go ahead and exit.

See also query-os-exit, which controls whether the user is prompted for confirmation when the operating system is exiting.

CG/JS Note: When running the IDE in a web browser, see also query-web-browser-exit to allow user confirmation when closing the browser tab of the IDE.

query-os-exit

Returns whether the IDE will always ask for exit confirmation when the underlying operating system is shutting down or logging off the current user. A modal dialog will ask "Do you really want to exit Allegro CL, allowing the operating system to exit?" If the user replies No to the modal dialog, then the shutdown or logoff is canceled, and the IDE continues running.

If there are unsaved changes in the IDE, then the dialog asking whether to first save changes will still appear regardless of the value of this option, and still offer a cancel option that would cancel the OS shutdown.

The default value is nil, since it is unusual for an application to cancel a shutdown when there are no unsaved changes.

See also query-exit, which controls whether the user is prompted for confirmation when a gesture is made to close the IDE.

query-web-browser-exit

A CG/JS option that determines whether the web browser will prompt for exit confirmation when the user tries to close the browser tab of the IDE or reload the page. Setting this to true can avoid losing unsaved changes in the IDE, such as in the editor. The default value is true, especially because Control+F4 is often used for closing a single application window, but when running in a web browser it will close the browser tab and thereby exit the IDE. Setting this option calls the setf of the CG function confirm-web-browser-exit. This option has an effect only in web browser mode.

This option is in addition to the query-exit option for all platforms for whether to prompt for confirmation when generally exiting the IDE.

recent

The default method returns an alist of the information used by the Recent pull-down menu. It is not intended for modification by users, but is exported because it may appear in the allegro-ide-options.cl file.

recent-limit

Returns (or sets with setf) the maximum number of items that will be retained in each of the submenus of the Recent pull-down menu. Older items are dropped as new items are pushed onto the lists when this maximum length has been reached. The initial value is 12.

remove-from-component-toolbar

Removes the button for a specified class from the IDE's Component Toolbar if there is one, and otherwise does nothing. component-class-name is the name of a control class that may be on the Component Toolbar. See add-to-component-toolbar.

Example:

restore-window-configuration

Arguments: window &optional (configuration (find-window-configuration window))

Moves and resizes window to the position and size that it had when the CG and IDE configuration options were last saved to or loaded from the allegro-ide-options.cl file. This applies only to windows for which keep-configuration returns true, which is the case for most IDE windows. Nothing is done for other windows, or if a allegro-ide-options.cl file has not been saved.

This function is called automatically at IDE startup time as each window is created, to restore each standard IDE window to its position and size from the previous invocation of the IDE (assuming that save-options-on-exit was true). It may possibly be useful to call at other times.

It is not useful to pass the optional configuration argument as something other than its default value.

run-as-web-browser-server

Returns a boolean value for whether the generated application will run by default in a web browser or as a desktop application. See the Project Manager option below for more information.

This CG/JS option is typically set with the Run as Web Browser Server widget in the CG/JS tab of the Project Manager dialog in the IDE. But it could be set programmatically like this:

run-in-web-browser

Returns whether the IDE will run in a web browser by default on successive runs, rather than as a desktop app. This default is now only rarely used, though, because the IDE always runs in a web browser on Mac and Linux, and the Start menu on Windows has separate commands for Windows desktop mode or web browser mode.

This option would still be used when running the IDE from the Windows File Explorer or when running it from a Windows terminal without specifying a --run-as-web-browser-server command line argument.

run-project-action

Returns (or sets with setf) whether project files should be saved and/or compiled whenever running a project. Valid values are the keywords

Radio-buttons for this option appear in the Run group-box of the Project tab of Options dialog.

running-form

Returns (or sets with setf) the form whose running window is window. A custom on-initialization function for a project may want to setf this value (along with the running-window of the form) when it runs a form. Then the IDE will know how to automatically close the running window if it is still open the next time the form is run. See the example in default-init-function.

running-window

Returns (or sets with setf) the window which is the running version of the form form, if such a window exists and is still open, and otherwise returns nil. A custom on-initialization function for a project may want to setf this value (along with the running-form of the window) when it runs a form, so that the IDE will know how to automatically close the running window if it is still open the next time the form is run. See the example in default-init-function.

runtime-build-option

A property of a project that holds the value that will be passed as the :runtime argument to generate-application when the File | Build Project Distribution command is invoked to create a standalone application from the project. The value may be either :standard (the default), :dynamic, or :partners. You must have the correct license for whatever value is selected. (If you do not have the correct license, the build will fail with an appropriate error.)

Certain features of Allegro CL may be included in runtime versions of different kinds, and not included in others. One such option is the compiler, which may not be included in a :standard runtime image. If the value is :standard, the discard-compiler to generate-application is specified true when the distribution is created.

This option can be set with the Runtime Option widget on the Build tab of the Project Manager dialog.

runtime-modules

Returns a list of keywords indicating the Common Graphics code modules that will be included in the standalone application that is generated from the specified project. By default, a project includes all CG modules, but a typical application can be made significantly smaller by excluding modules that are not used by the application.

The Include tab of the Project Manager dialog shows the list of all CG modules, and has a button for automatically selecting the modules that are used by the current project. The set of included modules could also be specified programmatically by calling (setf runtime-modules). The function all-runtime-modules returns the list of all CG module names.

sample-initargs

This generic function is called when a widget is being placed onto a form window, to determine the sample property values that it will initially have. Widgets do not have these sample property values when created programmaticlly; they are added only when designing dialogs interactively as forms to illustrate typical property values and their effects.

An :around method prevents sample initargs from being used when the name of the widget class is not in a built-in CG package. This prevents overriding the default initargs of a user widget subclass that has been placed onto the widget palette with a call to add-to-component-toolbar. That method has made it only marginally useful to define custom sample-initargs methods. But you could redefine the sample properties for built-in widget classes if desired. Or if it's tedious to remove the sample property values after creating instances of the built-in widget classes, you could define methods for built-in classes that simply return nil to avoid sample property values altogether.

A sample-initargs method should accept a single argument, which is a widget that's being added to a form. It should return a plist that's similar to the :default-initargs plist of a defclass form.

Here is the built-in method for single-item-list, which provides a sample range and initial value:

Custom sample-initargs methods should not be added to project code, because they are part of the IDE, which is not present in standalone applications. Custom methods could be loaded automaticatlly whenever the IDE starts up by placing the code into a startup.cl file in your main Allegro directory. Just create that file if it doesn't exist already.

save-options-on-exit

Returns (or sets with setf) whether current development configuration property values will automatically be saved into the allegro-ide-options.cl file when the IDE is exited. This value can be toggled interactively by selecting the Tools menu | Save Options on Exit menu command. This property is on by default.

save-options-to-user-specific-file

If the value of this IDE configuration option is true, as it is by default, then Common Graphics and IDE user options are saved into the user's home directory (or personal documents directory on Windows). If it is nil, then options are saved into the top-level directory of the Allegro CL installation (known as the allegro directory). In either case, the options will be saved into a file named allegro-ide-options.cl.

The full pathname that will be used can be found by calling Options, passing the value of this option as the user-specific argument.

The heuristic described above is intended to handle typical needs for user-specific options files or for avoiding a write-protected Allegro directory. If that default behavior is not adequate, then you can specify an explicit path by setting up an environment variable called "allegro_prefs" and whose value is the complete path namestring for the options file. This variable will take precedence in all cases. Example value: h:/important-files/allegro-prefs.cl. The path's directory should already exist. Environment variables are normally set up in the System area of the Windows Control Panel. The string case of environment variables is not important to Windows but Allegro CL expects lowercase so the variable name, allegro_prefs, must be lowercase. Its value may use either forward or backward slashes.

When starting the IDE, options are always loaded from the user-specific location if the file exists, and otherwise from

On Linux/Unix, the home directory is the value of the HOME environment variable as usual. On Windows, the home directory is considered to be the user's My Documents directory if it exists, or else the Personal directory. These directories are found by calling special-windows-directory with the keywords :my-documents and :personal.

save-whether-to-show-subproject-modules

When this setfable project property is true, a saved project will remember which subprojects were currently showing their modules in the Modules tab of the Project Manager dialog, and restore that state in the Project Manager when the project is opened again. The default value is t.

This property could be turned off to avoid saving a modified version of the project's .lpr file after simply showing or hiding a subproject's modules in the Project Manager, when no functional changes have been made to the project. This may be useful for source code management. You can find this property by using the Inspect Project button in the Project Manager's toolbar.

scroll-while-tracing

Returns or sets with setf the value of the scroll-while-tracing property of configuration. The current development configuration is the value of (configuration *ide-system*) (See configuration and *ide-system*.)

If the property is true, then when traced functions are called while the trace dialog is visible, the outline of traced functions will continuously scroll so that the most recent trace information is always visible at the bottom of the outline. If false, the outline will not scroll at all except when scrolled explicitly by the user.

selected-listener-pane

Returns the currently-selected IDE listener pane. It may be desirable to print debugging output to this particular stream, though IDE Listener processes and processes started by Run | Run Project generally handle that for you by binding the standard output streams to the selected listener pane.

If no-create is nil (as it is by default) and no IDE Listener exists, then one will be created. If true, then a listener is never created by calling this function. This argument is probably not useful to users since there normally is always at least one IDE Listener in the IDE.

shift-windows-onto-screen-at-startup

This IDE configuration option determines whether to check at IDE startup time for any top-level IDE windows that lie partly or totally off of the screen (meaning the entire "virtual screen" when multiple monitors are used). When this option is true, any such windows will be moved fully onto the screen.

When the use-ide-parent-window option is true, the single parent window is the only top-level IDE window, and therefore the only one that might get shifted. To retrieve child windows that might have gotten shifted out of the interior of the parent window, use the commands View | Manage Windows | Initialize Window Location or View | Manage Windows | Initialize All Window Locations.

Normally this check is not needed because the IDE saves its window positions separately for each different screen size that is used. But this option's value is true by default, to check just in case something has gone awry.

Shifting all IDE windows into view might be undesirable if the screen size is not being reported correctly by the underlying windowing system. We have seen this happen on a multiple monitor machine that reported the full virtual screen size that includes all monitors as being only as large as the primary monitor. That caused any IDE windows that were left on the secondary monitor to be moved onto the primary monitor at IDE startup. That can be avoided by setting this option to nil.

show-cgjs-server-window

Returns a boolean value for whether an additional web browser tab will appear for the CG/JS application server, where you can exit the server by closing that tab or the window that's inside it. See the Project Manager option below for more information.

This CG/JS option is typically set with the Show CG/JS Server Window widget in the CG/JS tab of the Project Manager dialog in the IDE. But it could be set programmatically like this:

show-dialog-on-compiler-warnings

If this configuration option is true, as it is initially, then a modal dialog is shown when any compilation warnings result from compiling source code files by using various IDE commands. (The dialog is not shown when there are no warnings.)

The dialog lists the warning messages and provides an OK button to proceed with loading the compiled file(s) and a cancel button to skip loading the compiled file(s). In addition, if the compilation is being done by Run | Run Project or Run | Run Form, then canceling the dialog will avoid running the form or project.

If this option is nil, then no dialog is shown, the loading is never skipped (unless a compilation error occurs), and (in the case of Run Project and Run Form) the project or form is always run. Compilation warnings are printed to the Debug Window regardless of the value of this option.

This option can be set in the Optional Dialogs group on the IDE 1 tab of the Options dialog. It may also be set with setf and this function.

The current development configuration is the value of (configuration *ide-system*). (See configuration and *ide-system*.)

show-quick-symbol-info-on-space

If this IDE user option is enabled, then typing a space after a symbol in the IDE's editor or listener will automatically invoke the command "Help | Quick Symbol Info" to display brief information about the symbol in the status bar.

This option is enabled by default, though it may interfere with some input methods that use multiple keystrokes for typing some characters, if one of the keys in such a sequence is the spacebar. If this happens, you can turn this option off to avoid the problem.

This option is not on the Options dialog, but you could turn it off interactively with Tools menu | Inspect System Data | IDE Configuration Options menu command, or programmatically with this expression:

show-widget-palette-when-click-form

An IDE configuration option that determines whether clicking the background of a form window will expose the Widget palette. The default value is true, but the option could be turned off if frequently exposing the palette becomes annoying. The palette can alternately be exposed with Form | Show Widget Palette.

The current ide-configuration is the value of (configuration *ide-system*) (see configuration and *ide-system*).

This option is not included on the Options dialog, but could be turned off by evaluating this expression:

snap-to-components

Returns or sets with setf the value of the snap-to-components property of development-configuration. The current development configuration is the value of (configuration *ide-system*) (see configuration and *ide-system*). This property determines whether a widget that is being dragged on a form will snap into exact alignment with another widget whenever it is within a few pixels of being aligned. Lines are also drawn on the form to show which widgets are currently aligned during the drag when this option is used. This makes it easy to align widgets exactly when dragging them. The default value is true. See also snap-to-grid.

You can also align widgets on forms by using the arrow keys to move the selected widget by a single pixel at a time. Alignment lines will be drawn at this time as well, to tell you when an incremental move has reached exact alignment. Holding down the Alt key while pressing an arrow key will move the widget by ten pixels rather than by one, and holding down the Control key will resize the widget rather than moving it.

You can examine and change configuration options with the inspector. Choose Tools menu | Inspect System Data | IDE Configuration Options.

snap-to-grid

Returns or sets with setf the value of the snap-to-grid property of development-configuration. The current development configuration is the value of (configuration *ide-system*) (see configuration and *ide-system*). This property determines whether dragging or resizing a component on a form will align it with the grid dots. If true, components (when moved with the mouse) will be aligned with the grid of dots on a form. If nil, components can be placed anywhere, whether aligned with the dots or not. The default value is nil because snapping to the grid makes it more difficult to align widgets with each other (see snap-to-components).

You can examine and change configuration options with the inspector. Choose Tools menu | Inspect System Data | IDE Configuration Options.

source-file-types

The value of this configuration option may be modified to change the set of file types that the IDE recognizes as source code files. The file types are used in places such as the file selection dialog, where files of those types are presented when asking for a source code file.

The value should be a list of strings, where each string names a file type. The default value is the list ("cl" "lsp" "lisp" "jil").

This option is not on the Options dialog, but could modified with a form like the following. This example would add "mylisp" to the list if it's not already there.

splash-file

Returns the file (as a pathname or path namestring) containing the splash pixmap for a project. When a standalone application is generated from the project with the File | Build Project Distribution or File | Build Project Exe command), the pixmap will appear on the screen as the standalone application is starting up. This lets the user know that something is happening while waiting for the application to finish loading and initializing.

The value may also be nil, in which case no splash pixmap is shown. Otherwise, the value should be the pathname or path namestring of a .bmp pixmap file. Allegro does not provide any tools for interactively drawing pixmaps, but Common Graphics does provide certain functions such as get-pixmap and save-pixmap to grab an image from the screen and then save it as a .bmp file.

The setf of this function may be used to specify a new splash file for a project programmatically, though this is typically done interactively on the Build tab of the Project Manager dialog instead.

standard-toolbar-icons

A configuration option that indicates which IDE commands are present as buttons on the main IDE toolbar (which is the toolbar to the left of the Components toolbar). The current development configuration is the value of (configuration *ide-system*). (See configuration and *ide-system*.)

The value is a list of keywords with names similar to the IDE menu-bar commands to which they correspond. The special value :gap is used to indicate where a vertical separator bar should appear between buttons on the toolbar. The initial value is:

(:apropos :breakpoint :breakpoint-status :browse-class
 :find-debug-prompt :find-definition :find-in-file
 :gap :graph-subclasses :graph-superclasses
 :incremental-compile :inspect :load :macroexpand
 :new :new-form :new-project :open :print
 :profile :profile-status :quick-symbol-info
 :run-project :save :save-all :stop :trace
 :trace-status :unbreakpoint :unbreakpoint-all
 :unprofile :unprofile-all :untrace :untrace-all
 :windows-help)

The extended toolbar (displayed with the View | Extended Toolbar menu command) will contain all of the commands that are not on the main toolbar.

This option may be set programmatically by calling (setf standard-toolbar-icons). Alternately, the value may be modified interactively by dragging icons between the main toolbar and the extended toolbar in the following way:

Commands can similarly be moved from the main toolbar to the extended toolbar, or within one of the toolbars. (The Components toolbar may not be modified.)

The value may also be modified in the inspector by using the Tools menu | Inspect System Data | IDE Configuration Options command.

start-ide

This is the entry function for starting the Integrated Development Environment (IDE) in a lisp where the IDE is not already running. This is all that is needed in the typical case:

If the IDE is already running (or is starting up), then start-ide simply returns nil. Otherwise, start-ide creates a new "IDE GUI" process and returns it right away. The IDE GUI process then proceeds to start up the IDE, and then sets *ide-is-running* to t when startup is finished. Therefore, if the caller of start-ide needs to know when the IDE is ready to use, it should wait until *ide-is-running* is true, since this is generally some time after start-ide returns.

If run-in-web-browser is true, then the IDE will run inside a new tab of a web browser, and otherwise it will start up as a desktop Windows app.

If start-local-client is true (as it is by default), then the IDE will proceed to appear in the default web browser on the same machine (when run-in-web-browser is also true). Otherwise the IDE will wait for a web browser on the same or another machine to connect to the server machine at the port that's printed by start-ide, to display the IDE there at that time.

Note about starting the IDE in Allegro CL Express Edition on Linux: if you wish to use the IDE on Linux in the Express Edition, you must start the executables and images that are named allegro or allegro-ansi. Trying to load the IDE and then calling start-ide does not work in Express. See Running the IDE in Allegro CL Express on Linux in installation.html.

start-in-allegro-directory

This configuration option determines the directory that will initially be shown in the file selection dialog the first time it is invoked in an IDE session. (After a file is actually selected in this dialog, the next invocation will initially show the directory of the most recently selected file, unless that is overridden by context-sensitive-default-path).

If this option is nil (the default), then the first invocation of the file selection dialog will show the operating system's current directory, which may have been set by another application or by a Windows shortcut that was used to start the IDE. If this option is true, then the first invocation of the file selection dialog will show the directory where Allegro is installed.

If you usually use Windows shortcuts to start the IDE, either from the Start Menu or from desktop icons, then nil (the default) is probably the suitable choice, because then the initial file selection directory will reflect the "Start In" directory of the shortcut. Multiple shortcuts can even be used to default the file selection dialog to different directories of source code for various applications. But if you instead usually start the IDE by double-clicking an EXE or DXL file in the File Explorer, or by using a custom Emacs command, then you may want to set this option to true to prevent the file selection dialog from defaulting to an arbitrary current directory that had been set by an unrelated application.

start-local-client

Returns a boolean value for whether running the CG/JS generated application will also tell the default web browser on the same machine to connect to it as a client and display the application. See the Project Manager option below for more information.

This CG/JS option is typically set with the Start Local Client widget in the CG/JS tab of the Project Manager dialog in the IDE. But it could be set programmatically like this:

style-options

Returns an association list of global CG/JS stylistic options for things such as the color and thickness of window borders, the font used in all menus, and the delay before showing a child menu. See the Project Manager option below for more information.

This CG/JS option is typically set with the Style Options widget in the CG/JS tab of the Project Manager in the IDE. But it could be set programmatically like this:

(setf (ide:style-options
        (cg:cgjs-options (ide:current-project)))
  `((:selected-window-border-color
     ,(make-rgb :green #xaa :blue #xff))
    (:unselected-window-border-color
     ,(make-rgb :red #x77 :green #xcc :blue #xff))))

subobjects-with-partners

Returns a list of subobjects of object that may have "partners" that are associated with them in some way. For example, the subobjects-with-partners of a tab-control is the tab-control's range, since that is a list of tabs each of which has a set of "partners" consisting of the components on that tab.

A subobjects-with-partners method could be added to a custom widget in order to customize its behavior on forms.

The partners mechanism is used when manipulating components on a form in order to find components that may be affected when one of its "partners" is modified.

symbol-completion-searches-all-packages

Returns (or sets with setf) whether symbol completion will search all packages after finding no symbols in the initial search package.

If the symbol being typed has a package qualifier, then the initial search package is the package named by that qualifier; otherwise it is the current package. If one or more symbols are found in this initial search package, then only those symbols are presented as completion choices. (If there is only one choice, then that symbol is completed automatically.) But if there are no symbols found in the initial search package, then all packages will then be searched only if this property is true.

title-for-browser-tab

Returns the short string to display as the name of the CG/JS application in the small browser tab above the application. See the Project Manager option below for more information.

This CG/JS option is typically set with the Title for Browser Tab widget in the CG/JS tab of the Project Manager dialog in the IDE. But it could be set programmatically like this:

top-ide-window

trace-format

This function is used to insert arbitrary comments and data into trace output. Formats a string using format-string and args just as they are used in a call to format, and inserts that string into the trace output at the current position.

If the Trace Dialog is currently visible, an item is added to its trace outline. When an item that was created by a call to trace-format is selected in the trace outline, each of the args will appear individually in the trace dialog's Arguments item-list and be accessible as lisp objects, just as the arguments to traced functions are.

If the trace dialog is not currently visible, the string is printed to *trace-output* as a comment along with other trace output.

use-antialiased-text-in-tree-graphs

If this configuration option is true, then *antialiasing* will be bound to true when drawing the text in nodes in class graphs and runtime analyzer graphs. This produces text that is likely easier to read, though somewhat fuzzier (on the Windows platform only).

The default value is true. If you find the effect to be more annoying than useful, you can turn off the effect with this form (see configuration and *ide-system*):

use-cg-html-browser

Returns whether the various help commands in the IDE will display information in a Common Graphics html-browser dialog within the IDE, or in a third-party HTML-browsing program. The default value is nil. A true value will have an effect only in Windows desktop mode, though the html-browser is rather limited, such as having no string search ability.

An advantage of the html-browser dialog within the IDE (which is titled "Allegro Help") is that you can select text and apply IDE menu-bar commands to it. For example, you could select a code example and then invoke the Tools menu | Incremental Evaluation command on it directly, rather than first copying the example code to the editor or listener. Or select a class name and then invoke the Tools menu | Browse Class command. The html-browser is also probably more reliable than the keystroke-emulation technique that we must employ to reuse an single instance of an arbitrary third-party program (see invoke-private-html-browser).

The major disadvantage of the Allegro Help dialog is that the html-widget within it does not provide a string search capability. This appears to be a limitation of the OCX WebBrowser control on which the CG html-widget is based. If you use the IDE's string search commands (from the Search menu) in the Allegro Help dialog, you will be presented with options that include displaying the current page in a third-party HTML browser, so that you can do the search there.

This option is located on the IDE 2 tab of the Options dialog, as a check-box with the label "Show IDE Help Within the IDE". It can also be modified programmatically with a form such as the example below. (In either case, the value will be remembered in your preferences file and used in future IDE sessions.)

use-color-gradients-in-tree-graphs

If this configuration option is true, then *color-gradient-filling* will be bound to true when drawing the nodes in class graphs and runtime analyzer graphs. This produces a three-dimensional effect (on the Windows platform only).

The default value is true. If you find the effect to be more annoying than useful, you can turn off the effect with this form (see configuration and *ide-system*):

use-ide-background-window

Returns (or sets with setf) whether the optional IDE background window is displayed. This window is useful mostly for covering other applications that may be distracting when they are visible between the IDE's multiple top-level windows. This option has an effect only when the use-ide-parent-window option is nil, because otherwise there is only a single top-level window through which other applications do not show.

The background window also has a right-button shortcut menu that lists all current IDE windows that aren't shrunk (hidden). Selecting a window on this menu brings the window to the front and gives it the keyboard focus.

Changing this property while the IDE is running will toggle the background window off or on. When the IDE is started up, the background window will appear if it was there whenever the configuration options were most recently saved.

use-ide-debugger-on-all-processes

This user option controls controls whether the IDE's debugger will be used for all non-IDE processes when they signal errors, rather than using the base Lisp's debugger. (The IDE's debugger is always used for IDE processes.) The default value is true to use the IDE's debugger for all processes. One case where you may want to use the base Lisp's debugger instead for non-IDE processes is when running the IDE from Emacs, in which case you may want to turn this option off.

This option does not appear on the options dialog, but it could be turned off with the following expression:

An alternative is to specify whether the IDE's debugger should be used for an individual non-IDE process. This can be done by adding a :use-ide-debugger entry to the process-property-list of the process. If such an entry is in the plist, it overrides the value of use-ide-debugger-on-all-processes even if the plist entry is nil. For example, the following expression would ensure that the IDE's debugger is not used for the current process.

use-ide-parent-window

An IDE configuration option that returns whether the IDE uses a parent window (with all other IDE windows contained within it) rather than a non-parent owner window (with its owned IDE windows floating freely on the screen). A true value indicates a parent window, while nil indicates an owner window.

The initial value is true. The owner window style could be used by evaluating the form

and then restarting the IDE (assuming that the save-options-on-exit option is enabled as it is by default). use-ide-parent-window is on the IDE 1 tab of the Options dialog. A change to this option will be in effect only when you restart the IDE (so options must be save for the change to have any effect).

When this option is nil to use multiple top-level windows, the opaque background of a single parent window can be simulated by turning on the use-ide-background-window option, while still allowing the individual top-level windows to float freely.

The function main-ide-window will return the owner window of the various IDE tool windows. When an IDE parent window is used, the main-ide-window will be an instance of the ide-child-window class; this window is the frame-child of the IDE parent window, which is an instance of the ide-parent-window class. When an IDE owner window is used, the main-ide-window will be the IDE owner window itself, which is an instance of the ide-owner-window class.
The function top-ide-window always returns the topmost IDE window.

use-private-html-browser

This is an obsolete IDE configuration option that exists only for backward compatibility. It had been used by invoke-private-html-browser.

The current development configuration is the value of (configuration *ide-system*). (See configuration and *ide-system*.)

use-trace-dialog-in-this-process

Use of this function is deprecated as of release 10.0 because it is no longer needed. The trace dialog will now always be used for all processes whenever the trace dialog is present. This function will now simply signal a warning about that.

verbose

Returns the value of the verbose property of project. The value of the property can be true or nil. When true, *load-verbose* and *compile-verbose* are set to true when compiling and loading files associated with project. verbose is a property of the project class.

warn-on-no-action-taken

Returns the value of the warn-on-no-action-taken property of configuration. The current development configuration is the value of (configuration *ide-system*) (See configuration and *ide-system*.)

If this property is true, the system pops up a warning dialog when requested commands cannot be performed. If the value is nil, the failure is indicated, if at all, with a beep or a status-bar message.

web-browser-style-options

Returns a set of stylistic options for use in the IDE, such as window border colors and thicknesses. These values will override the default values for all CG/JS apps that are defined in *cgjs-client-options*, to give the IDE itself a custom style.

You could edit the values interactively by using Tools menu | Inspect System Data | IDE Configuration Options, then scroll down to web-browser-style-options near the bottom of the list of all IDE options in the inspector. Clicking on the value reveals a small button on the right, and clicking on that small button will show a multi-line text editor for editing a copy of *cgjs-client-options* that's used for the IDE itself. You will need to restart the IDE after editing these options for them to take effect.

As with the custom options for a project, the IDE's values can be any subset of *cgjs-client-options*, rather than the entire list that you see in the inspector.

These options are saved in a file with a name like allegro-style-options.txt, where allegro is the file name of the particular ACL executable that you're running. The file will be saved in the user's home directory, on Windows meaning their personal Documents directory. This file could be deleted to restore the IDE to use the default stylistic options for all CG/JS applications.

window-configurations

Returns a list of system windows named by keywords (:apropos-dialog, :find-in-file-dialog, etc.) paired with their exterior boxes. window-configurations is a property of the configuration class.

with-output-to-ide-listener

Arguments: (&key fresh-prompt expose-listener-frame show-top) &body body

This is a convenience macro for directing debugging output to the currently-selected IDE listener. It binds *standard-output* and *error-output* to the stream returned by selected-listener-pane around the execution of the body. It also first moves the listener's text cursor to the end of the text and calls fresh-line, to ensure that the output begins on a new line at the end of all previous output. For efficiency, the body is executed inside a call to with-delayed-redraw for the listener pane, which will delay the drawing of all output until the body has completed, and then draw it only once.

If fresh-prompt is true, then a prompt is printed after the body has been executed. A fresh prompt is not necessary in order to enter and evaluate a form in the listener, but it may be desired for aesthetic reasons or to indicate that the body has completed.

If expose-listener-frame is true, then the debug window is exposed and selected after the body has completed.

If show-top is true and there is enough output to scroll the first part of the output out of view, then the listener will be scrolled at the end so that the first part of the output is visible at the top of the listener pane.

Note that an IDE Listener process or a process started by Run | Run Project will bind the standardized input and output variables like *standard-output* and *standard-input* to the selected IDE listener, so standard output in those processes would appear in the IDE listener anyway, whereas other processes will instead bind the variables to the (typically hidden) console window, which is the value of *initial-terminal-io*.

with-trace-color

Causes all traced calls that occur within the dynamic scope of body (in the current process) to appear in the Trace Dialog with the background color specified by rgb-color, which must be an RGB color object (see make-rgb). Returns the values returned by the last form in body.

It may be useful to add calls to with-trace-color in tester code to distinguish calls made within a tester form from extraneous calls that happen to be made otherwise, or even to distinguish multiple tested options or multiple test runs from each other. Calls to with-trace-color may even be inserted into application code and left there when generating a standalone application to distribute, because in a standalone app the calls turn into simple progn forms.

For example, evaluating the following forms (after showing the Trace Dialog with the Run | Trace Dialog command) will trace a few functions and then collect pale green trace output for the calls to those functions that occur during a particular call to make-window. Lots of additional calls to device-open will appear as well in the Trace Dialog as arbitrary strings are created, and so the green highlighting helps to quickly find the block of calls that occurred within the tester form.

(trace make-window device-open initialize-instance)

(ide:with-trace-color ((make-rgb :red 224 :green 255 :blue 224))
  (make-window :foo :class 'frame-window))