10.5 Relating frames

Applications may consist of multiple frames, either permanent, or temporary such as for opening a `settings' window. This section discusses how frame references can be found, as well as how frames can force the user to deal with this frame first, in favour of all the other frames of the application: modal frames.

10.5.1 Class application

The class application is the key to this section. An application is a subclass of visual, and optionally located between display and frame in the visual consists-of hierarchy. It defines the `application<-member' method to located named frames, and thus supports locating frames similar to other graphicals as described in section 10.4.

A frame is made part of an application using the method `frame->application'. The application to which a frame is related may be changed. Frames are not required to be part of an application.

frame ->application: application*

Changes the application object the receiver belongs too. Combining multiple frame objects in an application allows for finding frames as well as defining modal relations between frames. See `frame->modal'.

The application to which a frame belongs may be changed at any time. Using the @nil argument, to frame is detached from any application.

This method invokes `application->delete' to the application currently holding the frame (if any) and `application->append' to the application receiving the frame. These methods may be redefined if an application wants to keep track of its associated frames.

application <-member: name

frame Return the frame for which `frame<-name' returns the argument name. See also `device<-member' and section 10.4.

10.5.2 Transient frames

The term transient window is taken from X11. A transient window (frame) is a frame that supports another frame. Transient windows are normally used for prompting. The related method is:

frame ->transient_for: frame

Make the receiver a transient window for the argument. This notion is handed to the X11 window manager, but the support varies. Therefore XPCE ensures that:

• The transient window stays on top
  Whenever the main window is raised, the transient window is raised too, ensuring the transient window does not get hidden behind the main window.
• Synchronise status change and destruction
  Status change (see `frame->status: {unmapped,hidden,iconic,open}') of the main window are forwarded to the transient windows. If the main window is destroyed, so is the transient window.

10.5.3 Modal operation

The method `frame->modal' works in combination with class application and transient frames to define what frames are temporary insensitive to events, forcing the user to operate on the modal frame first.

frame ->modal: {application,transient}*

Operate as a modal frame for all frames in the <-application, the frame I am <-transient_for, or none. A common sequence to display a modal dialog window centered on a frame is below. Note that, instead of `frame ->open_centered', one could also have used `frame<-confirm_centered'.

settings(Frame) :->
        "Open settings dialog"::                      
        new(D, dialog(settings)),
        send(D, transient_for, Frame),
        send(D, modal, transient),
        ...,
        <fill the dialog>,
        ...,
        send(D, open_centered, Frame?area?center).

Instead of using the center of a frame, the method can also use the location of @event to position itself. The code fragment for that is:

        ...,
        (   send(@event, instance_of, event)
        ->  get(@event, position, @display, EventPos)
        ;   EventPos = @default)
        ),
        send(D, open_centered, EventPos).