This preface contains information you need when using the rest of the CAPI documentation. It discusses the purpose of this manual, the typographical conventions used, and gives a brief description of the rest of the contents.
This manual contains a user guide section (previously published separately as the CAPI User Guide ) and a reference section (previously the LispWorks CAPI Reference Manual ).
The CAPI documentation assumes that you are familiar with:
Illustrations in this manual show the CAPI running on Mac OS X 10.5, so if you use a different version you should expect some variation from the figures depicted here.
Unless otherwise stated, examples given in this document assume that the current package has CAPI on its package-use-list.
Throughout this manual, certain typographical conventions have been adopted to aid readability.
Text which you should enter explicitly is printed like this.
Exported symbols and example code are printed like-this. The package qualifier is often omitted, as if the current package is capi (or graphics-ports or color.)
Variable arguments, slots and return values are italicised. They look like-this in the main text.
The user guide section of this manual forms an introductory course in developing applications using the CAPI. Please note that, like the rest of the LispWorks documentation, it does assume knowledge of Common Lisp.
Introduction to the CAPI, introduces the principles behind the CAPI, some of its fundamental concepts, and what it sets out to achieve.
Getting Started, presents a series of simple examples to familiarize you with some of the most important elements and functions.
General Properties of CAPI Panes, introduces more of the fundamental CAPI elements and common themes. These elements are explained in greater detail in the remainder of the manual.
General Considerations, covers some general issues that you should be aware of when using CAPI, including information about multiple displays.
Choices - panes with items, explains the key CAPI concept of the choice . A choice groups CLOS objects together and provides the notion of there being a selected object amongst that group of objects. Button panels and list panels are examples of choices.
Laying Out CAPI Panes introduces the idea of layouts . These let you combine different CAPI elements inside a single window.
Programming with CAPI Windows, outlines basic techniques for modifying existing windows.
Creating Menus, shows you how to implement menus.
Adding Toolbars, shows you how to add toolbars to a window.
Defining Interface Classes - top level windows, introduces the macro define-interface. This macro can be used to define interface classes composed of CAPI elements, including the predefined elements described in this manual and also elements which you define.
Dialogs: Prompting for Input, discusses the ways in which dialogs may be used to prompt the user for input.
Creating Panes with Your Own Drawing and Input, shows you how you can define your own classes when the elements provided by the CAPI are not sufficient for your needs.
Drawing - Graphics Ports, describes the Graphics Ports API which provides a selection of drawing and image transformation functions. Although not part of the CAPI package, and therefore not strictly part of the CAPI, the Graphics Ports functions are used in conjunction with CAPI panes, and are therefore documented in this manual. See also GRAPHICS-PORTS Reference Entries.
Graphic Tools drawing objects, describes the Graphic Tools API which provides a way to create more complex drawings, including graphs and bar charts. Graphic Tools are built with Graphics Ports and CAPI pinboards, and are therefore documented in this manual. See also LW-GT Reference Entries.
The Color System, allows applications to use keyword symbols as aliases for colors in Graphics Ports drawing functions. They can also be used for backgrounds and foregrounds of windows and CAPI objects. See also COLOR Reference Entries.
Printing from the CAPI—the Hardcopy API, describes the programmatic printing of Graphics Ports.
Drag and Drop, describes how you can implement drag and drop in your CAPI application.
Host Window System-specific issues, describes how to configure the appearance of CAPI windows on the various supported host window systems.
Self-contained examples, enumerates the CAPI example files available in the LispWorks library.
The reference section contains reference entries for the symbols in the capi, graphics-ports, lw-gt and color packages.
Within each chapter, the symbols are organized alphabetically (ignoring non-alphanumeric characters that are common in Lisp symbols, such as *). The typographical conventions used are similar to those used in Common Lisp: the Language (2nd Edition) . Further details on the conventions used are given below. The chapters are:
CAPI Reference Entries, describes the external symbols of the capi package.
GRAPHICS-PORTS Reference Entries, describes the external symbols of the graphics-ports package.
LW-GT Reference Entries, describes the external symbols of the lw-gt package.
COLOR Reference Entries, describes the external symbols of the color package.
Note:
Although the graphics-ports and color packages are not strictly part of the CAPI, they are included in this manual because the functionality is usually called from CAPI elements such as output panes. lw-gt is also included here since it is built on top of graphics-ports and capi. Drawing - Graphics Ports and The Color System shows you how to use the graphics-ports and color packages respectively; the remainder of the User Guide section shows you how to use the capi package.
Each entry is headed by the symbol name and type, followed by a number of fields providing further details. These fields consist of a subset of the following: "Summary", "Package", "Signature", "Method signatures", "Arguments", "Values", "Initial value", "Superclasses", "Subclasses", "Initargs", "Accessors", "Readers", "Description", "Notes", "Compatibility notes", "Examples" and "See also".
Some symbols with closely-related functionality are coalesced into a single reference entry.
Entries with a long "Description" section usually have as their first field a short "Summary" providing a quick overview of the symbol's purpose.
The "Package" section shows the package from which the symbol is exported.
The "Signature" section shows the arguments and return values of functions and macros, and the parameters of types.
In a Generic Function entry there may be a "Method signatures" section showing system-defined method signatures.
The "Arguments" and "Values" sections show types of the arguments and return values.
In a Variable entry, the "Initial value" section shows the initial value.
In a Class entry the "Subclasses" section of lists the external subclasses, though not subclasses of those, and the "Superclasses" section lists the external superclasses, though not superclasses of those. The "Initargs" section describes the initialization arguments of the class, though note that initargs of superclasses are also valid. There may be an "Accessors" section listing accessor functions which are both readers and writers, and/or a "Readers" section listing accessor functions which are only readers. Accessor functions access the slot with matching name.
The "Description" section contains the detail of what the symbol does, how each argument is interpreted (and its default value if applicable), and how each return value is derived. More incidental information may be shown in a "Notes" section.
A few entries have a "Compatibility notes" section describing changes in the symbol's functionality relative to other LispWorks versions.
Examples are given under the "Examples" heading. Short examples are shown directly. Longer examples are supplied as source files in your LispWorks installation directory under examples/capi/. The convenience function lw:example-edit-file allows you to open these files in the LispWorks editor.
Note that the example code is written with explicit package qualifiers such as capi:interface, so that it can be run as-is, regardless of the current package.
Finally, the "See also" section provides links to other related symbols and user guide sections.
This manual often refers to example files in the LispWorks library via a Lisp form like this:
(example-edit-file "capi/choice/drag-and-drop")
These examples are Lisp source files in your LispWorks installation under lib/7-1-0-0/examples/. You can simply evaluate the given form to view the example source file.
Example files contain instructions about how to use them at the start of the file.
The examples files are in a read-only directory and therefore you should compile them inside the IDE (by the Editor command Compile Buffer or the toolbar button or by choosing
Buffer > Compile
from the context menu), so it does not try to write a fasl file.
If you want to manipulate an example file or compile it on the disk rather than in the IDE, then you need first to copy the file elsewhere (most easily by using the Editor command Write File or by choosing
File > Save As
from the context menu).
The LispWorks manual set also includes the following books:
These books are provided in both HTML and PDF formats, and may also be found at
www.lispworks.com/documentation
.
Commands in the Help menu of any of the LispWorks IDE tools give you direct access to your local copy of the HTML format manuals. Details of how to use these commands can be found in the LispWorks IDE User Guide .
You can use Adobe® Reader® to browse the PDF documentation. Adobe Reader is available from Adobe's web site, http://www.adobe.com/.
Please let us know at
lisp-support@lispworks.com
if you find any mistakes in the LispWorks documentation, or if you have any suggestions for improvements.
CAPI User Guide and Reference Manual (Macintosh version) - 3 Aug 2017