A window is a subwindow of a frame
object. It appears on the screen as a rectangular area inside a frame.
It defines an infinite two-dimensional drawing plane of which a
rectangular sub-area is window<-visible.
A window optionally has window->scrollbars
attached that allows the user to move the visible rectangle over the
infinite plane.
Class window takes
care of the communication with its window<-frame
and the window system it uses for it's graphical representation.
As defined in class device,
a window can display graphical
objects (i.e. instances of one of the
subclasses of class graphical).
There are several kinds of windows:
->event.
This is not necessarily the same as @event.
Consider the case were the window has opened a popup. In this case window<-current_event
will point to the event that caused the popup to open (generally an
ms_right_down event), while @event
will point to the various events that are processed during the opened
state of the popup window.
->catch_all
creates a decorator for methods that are not defined on class window
and are defined by class window_decorator.
This allows for e.g.,
send(Window, scrollbars, both)
<->focus_cursor:
the window<->focus_cursor
<->cursor
the cursor of the object in focus
<->cursor
of the window. @see device->event
@see window-focus_cursor
@see graphical->cursor
@see window->focus
<-focus_recogniser
too is not @nil
the event will be posted to this recogniser only.
Note that keyboard events will be send to the window<-keyboard_focus
when this is not @nil.
<-focus
is not @nil),
this focus remains active until a button-up-event is received with this
button. When @nil,
the focus remains set till it is explicitly cleared.
<-focus
is not @nil,
this cursor will be displayed.
<-focus
is not @nil,
events are given to this
recogniser
object.
<-member.
If the window has no frame and is not displayed on another graphical and
create is @on
or @default a
default frame is attached to the window which is returned.
->event
and may be redefined, but should always invoke the primary
implementation.->input_focus.
When modified, and the
window<-keyboard_focus
is not @nil,
the method will generate either an activate_keyboard_focus or a
deactivate_keyboard_focus event to window<-keyboard_focus.
A graphical getting the keyboard focus will be sent an
obtain_keyboard_focus event. Graphicals loosing the
keyboard focus will be sent a release_keybaord_focus event.
->event.
@receiver The window @arg1 The window @arg2 New size of the window
This message is always sent when the associated frame is created.
Resizing a window may also be specified by redefining the
window->geometry
method. See also window<-visible
and dialog->layout.
window<-visible
is the proper way to get information on the current location of the
visible area of the window.
|elevation|colour*<-selected: @on
are visualised. Values:
<-foreground
and window<-background
colour.
.selection_handles.
Used (for example) in PceDraw.
<-colour
attribute, drawing the graphical using the colour specified here.
Suitable on colour devices only. Using a light-grey or otherwise
coloured window<-background
generally improves the result.
->fit.
It allows the window to resize itself to fit with its contents. By
default this method is only active for class dialog.
This method may be redefined.
|tileDepending on whether or not the argument is a window or a tile, the behaviour of this method is rather different. Using window argument is intended for initial creation of windows, while using a tile argument is intended for adding windows to an already open frame object:
vertical stack, place
the new window at the top of the stack. If the window is part of a horizontal
stack, create a vertical stack holding the receiver and stack of the
argument window. If the window is not part of a stack, create a vertical
stack holding both windows.
To align a window nicely above another window, use:
send(NewWindow, above, Old?tile).
To align a window above two horizontally aligned windows, use:
send(NewWindow, above, Old?tile?super).
If the receiver window is not already part of the same frame as the argument window it will be made part of this frame. Thus method may be used after one or both windows have been created.
The techniques chapter in the Users's Guide contains a
section on generation window layout in a frame.
|pixmapDefaults: The display<-background.
|tile->above,
but rhe receiver is placed below the argument.
->compute’.<-decoration, window<-frame
and window<-tile
while these slots are not yet filled. If the selector is found on any of
these classes, the corresponding object is associated to the window and
the message is delegated. This implementation ensures that messages like window_decorator->scrollbars,
frame->kind
and tile->hor_stretch
may always be send directly to the window.device when the union of
all graphicals has changed. Used to update the scrollbars accordingly.
See also window->update_scroll_bar_values.Defaults: When @default
is provided, display<-foreground
is used.
->create
establishes the resources for making the window visible. This method is
normally called from frame->open
and should not be used directly by the user.
->initialise.->destroy
for details.->expose.->alert,
which depending on the setting of the
window.visual_bell will either ring the bell
or flash the object.
Graphical is the graphical
object in focus. If Recogniser is not
@nil, events
are given to this particular recogniser
object. If Cursor is not @nil,
the cursor is set to this value until the focus is released. The Name
argument indicates the button that initiated the focus. If a button-up
event is received of this button, the focus will be released
automatically. If the value is @nil,
the focus remains active until a new window->focus
message is received.
See also window->grab_pointer
and window->grab_keyboard.
Defaults: The following defaults apply:
Recogniser @nil (None) Cursor @nil (Cursor is not changed) Button Button of the current event, computed with: Window?current_event?button
<-focus_cursor
variable and displayed cursor if the window has window<->focus
not equal to @nil.
The cursor is automatically reset if the focus of the window is set to @nil.
This method is often used by gestures to change the cursor while the
gesture is active.
->free
causes the entire frame and possible other windows that are part of the
frame to be freed.
If a window is just to be deleted from its window<-frame
use frame->delete.
->set, graphical->size, window->position
and other methods to manipulate the geometry that are inherited from
class graphical. It
sets the graphical<-area
of the window.
Note that the size and position of a window is dictated by its
associated window<-tile.
To change the layout of windows in a frame, please examine the behaviour
defined on class tile.
Windows delegate to their tile.
The normal XPCE event-processing ensures the window in which a mouse-down event occurrs grabs the pointer until the mouse-button is released (see also class gesture).
Most modern window environments do not allow a global grab on the pointer. Any event happening on any xpce window of the same process is redirected to this window.
See also window->focus
and window->grab_keyboard.
->hide.This will create a default frame for this window. When two windows
are related using window->above, window->below, window->left
or
window->right,
both windows will be made part of the same frame. The frame of the
receiver of the window->above,
etc. method will be destroyed and this window will be made part of the
frame of the argument window.
Defaults:
label untitledsize resource defined (see size resource) display @display
|tile->above,
but rhe receiver is placed left of the argument.
<-frame.|graphical|chain,
mode=[{xy,x,y}]object visible by scrolling the window. Object
is either an area, a graphical or a chain of graphicals. The area that
is made visible is the area itself, the area of the graphical or the
union of the areas of the graphicals in the chain.
If it is not possible to make the entire area visible, it is ensured the top-left corner of the area is visible.
If mode is x, the window is only scrolled horizontally.
Likewise if mode is y the window is only scrolled
vertically. In all other cases scrolling is performed in both
directions.
<-frame
and invokes frame->open
to realise the toplevel window on the given display. Some window
systems, notably Wayland, ignore the position argument.
|frame],
display=[display], grab=[bool]->open,
but the frame is centered around the given point.
Defaults: If no point is specified, the window is opened at the center of the display.
Defaults: 1
This method should be used with care. Users tend not to like jumping
mice. It is generally better to place a UI component close to the
pointer location (see event<-position)
than to place the UI component far away and jump the pointer towards it.
Class resize_gesture uses it to position the pointer exactly on the border of a graphical if it was depressed close to it.
Diagnostics: Succeeds without side-effects if the window is not displayed.
->event
with the same event, similar to the device->event
routine on normal graphical
objects. The distinction makes the function of device->event
the same on all graphical classes, simplifying code reuse. Redefinition
of window->post_event
should rarely be necessary.PCE is designed to take care of all visual side-effects automatically, so the user should never have to invoke methods explicitly. An exception on this rule are the decorations (scrollbars and label) of the window. If these are changed this method needs to be called explicitly to update the window.
<-current_event
to @nil and
releases a possible event-focus. Then invokes visual->reset
to take care of the graphicals displayed on it.
<-resize_message
is specified, this message is executed with the following arguments:
@receiver The window @arg1 The window (i .e. same)@arg2 The new size of the window
The new size is the area<-size
of the graphical<-area.
See also window<-visible
and dialog->layout.
<-resize_message
and executes it if the window has already been created. Arguments:
@receiver: The WIndow @arg1 Same as @receiver @arg2 Size object reflecting the new size
|tile->above,
but rhe receiver is placed right of the argument.
If the force argument is @on,
the scroll actions is performed unconditionally. Otherwise it is only
performed if the window has the associated scroll_bar
object. This ensures no scrolling is performed based on a wheel-mouse if
the window has no scroll_bar.
<-visible.
<->border
and offset caused by possible scrollbars and then invokes
`tile ->set: @default, @default, Width, Height`
Which will change the desired size. The associated frame then
decides on the actual size. If the associated frame is already created,
only the distribution of the windows inside the frame may be changed.
The frame itself won't be resized. The method frame->fit
requests the frame to resize its contents and itself to the most
desirable value.
Various subclasses of window redefined this method to make the unit of the size dependent on their font.
|event_id,
delegate=[bool]->event
if no graphical
object in the window accepted the typed key. The window will forward the
typed key to the frame using frame->typed
The frame in turn will check for another window (generally a dialog
object) that is capable of handling the typed key.
If delegate = @on
(as invoked from device->event)
it invokes window->typed
on
window<-frame.
->unlink,
this method takes care of the
window<-decoration
and the associated window-system window.->resize),
the bounding box of the content changed (see window->changed_union)
or the window was scrolled (see window->scroll_to).
It can be redefined to constrain other objects to these actions. The
redefined method must call this method to ensure proper update of the
windows window->scrollbars.
<-confirm
on its frame.
|frame],
display=[display], grab=[bool] -> any<-confirm,
but centers the frame of the window around the given position instead of
putting the top-left corner at the given position.
|device<-contained_in
for class window.
Windows normally appear as tiled objects in a frame
object. They can also be displayed as normal graphical
objects.
<-window.
Simplifies activating methods that accept a window as argument.<-colour.
<-position
of this area is the coordinate of the top-left corner of the window. Its
value is initially (0,0), but may be changed if the window is scrolled.
The window<-size is the size of the
visible area of the drawing plane.