On this page:
Version: 4.2.1

frame% : class?

  superclass: object%

  extends: top-level-window<%>
A frame is a top-level container window. It has a title bar (which displays the frame’s label), an optional menu bar, and an optional status line.

Under Windows, both Multiple Document Interface (MDI) and Single Document Interface (SDI) frames are supported.

(new frame% [label label] 
  [[parent parent] 
  [width width] 
  [height height] 
  [x x] 
  [y y] 
  [style style] 
  [enabled enabled] 
  [border border] 
  [spacing spacing] 
  [alignment alignment] 
  [min-width min-width] 
  [min-height min-height] 
  [stretchable-width stretchable-width] 
  [stretchable-height stretchable-height]]) 
  (is-a?/c frame%)
  label : label-string?
  parent : (or/c (is-a?/c frame%) false/c) = #f
  width : (or/c (integer-in 0 10000) false/c) = #f
  height : (or/c (integer-in 0 10000) false/c) = #f
  x : (or/c (integer-in -10000 10000) false/c) = #f
  y : (or/c (integer-in -10000 10000) false/c) = #f
  style : 
(listof (one-of/c 'no-resize-border 'no-caption
                  'no-system-menu 'hide-menu-bar
                  'mdi-parent 'mdi-child
                  'toolbar-button 'float 'metal))
   = null
  enabled : any/c = #t
  border : (integer-in 0 1000) = 0
  spacing : (integer-in 0 1000) = 0
  alignment : 
(list/c (one-of/c 'left 'center 'right)
        (one-of/c 'top 'center 'bottom))
   = '(center top)
  min-width : (integer-in 0 10000) = graphical-minimum-width
  min-height : (integer-in 0 10000) = graphical-minimum-height
  stretchable-width : any/c = #t
  stretchable-height : any/c = #t
The label string is displayed in the frame’s title bar. If the frame’s label is changed (see set-label), the title bar is updated.

The parent argument can be #f or an existing frame. Under Windows, if parent is an existing frame, the new frame is always on top of its parent. Also, the parent frame may be an MDI parent frame from a new MDI child frame. Under Windows and X (for many window managers), a frame is iconized when its parent is iconized.

If parent is #f, then the eventspace for the new frame is the current eventspace, as determined by current-eventspace. Otherwise, parent’s eventspace is the new frame’s eventspace.

If the width or height argument is not #f, it specifies an initial size for the frame (in pixels) assuming that it is larger than the minimum size, otherwise the minimum size is used.

If the x or y argument is not #f, it specifies an initial location for the frame. Otherwise, a location is selected automatically (tiling frames and dialogs as they are created).

The style flags adjust the appearance of the frame on some platforms:

If the 'mdi-child style is specified, the parent must be a frame with the 'mdi-parent style, otherwise an exn:fail:contract exception is raised.

Even if the frame is not shown, a few notification events may be queued for the frame on creation. Consequently, the new frame’s resources (e.g., memory) cannot be reclaimed until some events are handled, or the frame’s eventspace is shut down.

For information about the enabled argument, see window<%>. For information about the border, spacing, and alignment arguments, see area-container<%>. For information about the min-width, min-height, stretchable-width, and stretchable-height arguments, see area<%>.

(send a-frame create-status-line)  void?
Creates a status line at the bottom of the frame. The width of the status line is the whole width of the frame (adjusted automatically when resizing), and the height and text size are platform-specific.

See also set-status-text.

(send a-frame get-menu-bar)
  (or/c (is-a?/c menu-bar%) false/c)
Returns the frame’s menu bar, or #f if none has been created for the frame.

(send a-frame has-status-line?)  boolean?
Returns #t if the frame’s status line has been created, #f otherwise. See also create-status-line.

(send a-frame iconize iconize?)  void?
  iconize? : any/c
Iconizes (minimizes) or deiconizes (restores) the frame. Deiconizing brings the frame to the front.

A frame’s iconization can be changed by the user, and such changes do not go through this method. A program cannot detect when a frame has been iconized except by polling is-iconized?.

(send a-frame is-iconized?)  boolean?
Returns #t if the frame is iconized (minimized), #f otherwise.

(send a-frame is-maximized?)  boolean?
Under Windows and Mac OS X, returns #t if the frame is maximized, #f otherwise. Under X, the result is always #f.

(send a-frame maximize maximize?)  void?
  maximize? : any/c
Specification: Maximizes or restores the frame under Windows and Mac OS X; the frame’s show state is not affected. Under Windows, an iconized frame cannot be maximized or restored.

A window’s maximization can be changed by the user, and such changes do not go through this method; use on-size to monitor size changes.

Default implementation: If maximize? is #f, the window is restored, otherwise it is maximized.

(send a-frame modified)  boolean?
(send a-frame modified modified?)  void?
  modified? : any/c
Gets or sets the frame’s modification state as reflected to the user. Under Mac OS X, the modification state is reflected as a dot in the frame’s close button. Under Windows and X, the modification state is reflected by an asterisk at the end of the frame’s displayed title.

(send a-frame on-mdi-activate active?)  void?
  active? : any/c
Called under Windows when a MDI-child frame becomes the active frame within its parent (in which case the argument is #t), or when the child frame ceases to be the active frame (in which case the argument is #f).

MDI activation is different from keyboard-focus activation. If the parent frame is the frontmost top-level frame, so that the MDI child gets or loses the keyboard focus, then a separate on-activate notification is sent to the MDI-child frame.

(send a-frame on-menu-char event)  boolean?
  event : (is-a?/c key-event%)
If the frame has a menu bar with keyboard shortcuts, and if the key event includes a Control, Alt, Option, Meta, Command, Shift, or Function key, then on-menu-char attempts to match the given event to a menu item. If a match is found, #t is returned, otherwise #f is returned.

When the match corresponds to a complete shortcut combination, the menu item’s callback is called (before on-menu-char returns).

If the event does not correspond to a complete shortcut combination, the event may be handled anyway if it corresponds to a mnemonic in the menu bar (i.e., an underlined letter in a menu’s title, which is installed by including an ampersand in the menu’s label). If a mnemonic match is found, the keyboard focus is moved to the menu bar (selecting the menu with the mnemonic), and #t is returned.

(send a-frame on-subwindow-char receiver    
  event)  boolean?
  receiver : (is-a?/c window<%>)
  event : (is-a?/c key-event%)
Returns the result of

  (or (send this on-menu-char event)
      (send this on-system-menu-char event)
      (send this on-traverse-char event))

Under Mac OS X, called when the user clicks the toolbar button on a frame created with the 'toolbar-button style.

(send a-frame set-icon icon [mask which])  void?
  icon : (is-a?/c bitmap%)
  mask : (is-a?/c bitmap%) = #f
  which : (one-of/c 'small 'large 'both) = 'both
Sets the large or small icon bitmap for this frame. Future changes to the bitmap do not affect the frame’s icon.

The icon is used in a platform-specific way:

The bitmap for either icon can be any size, but most platforms scale the small bitmap to 16 by 16 pixels and the large bitmap to 32 by 32 pixels.

If a mask bitmap is not provided, then the entire (rectangular) bitmap is used as an icon.

If a mask bitmap is provided, the mask must be monochrome. In the mask bitmap, use black pixels to indicate the icon’s region and use white pixels outside the icon’s region. In the icon bitmap, use black pixels for the region outside the icon.

(send a-frame set-status-text text)  void?
  text : string
Sets the frame’s status line text and redraws the status line. See also create-status-line.