SWI-Prolog -- Send methods

1.38.2 Send methods

device ->advance: from=[graphical]*, propagate=[bool], direction=[{forwards,backwards}]

Advance the keyboard-focus to the next graphical object of this device for which the test graphical->_wants_keyboard_focus succeeds. Used by text_item to implement text_item->advance.

This method cycles through the device<-graphicals chain. If the argument is a graphical and there is no graphical that requests the keyboard focus further down the device<-graphicals chain and the device is not the window itself, and propagate not is @off, it will invoke device->advance on its graphical<-device, passing itself as argument. This behaviour allows for handling the keyboard focus in dialog-windows built from nested devices.

Otherwise, If no graphical wants to have the keyboard focus, the keyboard focus of the graphical<-window is set to @nil.

Defaults: If graphical is @default, the first graphical accepting device->_wants_keyboard_focus is given the focus.

See also: - text_item->_wants_keyboard_focus
- text_item-advance
- window->keyboard_focus

device ->append_dialog_item: item=graphical, relative_to_last=[{below,right,next_row}]

Append a graphical object using the dialog-layout mechanism. This method may be used to define sub-dialogs. See‘dialog device->append’for details.

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

If the union of the displayed graphicals (see area->union) has changed, this method is called. The arguments indicate the old union of the graphicals. This method may be used to implement custom scroll_bar objects with figure objects.

device ->clear: [{destroy,free,erase}]

Remove all graphicals from the device. The argument controls what happens to the removed graphicals. By default it uses device->erase, leaving destruction to the reference-count garbage collector. Using free the graphicals will be send a object->free, ensuring destruction of the graphicals, but not their parts and using destroy ensures deep destruction of the displayed graphicals based on visual->destroy.

See also: device->erase

device ->compute:

Send device->compute to all members of -recompute, next recomputes the device<-format if requested by -bad_format and finally recomputes the graphical<-area (bounding box) requested by -bad_bounding_box.

device ->display: graphical, position=[point]

Display a graphical object on the device. This is the principal way of drawing on a device. It performs the following operations:

if point is not @default, invoke graphical->set with the X and Y values of the point.
invoke graphical->device
invoke graphical->displayed Note that the geometry management may be redefined for each graphical using graphical->geometry. Also graphical ->device' and graphical graphical->displayed‘may have been redefined.
Defaults: If point is omitted, the current position of the graphical is used. For graphicals that were never displayed, this is usually (0,0)

See also
- graphical->reparent
- graphical->display_on
- graphical-displayed
- graphical-device

device ->erase: graphical

Erase a graphical from the device. The graphical is removed from the device<-graphicals chain of the device, the graphical's graphical<-device is set to @nil and the display is updated.

Note that the graphical is only destroyed if it had no other references. To make sure the graphical is destroyed, use object->free. To be sure all sub-graphicals are removed as well, use visual->destroy.

See also: - graphical->reparent
- device->clear

device ->event: event

Process an event. It performs the following operations:

Update device<-pointed and generate area_enter and area_exit events to graphicals that were added/removed from this chain. Implemented by device->update_pointed
Post the event to the elements on device<-pointed using event->post. If event->post succeeds on some graphical, stop with success.
Activate graphical->event to process recognisers defined on the device.

See also
- device->update_pointed
- graphical->event
- event->post

device ->for_all: [name], code

Run code on all graphicals with given graphical<->name. Stops with failure executing code fails for some graphical. If name is @default, code is executed on all member graphicals, which makes the method equivalent to

send(Dev?graphicals, for_all, Code)

See also: - device->for_some
- chain->for_all
- device-graphicals

device ->for_some: [name], code

Run code on all member graphicals that have graphical<-name equal to name. The exit status is ignored and device->for_some always succeeds. If name is @default, code is run on all device<-graphicals in the device object.

Defaults: If name is @default, code is executed on all member graphicals.

See also: - device->for_all
- device-graphicals

device ->foreground: colour

The foreground colour of a device determines the colour used to draw member graphicals that have graphical<-colour not equal to @default. Device ->foreground' is equivalent to Graphical graphical->colour‘.

See also: - graphical->colour
- class colour

device ->format: format*|name, [any]

This method has two modes of operation:

Device device->format: format* Attaches a format object to a device. This implies the graphicals are placed in a two-dimensional grid.
Device device->format: name, value Change an attribute of the associated format object and recompute the layout of the graphicals in the device according to the new format.
See class format for details.

See also
class format

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

device->geometry updates device<-offset (the offset of the device's coordinate system relative to its super-device) such that the top-left corner is at (X, Y).

The graphical<-width and graphical<-height of a device is defined to be the union of the area of the member graphicals (intersected with device<-clip_area) and the W and H parameters of the geometry request are thus ignored.

See also: graphical->geometry

device ->initialise:

Create an empty device.

device ->layout_dialog: gap=[size], size=[size], border=[size]

This method implements the layout of dialog objects (see dialog->layout). It may be used to define compound dialog windows or to exploit the layout mechanism for dialog windows in a normal window or graphical device.

device ->modified_item: graphical, bool

Virtual method, fails. Dialog item's send this message to their device after they have been modified. If this message succeeds, they assume the dialog is an attribute editor and will not forward their device<-message. Otherwise they will immediately forward their device<-message. See also dialog->modified_item.

device ->move: point

Move the origin of the device to be at point. Note that this need not be the top-left corner. To set the top-left corner, use‘Device graphical->set: X, Y’.

See also: - device->y
- device->x
- device->position

device ->position: point

Inherits description from: device-offset

See also: - device-offset
- device->move

device ->reference: [point]

Move the reference-point (offset) of the device to be at point, but move the member graphicals the same amount in the other direction, such that they remain displayed at the same position.

The default reference point is the top-left corner of the bounding box of all the member graphicals.

device ->reparent:

Called from PCE graphics kernel if something has changed to the graphical<-device organisation up in the graphical<-device hierarchy. This general method performs the following:

Updates device<-level to reflect the distance to the top-most graphical device.
Sends device->reparent to all its member graphicals
Invoked graphical->reparent on itself See graphical->reparent for details.

See also
graphical->reparent

device ->resize: x_factor=real, y_factor=[real], origin=[point]

Resize the member graphicals of the device in X and Y direction. See graphical->resize for details on the parameters.

Defaults:

The following defaults apply:

Y-resize factor (2nd argument) defaults to the X-resize-factor (1st argument).
The resize origin defaults to device<-position (origin) of the device
Bugs:

The contents are resize by sending graphical->resize to each graphical. If graphicals are related using constraints the result may be incorrect.

See also
graphical->resize

device ->room: area

Test if there are no graphicals that have‘Graphical graphical<->displayed: @on’and overlap with area on the device. See also device<-inside.

See also: device<-inside

device ->selection: graphical|chain*

Set the member graphicals that have graphical<->selected. If the argument is a graphical, this graphical will be selected. If it is a chain of graphicals, each member of this chain will be selected. If the argument is @nil, no graphical will be selected.

All graphicals displayed on this device, except for the indicated one's will be deselected.

See also: - device<-selection
- graphical-selected

device ->unlink:

device->erases all device<-graphicals from the device and then calls graphical->unlink. Note that erased graphicals are only garbage-collected if they have no references from other objects. See also‘visual visual->destroy.

device ->update_pointed: event

Update the device<-pointed chain to represent all graphicals displayed on the device for which event is in the event_area. Graphicals that are deleted from the chain are send an area_exit event. Graphicals that are added to the chain are send an area_enter event. If on or more of the mouse-buttons are down, these events are area_cancel and area_resume.