A (graphical) device is a collection of graphical objects. As device itself is a graphical objects; devices may be nested. Class device describes the management of such a collection: adding (displaying) graphical objects; erasing graphical objects; changing them; dispatching events over their displayed graphical objects; etc.
Devices communicate changed area's to their super-device and eventually to the window, which takes care of planning and executing the actual redisplay of the X-window.
The PCE-user normally uses the behaviour of devices via the classes figure or one of the sub-classes of window. Class device itself may be used for the definition of compound graphical objects.
The graphical<-area
of a device is by definition the bounding box of all
graphical<-displayed graphical
objects.
The variable is defined at the level of class device for technical reasons. The clip_area mechanism is activated at the level of class figure.
Defaults: @nil (no clipping is done).
If a device has a device<-format,
graphicals cannot be moved any more. Also, the position argument of device->display
is simply ignored.
->expose
and friends to change the stacking order of overlapping graphicals.
The contents of this chain may be queried but not changed. Use the
manipulation behaviour defined on devices and graphicals to change the
contents of the device. Note that the collection enumeration
methods
device->for_all
and device->for_some
are also available for devices. The following example changes the pen
thickness of all graphicals of a device to 2:
send(Device, for_some, @default,
message(@arg1, pen, 2)),
<-level
equals 0. Used for quick detection of a common device for two
graphicals.
See also device->reparent.
->position,
etc.).
The first element of this chain is the top-most graphical. The others are further and further in the background.
->compute
->_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.
->append’for details.->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.->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.
->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.
point is not @default,
invoke graphical->set
with the X and Y values of the point.
->device
->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)
<-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.
<-pointed
and generate area_enter and
area_exit events to graphicals that were added/removed from
this chain. Implemented by device->update_pointed
<-pointed
using
event->post.
If event->post
succeeds on some graphical, stop with success.
->event
to process recognisers defined on the device.
<->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)
<-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.
<-colour
not equal to @default. Device ->foreground' is equivalent to Graphical graphical->colour‘.
|name,
[any]
->format:
format* Attaches a format
object to a device. This implies the graphicals are placed in a
two-dimensional grid.
->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.
->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.
->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.attribute editor and will not forward their device<-message.
Otherwise they will immediately forward their device<-message.
See also
dialog->modified_item.->set:
X, Y’.
-offset
The default reference point is the top-left corner of the bounding box of all the member graphicals.
<-device
organisation up in the graphical<-device
hierarchy. This general method performs the following:
<-level
to reflect the distance to the
top-most graphical device.
->reparent
to all its member graphicals
->reparent
on itself See graphical->reparent
for details.
->resize
for details on the parameters.
Defaults:
The following defaults apply:
<-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.
<->displayed:
@on’and
overlap with area on the device. See also device<-inside.
|chain*<->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.
->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.<-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.
->move
->move
hello, type
?- get(Device, hello_member, Hello).
NOTE: Graphicals may also be found using device<-member.
Diagnostics: Asking for a graphical that does not exist will trap the no_behaviour error.
<-graphicals’.
|event],
condition=[code] -> graphicallocal graphical overlapping with at
for which
condition succeeds.
This methods uses a similar search technique as used by
device->event
and is first of all intended to help writing gestures that have to
relate two graphical
objects, possibly not placed on the same device
object. Examples are class connect_gesture
or a drag-and-drop gesture.
device<-find
performs the following steps:
<-graphicals
from tail to head (i.e. starting at the
topmost graphical). For each graphical:
at is given and graphical->in_event_area
fails Continue with the next graphical
<-find
on the device. Return with the result if any.
The following example finds a graphical that defines the send-method
drop in the same window as where the event occurred:
...
get(@event?window, find, @event,
message(@arg1, has_send_method, drop), Gr),
...
selection because it is commonly used to implement
selecting multiple graphicals by dragging a box around them. See
PceDraw.
<-graphicals
that has name
name. This mechanism is commonly used to address parts of a
device.
Diagnostics: Fails if no graphical with the requested name exists.
-offset
|event,
append_to=[chain] -> chainIf chain is supplied, this chain is filled with the matching
graphicals. This chain is chain->cleared
first. If it is @default,
a new
chain object with the
matching graphicals it returned.
The matching graphicals are the graphicals for which‘Graphical
graphical->in_event_area’succeeds.
The graphicals are stored in the chain, such that the top-most graphical
is the head of the chain.
-offset
<-selected:
@on’. If
there are no such graphicals, an empty chain is returned.
<-offset.
<-offset.