1.63.3 Send methods

frame ->initialise: label=[name], kind=[{toplevel,transient,popup}], display=[display], application=[application]

Create a frame from its label, kind, display and (optional) application. Frames are often created implicitly as a side-effect of creating a window.

Defaults:

label		untitled
kind		toplevel
display	@display

frame ->unlink:

Destroy the frame and all its member windows. Transients are sent object->free.

frame ->reset:

Cancel any active frame->busy_cursor and restore the normal cursor.

frame ->convert_old_slot: slot=name, value=any

Backward-compatibility hook used when loading saved frames: translates the legacy show slot into frame<-status.

frame ->initialise_new_slot: var=variable

Initialise newly-introduced slots (currently background) when loading older saved instances.

frame ->display: display

React to a display change (e.g. when the host moves the frame to another monitor). Applications normally do not call this.

frame ->append: subwindow=window

Append a window to the frame. Typical when assembling a frame from several sub-windows:

:- pce_begin_class(mail, frame, "Simple mail tool").

initialise(M) :->
        "Create mail tool"::
        send(M, send_super, initialise, mail),
        /* append the various parts to the tool */
        send(M, append, new(B, browser)),
        send(M, append, new(V, view)),
        send(M, append, new(D, dialog)),
        /* specify the layout of the parts in the tool */
        send(V, below, B),
        send(D, below, V),
        ...

See also

- topic Window Layout
- window->above

frame ->delete: member=window

Remove a window from the frame. See also frame->append, window->left, window->above, ...

frame ->fit:

Recompute the layout of the sub-windows and resize the frame to fit the tiled result. Internally:

• tile->enforce on the root tile;
• window->_compute_desired_size on each sub-window (currently only dialog implements this);
• tile->enforce on the root tile;
• frame->set to the root-tile's ideal width/height. Normally called from frame->create; user code calls it after runtime layout changes (e.g. after graphical->size or after modifying a dialog window).

  See also

  - frame->create
  - frame->set
  - dialog->_compute_desired_size
  - tile->enforce

frame ->resize:

Recompute the layout of the sub-windows in response to the OS resizing the frame.

frame ->update_tile_adjusters: [tile]

Walk the frame<-tile hierarchy and create a tile_adjuster object for each tile whose frame<-can_resize is @on; free adjusters of non-resizable tiles. Called from frame->create.

frame ->set: x=[int], y=[int], width=[int], height=[int], display=[display]

Modify the client area (without title-bar/borders). Window system constraints may clamp the actual values.

When the frame is already shown, the request is sent asynchronously to the OS; the slots are updated when the OS confirms. A successful size change triggers frame->resize.

See also

- frame->size
- frame->position
- frame->geometry

frame ->size: size=size

Equivalent to frame->set.

frame ->width: width=int

frame ->height: height=int

frame ->x: x=int

frame ->y: y=int

Convenience wrappers around frame->set that change one axis.

frame ->position: position=point

Set the top-left position of the frame. Equivalent to frame->set with the point's x and y.

frame ->move: position=point

Alias for frame->position.

frame ->center: center=[point], display=[display]

Move the frame so the given point becomes its centre. Requires the frame to be already created.

frame ->area: area

frame->set from the four fields of the argument area.

frame ->geometry: geometry=name, display=[display]

Parse the geometry specification and apply it (immediately if the frame is open, otherwise stored for frame->create). The syntax is

<width>x<height>[+-]<X>[+-]<Y>[@<monitor>]

All five components are optional. A negative X / Y is measured from the right / bottom edge of the screen. Example:

400x200+0-0

means a 400x200 frame anchored at the bottom-left. The size applies to the client area; the position to the frame including borders.

The @<monitor> suffix, where <monitor> is a value from display_manager<-members, picks the monitor used as the origin. This syntax follows the FVWM convention. If the display argument is given explicitly, @<monitor> is ignored.

See also

- frame->set
- frame.geometry

frame ->create:

Realise the frame in the window system:

1. Succeed immediately if already created.
2. Open frame<-display if needed.
3. Append the frame to display<-frames.
4. frame->fit to lay out sub-windows.
5. Create the OS window.
6. frame->create each member window.
7. Update cursors.
8. Set the transient-for relationship (if any).
9. Apply -geometry if set. 10. frame->update_tile_adjusters.

   See also

   - frame->open
   - display<-frames
   - frame->fit

frame ->uncreate:

Destroy the OS counterpart, leaving the xpce object intact for later reuse.

frame ->open: position=[point], display=[display], grab=[bool]

Open the frame at the given position:

1. frame->create if not yet created.
2. frame->set the position if supplied.
3. frame->status. If grab is @on the frame grabs the pointer (see window->grab_pointer).

   See also

   - frame->open_centered
   - frame->set
   - frame->create
   - window->open

frame ->open_centered: center=[point|frame], display=[display], grab=[bool]

Like frame->open but centres the frame on the given point (or the centre of frame<-display if omitted).

frame ->show: show=bool

Show (@on) or hide (@off) the frame on the display. When a frame becomes shown its transients are shown too. See also frame->open and frame->status.

frame ->mapped: bool

Called when the OS reports the frame mapped (@on) or unmapped (@off). Triggers frame->show on transients to follow the main frame.

frame ->wait:

Dispatch events until the frame has been mapped and its windows have processed at least one redraw request. Used to force the frame visible during a long computation. See also frame->flush and frame->synchronise.

frame ->status: {unmapped,hidden,iconic,window,full_screen,open}

Set the frame's visibility status (see frame<-status). open is a synonym for window.

frame ->closed: open=bool

Compatibility shortcut: frame->closed opens the frame (frame->status), frame->closed iconifies it.

See also

- frame<-closed
- frame->status

frame ->expose:

Raise the frame to the top of the window stack. Internally calls frame->closed (in case the frame was iconic) and then asks SDL to raise the OS window. On success frame->exposed is invoked via the resulting OS event.

See also

- frame<-postscript
- frame->closed

frame ->exposed:

Invoked when the OS reports the frame raised. Sends frame->expose to each transient frame.

See also

- frame->hidden
- frame<-transients

frame ->hidden:

Invoked when the OS reports the frame hidden (lowered or minimised). Sends frame->hide to each transient frame.

See also

- frame->exposed
- frame->transient_for

frame ->label: label=name

Set the title shown in the frame's decorations. Whether and how the label appears is up to the OS theme.

frame ->bell: volume=[int]

Ring the bell on the display hosting the frame.

See also

- display.volume
- display->bell

frame ->busy_cursor: cursor=[cursor]*, block_input=[bool]

Show a temporary cursor (default frame.busy_cursor) on every sub-window of the frame. When block_input is @on, all pointer and keyboard events are blocked while the cursor is active. frame->busy_cursor restores the normal cursor and re-enables input.

See also

display->busy_cursor

frame ->cursor: [cursor]

Set the cursor shown over the frame's decoration / background (i.e. when the pointer is on the area between sub-windows). Used by frame->event while resizing tiles.

frame ->input_focus: bool

Receive notification from the window system that this frame has (@on) or has lost (@off) keyboard focus. Forwards to frame<-keyboard_focus or the window currently under the pointer.

frame ->input_window: window

Direct all keyboard events arriving on this frame to the indicated window. Appropriate when only one sub-window contains keyboard-sensitive controls.

frame ->keyboard_focus: [window]*

When set to a window, all keyboard input arriving at any sub-window is redirected there. The argument need not be a member of the frame. @nil/@default makes keyboard input follow the pointer.

frame ->event: event

Handle an event that landed on the frame's background or decoration. Two cases are dispatched:

• keyboard event with an frame<-input_focus window: forward to that window;
• pointer on a sub-window boundary: indicate / perform a resize drag.

frame ->post_event: event

Re-dispatch a keyboard event that wasn't consumed elsewhere. Fails by default.

frame ->typed: event|event_id

Distribute a typed key across the frame's sub-windows so any window can accept it as an accelerator.

frame ->return: unchecked

Make a blocking frame<-confirm call on this frame return with the given value. Stores it in -return_value.

See also

- frame<-confirm
- frame-return_value

frame ->report: kind={status,inform,progress,done,warning,error,fatal}, format=[char_array], argument=any ...

Redefinition of visual->report that walks a frame's report chain:

1. Call visual<-report_to; if it returns a value other than frame<-display, forward frame->report there.
2. Try frame->report on each frame<-members window until one succeeds. Windows by default delegate back to their frame, so the loop detects and breaks this cycle.
3. If the frame is transient, forward to frame<-transient_for.
4. Fall back to visual->report.

frame ->wm_protocol: protocol=name, action=code

Register a handler for an OS protocol message. The name is matched against incoming protocol events; on a match the code is executed with @receiver set to the frame and @arg1 to its first window.

Historically these names matched X11's WM_PROTOCOLS messages, notably WM_DELETE_WINDOW (close request) and WM_SAVE_YOURSELF (session save). On SDL3 only the close-request path remains; the others are accepted but never triggered.

See also

- frame<-wm_protocols
- frame->save_message
- frame->done_message
- frame->delete_wm_protocol

frame ->delete_wm_protocol: protocol=name

Remove a protocol handler installed with frame->wm_protocol.

frame ->done_message: action=code

Shortcut for frame->wm_protocol. Default: message(@receiver, wm_delete).

See also

- frame->wm_delete
- frame->wm_protocol

frame ->save_message: action=code

Shortcut for frame->wm_protocol. Kept for completeness; SDL3 does not emit this event.

frame ->wm_delete:

Default action for an OS close request:

1. Fail if frame<-can_delete is @off.
2. If frame<-confirm_done is @on, pop up display->confirm. Fail if the user cancels.
3. visual->destroy the frame. @see frame->done_message @see frame<-can_delete @see frame<-confirm_done

frame ->show_label: show=bool

Compatibility alias: @on is equivalent to frame->kind, @off to frame->kind. New code should use frame->kind.

frame ->transient_for: frame*

Declare this frame as a transient (e.g. dialog or inspector) for the argument frame. Effects:

• The OS is told about the relationship so it can stack and iconify the transient with its parent.
• When the parent is destroyed, mapped, exposed or hidden, the same action is propagated to its transient frames.

  See also

  - frame->unlink
  - frame<-transient_for
  - frame<-transients

frame ->attach_transient: frame

frame ->detach_transient: frame

Maintain the frame<-transients chain. Called by frame->transient_for and frame->unlink; user code rarely invokes them directly.

frame ->redraw: [area]

Redraw the resize-handle widgets between sub-windows. Used after layout changes.