on-initialization

Generic Function

Package: common-graphics

Arguments: project

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 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 cg::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, cg::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))))

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 Optionstab of the Project Manager dialog, or programmatically by calling (setf on-initialization) on the project.

on-initialization is a property of the project class.

Common Graphics and IDE documentation is described in About Common Graphics and IDE documentation in cgide.htm.

The documentation is described in introduction.htm and the index is in index.htm.

Copyright (c) 1998-2000, Franz Inc. Berkeley, CA., USA. All rights reserved.

Created 2000.10.5.