finder-function

Generic Function

Package: common-graphics

Arguments: module

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 doc/cg/form/form.htm and doc/cg/ide-user-guide/ide-user-guide-4.htm 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.

module should be 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 :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,

(finder-function (find-module (current-project) :form6) )
  -> my-package::form6

If the name of the form is :curve-dialog and the package is common-graphics-user, finder-function called with argument the :curve-dialog module 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.

Since the programmer knows the names of these functions by formula, it is technically not necessary to use finder-function and maker-function to find them. But finder-function and maker-function are useful because they allow you to modify names (and packages) without finding and changing all references in source code. Suppose instead you have an association list with descriptions and names of your application windows:

(defparameter app-window-association-list
  (:main-window :account-dialog :deposit-popup :deposit-dialog
   :withdrawal-popup :pay-dialog))

So long as you keep that association list up to date, and the value of my-project is the project, the forms

(apply 
  (finder-function 
    (find-module my-project
       (getf app-window-association-list :withdrawal-popup))))
(apply
  (maker-function 
    (find-module my-project
       (getf app-window-association-list :withdrawal-popup))))

will call the finder function and the maker function, respectively, even if the name of the :withdrawal-popup form/window is changed from :pay-dialog to :withdrawal-dialog at some point during the application development.

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.

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, name, title, and border. These arguments have the same meanings they do with the function make-window.

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.

Created 2000.10.5.