1.185.3 Send methods

window ->_compute_desired_size:

This method is invoked by class frame to as part of frame->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.

window ->above: window|tile

Part of the definition of the layout of windows inside a frame. Requests the receiver to be placed above the argument window.

Depending 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:

• window object argument If the window is part of a 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.
• tile object argument Align the receiver immediately above the argument tile, giving it the same width. If the argument is part of a vertical stack, insert the receiver at the proper location in the stack. If the argument is part of a horizontal stack, create a vertical stack holding the argument and the receiver, and let this new tile object replace the argument tile in the tile hierarchy.

  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.

  See also

  - frame->append
  - window-frame
  - topic Window Layout
  - window->right
  - window->left
  - window->below

window ->background: colour|pixmap

Colour of the drawing plane. Changing the colour forces a redraw.

Defaults: The display<-background.

See also

- window->foreground
- display-background

window ->below: window|tile

Similar to window->above, but rhe receiver is placed below the argument.

See also

- topic Window Layout
- window->above

window ->bubble_scroll_bar: scroll_bar

Update bubble of given scroll_bar object. Called by‘scroll_bar window->compute’.

window ->catch_all: name, unchecked ...

Handle delegation to window<-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.

window ->changed_union: ox=int, oy=int, ow=int, oh=int

This method is invoked from class device when the union of all graphicals has changed. Used to update the scrollbars accordingly. See also window->update_scroll_bar_values.

window ->foreground: [colour]

window ->colour: [colour]

Set the default colour for all graphicals displayed on this window: each graphical that has its colour set to @default will be displayed in the colour specified. If the window is displayed, it will be redrawn.

Defaults: When @default is provided, display<-foreground is used.

See also

- window->foreground
- graphical<-display_colour
- window<-foreground
- class colour

window ->create: [window]

window->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.

See also

- frame->create
- window->open

window ->decorate: area=[{grow,shrink}], left_margin=[int], right_margin=[int], top_margin=[int], bottom_margin=[int], decorator=[window]

Attach a window_decorator object to this window for displaying scroll_bar objects or a label. This method is used by window_decorator->initialise.

window ->destroy:

Destroys the associated window. See visual->destroy for details.

window ->expose:

Exposes (take to the front) the frame of the window on its screen. Invokes frame->expose.

window ->flash: area=[area], time=[int]

Flashes the window by temporary inverting it. Normally, applications should invoke graphical->alert, which depending on the setting of the window.visual_bell will either ring the bell or flash the object.

See also

- graphical.visual_bell_duration
- graphical.visual_bell
- graphical->bell
- graphical->alert

window ->flush:

Updates all graphicals in this window and requests a redraw for the window system.

See also

- graphical->flush
- display->flush

window ->focus: graphical*, [recogniser]*, [cursor]*, [name]*

Forward events arriving on this window to some graphical. This method is normally used only by class gesture to process all events starting with a mouse-down and ending with the mouse-up of the same mouse-button.

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

See also

- graphical->focus
- window-focus_button
- window-focus
- window-displayed_cursor
- window->grab_pointer
- class gesture
- window->keyboard_focus
- event->post
- window->focus_cursor

window ->focus_cursor: cursor*

Changes the window<-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.

See also

- class cursor
- window-focus_cursor
- graphical->focus_cursor
- window->focus

window ->free:

window->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.

window ->geometry: x=[int], y=[int], width=[int], height=[int]

Traps the graphical->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.

window ->grab_pointer: bool

If @on is specified, all subsequent events will be reported as if they happened on this window. @off should be used to resume normal event-processing.

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.

See also

- window-grab_pointer
- window->grab_keyboard
- display->inform
- window->focus

window ->hide:

Hides (put at the back) the frame of the window on its screen. Redefines graphical->hide.

window ->initialise: label=[name], size=[size], display=[display]

Create a window object from its label, size and the display on which is has to be displayed.

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	untitled
size	resource defined (see size resource)
display	@display

See also

class frame

window ->keyboard_focus: graphical*

Direct keyboard events to the given graphical.

See also

- window-keyboard_focus
- device->advance
- window->focus

window ->left: window|tile

Similar to window->above, but rhe receiver is placed left of the argument.

See also

- topic Window Layout
- window->above

window ->position: point

Position in window<-frame.

window ->x: int

Move graphical horizontally.

window ->y: int

Move graphical vertically.

window ->move: point

Class window redefines the inherited placement methods of class device to be equivalent to those of class graphical again. Class device defines the position to be the origin of the coordinate system, while the position of a window is the position of the top-left corner as with class graphical.

window ->normalise: on=area|graphical|chain, mode=[{xy,x,y}]

Try to make 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.

See also

- window->scroll_to
- window<-visible

window ->open: [point], display=[display]

Ensures the window has a window<-frame and invokes frame->open to realise the toplevel window on the given display. Some window systems, notably Wayland, ignore the position argument.

See also

- frame->open
- window<-confirm
- window->open_centered
- window->create

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

Equivalent to window->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.

See also

- frame->open_centered
- window<-confirm_centered
- window->open

window ->pen: 0..

Thickness of the line surrounding the window.

Defaults: 1

See also

window->border

window ->pointer: point

Move the pointer to the indicated position, which is in the same coordinate system as the graphicals displayed in the window. The pointer needs not be in the window, nor need the indicated coordinate be inside the window.

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.

See also

graphical->pointer

window ->post_event: event

Handle events comming from the underlying windowing system. This method deals with focus handling, cursor managements, etc. For normal unfocussed events is calls device->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.

window ->redraw: [area]

Redraw the entire window or some area of it. This method is normally invoked automatically if the window is opened on the display or part of it is exposed after it has been obscured by other windows.

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.

window ->reset:

Assigns window<-current_event to @nil and releases a possible event-focus. Then invokes visual->reset to take care of the graphicals displayed on it.

See also

visual->reset

window ->resize:

Invoked from the low-level window interface after the window has been resized for any reason. If window<-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.

window ->resize_message: code*

Set the variable window<-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

See also

window-resize_message

window ->right: window|tile

Similar to window->above, but rhe receiver is placed right of the argument.

See also

- topic Window Layout
- window->above

window ->scroll_vertical: direction={forwards,backwards,goto}, unit={page,file,line}, amount=int, force=[bool]

Trap message from vertical scrollbar.

window ->scroll_horizontal: direction={forwards,backwards,goto}, unit={page,file,line}, amount=int, force=[bool]

Traps a scroll-request from the horizontal scrollbar or a wheel-mouse. See class scroll_bar for details.

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.

See also

- window->scroll_vertical
- class scroll_bar
- scroll_bar-object

window ->scroll_to: point

Point is in the coordinate system of the graphicals displayed in the window. Makes this point the top-left corner of the window. Windows can scroll both the positive and negative coordinates. See also window<-visible.

See also

window->normalise

graphical ->size: size

Argument is the desired size in pixels. This method enlarges the requested size with the window<->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.

See also

- window-display_area
- frame->fit
- window->display_size

window ->typed: event|event_id, delegate=[bool]

Handle accelerator bindings. This method is normally invoked from device->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.

window ->uncreate:

Destroy associated window system resources. This method is used internally when a window is deleted from another window or its frame.

window ->unlink:

In addition to device->unlink, this method takes care of the window<-decoration and the associated window-system window.

window ->update_scroll_bar_values:

This message is sent to the window object if either the window is resized (see 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.