make-window

Arguments: name &rest arguments &key (class (quote frame-window)) (owner (development-main-window *system*)) dialog-items form-p child-name behind state &allow-other-keys

Creates and returns a new window, or returns nil if the request to the Operating System to create a new window fails (see the information under the heading make-window returns nil if a window cannot be created near the bottom of this page).

The name argument should be a symbol (we recommend using keywords) which does not name any other object. The name can be passed as an argument to find-window and other find- functions to get a programmatic handle on a window.

When using the Integrated Development Environment, you can design windows to be used in your application using forms. A form is a class of window that is used to design windows of other classes. The Integrated Development Environment creates a function from a form you have designed which creates the designed window. Get a new form by clicking File | New Form. You are asked for the class of the window (the value of the :class argument) and that is the type of window that will be designed with the form.

Here are some keyword arguments to make-window:

• :class: default: frame-window. The class of the window being created. The standard choices besides frame-window are text-edit-window, bitmap-window, dialog, rich-edit-dialog, and non-refreshing-window. We recommend that you subclass these standard classes so your customizations will not affect existing windows. In earlier releases, this argument was named device and that name is still accepted. Do not, of course, specify both.

  The accessor/setter of the class property is device, though it is uncommon to need to use that function programmatically (one typically sets this slot upon creation or using the class slot in an inspector window). (class-name (class-of object)) also serves as an accessor.

• :owner: an existing window (or the screen) that will be the owner of the new window. The default owner is the value returned by (development-main-window *system*), which is the invisible IDE owner window when the IDE is present, and otherwise the screen. See development-main-window.

  A window shrinks or closes whenever its owner window does. If the child-p argument is true, then the owner will also be the parent of the new window. A window moves along with its parent, and is clipped at the interior edge of the parent. In earlier releases, this argument was named parent and that name is still accepted. Do not, of course, specify both.

  See About child, parent, and owner windows in cgide.htm.

• :child-p: default is t. A boolean value indicating whether the new window will be a child window. If non-nil and the owner is a window rather than the screen, then the new window will be a child window and the owner window will also be its parent. A child window moves along with its parent and is clipped at the parent's interior border. If nil or the owner is the screen, then the new window will float freely about on the screen, but will still shrink and close along with its owner (if the owner is a window). The parent of a non-child window is the screen.

  GTK note: On X platforms, we strongly discourage specifying child-p as nil, because non-child owned windows are often not handled well. A typical window manager will add a separate taskbar item (and alt-tab item) for each non-child window, and will allow the user to move other applications between an owned window and its owner window in the occlusion stack. Common Graphics may also not be allowed to move the keyboard focus to a different top-level window programmatically.

• :dialog-items (formerly :widgets): default: nil. The value should be a list of controls (also called widgets, whence the former argument name) to be placed on the window. While controls can be placed on any window, only windows of type dialog-mixin (that is, only windows whose class is a subclass of dialog-mixin) will have the special Windows dialog behavior. In such windows, pressing the TAB key moves the keyboard focus from one control to another and pressing Alt-[letter] will move the keyboard focus to the control that has the letter underlined as its access character. (For example, pressing Alt-A will move keyboard focus to the control whose access letter is an underlined A.)

  Each widget in the list is created by calling make-instance on a subclass of dialog-item. See the list of all widget classes in cgide.htm. Each widget instance can be used on only a single parent window.

  The use of :widgets to name this argument is deprecated. :dialog-items should be used instead. :widgets is accepted and both should not be specified.

• :pop-up: default: nil. See pop-up. This argument should be specified true if the window is intended to be modal. Note that the value of this property cannot be changed once the window has been created.

  See About child, parent, and owner windows in cgide.htm.

• :form-p: this parameter is for internal use by the IDE, and should not be specified by applications.
• :child-name: when instantiating a window class that has the frame-with-single-child mixin (such as non-refreshing-window or bitmap-window), the :child-name argument may be passed to make-window to provide a name for the child pane that is created automatically for the frame window. As with other object names that are used in Allegro CL for finding objects, the name should be a symbol.

  In fact it is unlikely that this name will be needed programmatically, since the child-pane can be found by calling frame-child on the parent frame window, it is nevertheless often helpful for arbitrary objects to have names so that the they can be recognized more easily during debugging.

• :behind: this argument determines whether the new window should be placed behind or in front of its siblings in the occlusion stack. The default is nil, which places the window in front or its siblings. A value of t places the window behind all of its siblings. If the value is another window that is already on the owner window, the new window is placed immediately behind the specified window.
• :state: the initial state of the newly created window. Possible states are :normal (window has its normal size and is visible, this is the default); :shrunk (window is shrunken and not visible); :icon (window is shrunk to a visible icon); and :maximized (window is extended to its maximum size).

  When creating a window, the window is placed into its initial visible state (as specified by the :state initarg) by a device-open :around method. This means that if an application adds device-open methods (including :after methods) for its window subclasses, for example to set up child windows on the window, the main window will be shown only after this setup is complete, to avoid distracting the user and to increase creation speed. (An alternate approach is simply to create the main window in :shrunk state, then do arbitrary setup, and then set the state of the main window to :normal.)

• :exterior: a box (see make-box) in the coordinates of the parent that determines the initial position and size of the exterior boundary of the window. Note that if the new window is a non-child window, then the box should always be in screen coordinates, even if the window has an owner window.

  GTK Note: For a top-level window on the GTK platforms (Linux and Mac), you probably should always pass the interior argument rather than this argument or any of the others that apply to the exterior. The reason is that X11 makes it difficult or impossible (depending on the particular X server) to control the placement of the window manager frame of a top-level window, or even to determine its thickness. To make a cross-platform application work the same on Windows, the interior argument can be used universally. Child windows do not have this problem.

• :interior: an alternative to :exterior, in that the box specifies the boundary of the client (interior) area of the window, again in the coordinates of the parent. The frame of the window will protrude outward from this box as needed.
• :exterior-top-left: another alternative for the initial position. A position in the coordinates of the parent that determines the initial position of the top-left corner of the window. Another alternative is to pass individual coordinates using the :left and or :top arguments. If the window position is not determined by any make-window arguments or the default-initargs of the window class, then the initial position is determined by the default-top-left generic function.
• :width and :height: another alternative for the initial size. Integers specifying the exterior width and/or height of the window in pixels. If the width and/or height are not determined by any make-window arguments or default-initargs of the window class, then the initial size is determined by the default-width and/or default-height generic functions.
• :centered: specifies whether to initially center the window over the interior of its parent or owner. If nil (the default), then no centering is done. If :on-parent, then the window will be centered over its parent. For any other true value, the window will be centered over its owner. If an exterior or interior argument is passed along with a true centered argument, then the exterior or interior box will determine the size of the window while the centering will determine its position. A true centered argument would override an exterior-top-left argument. See also center-window and the centered property.
• :double-buffered: specifies whether the window uses a memory bitmap to reduce flashing when redrawing the window (not needed on GTK). This option is nil by default for backward compatibility and because it uses memory resources, but it is generally recommended to pass this initarg as true for any window on which an application draws. See double-buffered.

There are many other options (specified by initarg (a keyword)/value pairs) to make-window. In general, the initargs are keywords with the same name as properties, :left-attachment for left-attachment, e.g.)

make-window returns nil if a window cannot be created

make-window returns nil if the operating system fails to make the requested window. Such failure is typically due to one of the operating system's tables for all windows and menus becoming full. This situation should be rare, but if it does happen, your application should be modified to close any windows or menus that are no longer being used, in order to free up the corresponding operating system resources. Windows may be closed programmatically by calling close on them.

Copyright (c) 1998-2016, Franz Inc. Oakland, CA., USA. All rights reserved.
This page has had moderate revisions compared to the 8.1 page.
Created 2016.6.21.