on-initialization

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 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))))

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.

on-initialization is a property of the project class.

Creating a standalone application without the Project System

See About creating a Standalone Common Graphics Application without using the Project System in cgide.htm for information on creating a Common Graphics application with a direct call to generate-application. As pointed out there, a suitable 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 function must be augmented to perform various bookeeping and initialization tasks which are done automatically by the project system.

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