1.73.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 ->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 ->shortcut: event

A key typed in any window of the frame is offered to this method first, after the key that opens the menu bar (see frame.menu_bar_key). If it succeeds the key is used up; otherwise it goes to the window with the keyboard focus. Fails by default. Class pane_frame of the IDE uses it to switch tabs with Control-Page-Up and Control-Page-Down.

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 ->sdl_test_event: type=name, fields=sheet

For testing only. Build an SDL event of type for this frame and process it as if SDL reported it. This allows testing input that is not available on the test machine, such as pen and touch input. type is one of mouse_motion, mouse_button_down, mouse_button_up, mouse_wheel, pen_proximity_in, pen_proximity_out, pen_down, pen_up, pen_motion, pen_button_down, pen_button_up, pen_axis, finger_down, finger_up, finger_motion, finger_canceled, pinch_begin, pinch_update, pinch_end, key_down, key_up and text_input. The attributes of fields are named after the fields of the SDL event structure (e.g., x, y, which, button, pressure); missing fields are 0. Positions are relative to the frame, except for the finger events, whose x and y are normalised to 0..1 as in SDL. The wheel event takes dx, dy (precise) and integer_x, integer_y (whole notches). The key events take key (the SDL keycode), scancode, mod and repeat, and text_input takes char, the code point of the text.

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.