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.
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.
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
GRAPHICS-PORTS Reference Entries, describes the external symbols of the
LW-GT Reference Entries, describes the external symbols of the
COLOR Reference Entries, describes the external symbols of the
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
capi. Drawing - Graphics Ports and The Color System shows you how to use the
color packages respectively; the remainder of the User Guide section shows you how to use the
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".
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.
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.
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).
These books are provided in both HTML and PDF formats, and may also be found at
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 .
Please let us know at
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