If you've got reasonably complicated sets of objects on the screen, drawing
directly to the screen can result in flicker. You're much better off
drawing to an offscreen pixmap, then copying the changed region onto the
window...
In addition to XCopyArea(), judicious setting of Clip Rectangles while
drawing to the offscreen pixmap (and doing a XCopyArea of only the changed
regions of the offscreen pixmap) results in pretty good portable X windows
animation. Make sure that you are not drawing or copying uneccessary bits
outside of the region that was damaged by a previous frame of animation and
you get good performance.
In WINTERP 2.0 (OSF/Motif Widget INTERPreter), I've integrated Stasko and
Hayes' Xtango algorithm animation package into a new Motif drawing area
based animation "widget." This package allows you to move graphical
objects and composite objects around in a 2.5D coordinate system without
having to worry about taking care of refreshing -- the system automatically
attempts to minimize the amount of screen updating, and as a result, you
get relatively smooth, flicker-free movement without having to deal with
low-level boring details that hamper most graphics programming efforts.
Please feel free to compare the facilities in WINTERP's Xtango widget with
those found in TCL/TK's canvas widget, ezd, and Python's canvas
widget... Since there was some discussion about TCL/TK canvas widget in
comp.lang.python, you'll notice that this is cross-posted.
--------------------
Here's the relevant section of winterp/doc/winterp.doc. See
ftp.x.org:contrib/devel_tools/winterp.tar.gz for details.
** Introduction to Stasko and Hayes' Xtango:
XTANGO is a general purpose animation system that supports
programmers developing color, real-time, 2 & 1/2 dimensional, smooth
animations. The focus of the system is on ease-of-use. XTANGO
utilizes the path-transition animation paradigm which helps move
animation design to an abstract, high level. Programmers need not be
graphics experts to develop their own animations. The Xtango
library used by WINTERP was developed by John T. Stasko
(stasko@cc.gatech.edu) and Doug Hayes at the Georgia Institute of
Technology -- WINTERP uses a modified version of "xtangovararg"
(version 1.52) -- the original is available via anonymous ftp from
par.cc.gatech.edu:pub/xtangovarargs.tar.Z (130.207.119.254).
The WINTERP interface to XTANGO further simplifies the
creation of graphics and animation. It provides a new widget class
TANGO:WIDGET_CLASS in which Tango animations may be displayed. Within
the TANGO:WIDGET_CLASS instance, a set of TANGO:IMAGE_CLASS instances
may be displayed and animated -- the images may be lines, rectangles,
circles, ellipses, polylines, polygons, splines, bitmaps, GIFs, text,
or a composite of the aforementioned types. All Xtango images types
other that text, bitmaps and GIFs are pixel independent, thereby
simplifying scaling, zooming, and resizing of Xtango graphics.
The WINTERP interface to XTANGO allows programmers to use the XLISP
object system to create new images with new functionality and
encapsulated animation capabilities by subclassing and/or composing the
previously mentioned image types. Unlike Xtango, animations and
graphics may be developed interactively in WINTERP. Furthermore,
WINTERP's Xtango performs automatic memory management on all types
associated with Xtango -- storeage associated with paths, transitions,
images, and the tango widget is automatically deallocated
when the data is no longer needed.
For details on the Xtango system underlying WINTERP's interface to
Xtango, see <winterp-top-dir>/doc/xtangodoc.tex (LaTeX format)
and <winterp-top-dir>/doc/xtangodoc.ps.Z (compressed postscript).
For a conceptual overview of Xtango, see
<winterp-top-dir>/doc/xtango.ps.Z (compressed postscript).
** TANGO Colors (TANGO_COLOR):
TANGO_COLOR is a FIXNUM representing a Pixel value specific to the
Xtango package. One may also pass STRING values as TANGO_COLOR,
typically, these are color names from /usr/lib/X11/rgb.txt, e.g.
"red". One may also specify a hexadecimal value for the color, e.g.
"#FF0000".
The following constants represent predefined Xtango color values:
TANGO_COLOR_WHITE
TANGO_COLOR_YELLOW
TANGO_COLOR_GREEN
TANGO_COLOR_BLUE
TANGO_COLOR_ORANGE
TANGO_COLOR_RED
TANGO_COLOR_MAROON
TANGO_COLOR_BLACK
See also <<TANGO:WIDGET_CLASS Method :LOAD_COLOR>> as a way to load
colors into Xtango's colormap. If you are repeatedly using the same
color, it is more efficient to use the TANGO_COLOR fixnum as returned
by :LOAD_COLOR or the color constants listed above, rather than forcing
a STRING to TANGO_COLOR conversion to be done multiple times.
Note that the underlying Xtango library limits <tango_color> arguments
to work only with the eight "basic" tango colors mentioned above.
This limitation only applies to programmatically changing the colors
of an image during an animation, e.g. through methods :TAP_COLOR and
:TX_COLOR, and function TANGO:PATH_COLOR. <tango_color>
arguments for image creation can use the full set of colors from
/usr/lib/X11/rgb.txt. If the specified color is not
available, an error will be signalled during color allocation.
** TANGO Locations and Coordinates (TANGO_LOC):
Locations in WINTERP's Xtango are represented as XLISP
COMPLEX type data #C(<x> <y>), where <x> and <y> are FLONUMs
representing the location within the TANGO:WIDGET_CLASS instance.
Using COMPLEX data simplifies mathematical and geometric calculations
because WINTERP's XLISP can do mathematical operations on
COMPLEX numbers (+, -, *, /, SIN, COS, TAN, ASIN, ACOS, ATAN, EXPT,
EXP, SQRT, etc).
For an example of using COMPLEX domain calculations, see
<winterp-top-dir>/examples/xtango/test-dial.lsp which
defines a "dial widget" using XTANGO graphics, and employs
COMPLEX domain calculations involving "cis" ==
COS(x) + i*SIN(x) = EXP(i*x). In particular see
DIAL-WIDGET-CLASS (<winterp-top-dir>/examples/xtango/wcls-dial.lsp)
and POLAR-ARROW-IMAGE-CLASS
(<winterp-top-dir>/examples/xtango/icls-plrar.lsp).
Note that the coordinate system for XTANGO is the opposite of
what you'd expect given the useage of COMPLEX domain coordinates --
by default, the visible area of the TANGO:WIDGET_CLASS instance
is represented by the following border coordinates:
#C(0.0 0.0) #C(1.0 0.0)
+---------------+
| |
| |
| |
| |
+---------------+
#C(0.0 1.0) #C(1.0 1.0)
The coordinates bounding the viewing area can be changed by invoking
methods :ZOOM, :PAN, or :SET_COORD. Method :INQ_COORD returns the
border coordinates.
** TANGO Paths (TANGO_PATH):
A TANGO Path is a data type that identifies an animation path along
which an image is modified. A path can be thought of as a list of
relative offsets, each relative to the previous position.
Paths are applied to Xtango transition operations (methods :TX_* on
TANGO:IMAGE_CLASS and subclasses); each element in a path is applied
to the appropriate transition operator, becoming a single frame of
animation when the transition is performed via TANGO:TX_PERFORM or via
:PERFORM keyword supplied to a transition operation.
*** Function TANGO:PATH_CREATE (TANGOpath_create(), TANGOpath_null()):
(TANGO:PATH_CREATE [<path>...])
==> returns a TANGO_PATH node representing a path
(<x0,y0>...<xn,yn>)
The [<path>...] argument is optional, and may be of multiple types:
* if the <path> argument is omitted, then a path of length one with
both x and y offsets set to 0.0 is used as the path for the
transition (see TANGOpath_null() in doc/xtangodoc.tex);
example: (TANGO:PATH_CREATE)
==> returns null path of length 1.
* else, if <path> is of type FIXNUM, then a path of length <path> with
both x and y offsets set to 0.0 is used as the path for the
transition (see TANGOpath_null() in doc/xtangodoc.tex);
example: (TANGO:PATH_CREATE 2)
==> returns null path of length 2.
* else, if <path> is one or more COMPLEX (e.g. #C(<x> <y>) arguments
then a path element is created for each COMPLEX argument,
with the x and y offsets of each path element set to each
complex argument's <x> and <y> parts.
example: (TANGO:PATH_CREATE #C(0.1 0.1) #C(0.1 0.1)
#C(0.1 0.1) #C(0.1 0.1))
==> returns a path of length 4 w/
x and y offsets set to 0.1 .
* else, if <path> is a a pair of sequences (LIST or ARRAY) of FLONUMS,
then a path of the same length as the sequences is created,
with the x and y offsets set to the corresponding <x> <y>.
example: (TANGO:PATH_CREATE #'(0.1 0.1 0.1 0.1)
#'(0.1 0.1 0.1 0.1))
==> returns a path of length 4 w/
x and y offsets set to 0.1 .
*** Function TANGO:PATH_LENGTH (TANGOpath_length()):
(TANGO:PATH_LENGTH <path>)
==> returns a FIXNUM representing length of <path>.
<path> is a TANGO_PATH node, created (for example) by
function TANGO:PATH_CREATE.
This routine returns the numbers of offsets in the given path.
*** Function TANGO:PATH_DX (TANGOpath_dx()):
(TANGO:PATH_DX <path>)
==> returns a FLONUM representing the x distance traversed by
path.
<path> is a TANGO_PATH node, created (for example) by
function TANGO:PATH_CREATE.
This routine returns the <x> distance that the given <path>
traverses from start to finish.
*** Function TANGO:PATH_DY (TANGOpath_dy()):
(TANGO:PATH_DY <path>)
==> returns a FLONUM representing the y distance traversed
by path
<path> is a TANGO_PATH node, created (for example) by
function TANGO:PATH_CREATE.
This routine returns the <y> distance that the given <path> traverses
from start to finish.
*** Function TANGO:PATH_TYPE (TANGOpath_type()):
(TANGO:PATH_TYPE <k_type>)
==> returns a TANGO_PATH node.
<k_type> is a keyword argument, one of
:STRAIGHT -- move right
:CLOCKWISE -- move clockwise right in an upward arc
:COUNTERCLOCKWISE -- move counterclockwise left in an upward arc
Each of these paths when created will have 20 relative offset points
and will change in <x> by a total value of 0.2 animation coordinate
system units.
The paths created by this routine will probably not be utilized as is,
although there is no reason why they cannot be. They are provided
primarily as starting paths for use in the subsequent path modification
routines.
*** Function TANGO:PATH_COLOR (TANGOpath_color()):
(TANGO:PATH_COLOR <color>)
==> returns a TANGO_PATH node.
<color> is a FIXNUM ranging from 0-7 representing a Xtango pixel value.
The following symbols have been predefined with Xtango pixel values:
TANGO_COLOR_WHITE 0
TANGO_COLOR_YELLOW 1
TANGO_COLOR_GREEN 2
TANGO_COLOR_BLUE 3
TANGO_COLOR_ORANGE 4
TANGO_COLOR_RED 5
TANGO_COLOR_MAROON 6
TANGO_COLOR_BLACK 7
(Note that the underlying Xtango path-color primitives
do not allow other Xtango colors to be defined for
path operations).
This routine returns a one offset path that will change an image to
the given color when the path is used as an argument to tango-image
method :TX_COLOR. The direction of the offset in the path determines
the color to utilize. For example, if there is an image
'red_door_image' that you wish to be painted black, you could call
(send red_door_image :TX_COLOR (TANGO:PATH_COLOR TANGO_COLOR_BLACK))
For the above usage, you could also avoid calling TANGO:PATH_COLOR
entirely by using method :TAP_COLOR, e.g.
(send red_door_image :TAP_COLOR TANGO_COLOR_BLACK).
Note that colors created with TANGO:WIDGET_CLASS method :LOAD_COLOR
cannot be used as parameters to this function. The supported colors are
TANGO_COLOR_WHITE thru TANGO_COLOR_BLACK.
*** Function TANGO:PATH_ADD_TAIL (TANGOpath_add_tail()):
(TANGO:PATH_ADD_TAIL <path> <num>)
==> returns a TANGO_PATH node.
<path> is a TANGO_PATH as returned by other TANGO:PATH_* routines.
<num> is a positive FIXNUM, if <=0, the value 0 is used.
This routine elongates a path by extending the "tail" of the path.
The parameter <num> designates the number of null #C(0.0 0.0) offsets
that will be apppended to the given <path>, producing a new path that
is returned.
*** Function TANGO:PATH_ADD_HEAD (TANGOpath_add_head()):
(TANGO:PATH_ADD_HEAD <path> <num>)
==> returns a TANGO_PATH node.
<path> is a TANGO_PATH as returned by other TANGO:PATH_* routines.
<num> is a positive FIXNUM, if <=0, the value 0 is used.
This routine elongates a path by extending the "head" of the path.
The parameter <num> designates the number of null #C(0.0 0.0) offsets
that will be prepended to the given <path>, producing a new path that
is returned.
*** Function TANGO:PATH_DELETE_TAIL (TANGOpath_delete_tail()):
(TANGO:PATH_DELETE_TAIL <path> <num>)
==> returns a TANGO_PATH node.
<path> is a TANGO_PATH as returned by other TANGO:PATH_* routines.
<num> is a positive FIXNUM, if <=0, the value 0 is used.
This routine provides a way of shortening a path. The parameter <num>
designates the number of offsets that will be removed from tail of the
given <path> in order to produce a new path that is returned.
*** Function TANGO:PATH_DELETE_HEAD (TANGOpath_delete_head()):
(TANGO:PATH_DELETE_HEAD <path> <num>)
==> returns a TANGO_PATH node.
<path> is a TANGO_PATH as returned by other TANGO:PATH_* routines.
<num> is a positive FIXNUM, if <=0, the value 0 is used.
This routine provides a way of shortening a path. The parameter
<num> designates the number of offsets that will be removed from head
of the given <path> in order to produce a new path that is returned.
*** Function TANGO:PATH_REVERSE (TANGOpath_reverse()):
(TANGO:PATH_REVERSE <path>)
==> returns a TANGO_PATH node.
<path> is a TANGO_PATH as returned by other TANGO:PATH_* routines.
This routine returns a path that is the inverse of the given <path>.
Being an inverse path means that the order of offsets is reversed,
and each offset points in the exact opposite direction. This routine
provides a way for an image to retrace its tracks from a movement
transition.
*** Function TANGO:PATH_ROTATE (TANGOpath_rotate()):
(TANGO:PATH_ROTATE <path> <deg>)
==> returns a TANGO_PATH node.
<path> is a TANGO_PATH as returned by other TANGO:PATH_* routines.
<deg> is a positive FIXNUM, ranging from 0 to 360 (degrees).
This routine returns a path that corresponds to the rotation of the
given <path> in a counter-clockwise motion. The number of degrees to
rotate is provided by the FIXNUM integer parameter <deg> which should
be between 0 and 360.
*** Function TANGO:PATH_INTERPOLATE (TANGOpath_interpolate()):
(TANGO:PATH_INTERPOLATE <path> <factor>)
==> returns a TANGO_PATH node.
<path> is a TANGO_PATH as returned by other TANGO:PATH_* routines.
<factor> is a FLONUM
This routine returns a path in which the number of offsets is modified
by a factor given by the <factor> parameter. If a path with length 10
is interpolated with a factor of 2.0, the returned path will have 20
offsets. If the factor is 0.3, the path will have 3 offsets. Straight
linear interpolation is used. Consequently, when interpolating a path
with choppy, wavy motion characteristics, individual extrema may be
lost with certain <factor> parameters.
*** Function TANGO:PATH_SCALE (TANGOpath_scale()):
(TANGO:PATH_SCALE <path> <scale>)
==> returns a TANGO_PATH node.
<path> is a TANGO_PATH as returned by other TANGO:PATH_* routines.
<scale> is a COMPLEX number #C(<dx> <dy>) where <dx> <dy> are FLONUMs.
This routine returns a path in which each offset is scaled by the
given factors in X and Y. That is, each offsets' X and Y values are
mulitplied by the respective <dx> and <dy> factors specified in the
COMPLEX <scale> argument. So, for example, to return a path that
would be the reflection of a path across an imaginary vertical line,
<scale> == #C(-1.0 1.0).
*** Function TANGO:PATH_EXTEND (TANGOpath_extend()):
(TANGO:PATH_EXTEND <path> <extension>)
==> returns a TANGO_PATH node.
<path> is a TANGO_PATH as returned by other TANGO:PATH_* routines.
<extension> is a COMPLEX number #C(<dx> <dy>) where <dx> <dy>
are FLONUMs.
This routine returns a path in which each offset is extended by the
given factors in X and Y. That is, each offsets' X and Y values have
the respective <dx> and <dy> factors (specified in the COMPLEX
<extension>) added to them.
*** Function TANGO:PATH_COPY (TANGOpath_copy()):
(TANGO:PATH_COPY <path>)
==> returns a TANGO_PATH node.
<path> is a TANGO_PATH as returned by other TANGO:PATH_* routines.
This routine returns a new path that has an exact duplicate list of
offsets as the given <path>.
*** Function TANGO:PATH_ITERATE (TANGOpath_iterate()):
(TANGO:PATH_ITERATE <path> <factor>)
==> returns a TANGO_PATH node.
<path> is a TANGO_PATH as returned by other TANGO:PATH_* routines.
<factor> is a FLONUM
This routine returns a path which is an iteration of a given <path>.
The <factor> FLONUM parameter provides how many times the given path
should be repeated in the path to be created.
*** Function TANGO:PATH_CONCATENATE (TANGOpath_concatenate()):
(TANGO:PATH_CONCATENATE <path-0> <path-1> <path-2> ...)
==> returns a TANGO_PATH node.
<path-i> is a TANGO_PATH as returned by other TANGO:PATH_* routines.
This routine creates a path which is the concatenation of some number
of other paths. The paths will be concatenated in order from the
<path-0> position on to the last <path-n> position. The first offset
of a path is relative to the last offset of the previous path.
*** Function TANGO:PATH_COMPOSE (TANGOpath_compose()):
(TANGO:PATH_COMPOSE <path-0> <path-1> <path-2> ...)
==> returns a TANGO_PATH node.
<path-i> is a TANGO_PATH as returned by other TANGO:PATH_* routines.
This routine returns a path which is the composition of the paths
given in the <path-0> to <path-n> parameters. By composition, we
mean a cumulative combination on an offset by offset basis. If a path
is thought of as a vector, the composition of paths produces a new
vector that has the same length as the originals and is like the
vector sum of the original path vectors. Only paths with an equal
number of offsets can be composed. Otherwise, an error is signalled.
Essentially, path composition takes all the first relative <x> <y>
offsets and adds them together to make a new cumulative first <x>,<y>
offset. This is done for each offset in the paths.
*** Function TANGO:PATH_DISTANCE (TANGOpath_distance()):
(TANGO:PATH_DISTANCE <from_loc> <to_loc> <distance>)
==> returns a TANGO_PATH node.
<from_loc> is a COMPLEX number #C(<from_x> <from_y>),
where <from_x>, <from_y> are FLONUMs.
<to_loc> is a COMPLEX number #C(<to_x> <to_y>),
where <to_x>, <to_y> are FLONUMs.
<distance> is a FLONUM.
This routine returns a path that proceeds in a straight line from the
given <from_loc> to the given <to_loc> with the condition that the
path will have an offset every time the given <distance> has been
covered. If the given distance is larger than the distance between
the <from_loc> and <to_loc>, the path is only given one offset. This
routine is useful to create paths that will make images move at the
same velocity.
*** Function TANGO:PATH_EXAMPLE (TANGOpath_example()):
(TANGO:PATH_EXAMPLE <from_loc> <to_loc> <path>)
==> returns a TANGO_PATH node.
<from_loc> is a COMPLEX number #C(<from_x> <from_y>),
where <from_x>, <from_y> are FLONUMs.
<to_loc> is a COMPLEX number #C(<to_x> <to_y>),
where <to_x>, <to_y> are FLONUMs.
<path> is a TANGO_PATH as returned by other TANGO:PATH_* routines.
This routine returns a path which "looks like" the given example
<path>, but which would move from the logical <from_loc> to the
logical <to_loc>. The created path will have the same number of
offsets as the given path. The general flow of movement in the
example path is followed as closely as possible by maintaining the
same ratios between control points in both paths. Clearly, however,
if the two paths move in opposite directions, they will not look much
alike. Typically, this routine will be used when one wants an image
to end up in some specific position, with the image following some
rough, given trajectory path in order to get there.
*** Function TANGO:PATH_MOTION (TANGOpath_motion()):
(TANGO:PATH_MOTION <from_loc> <to_loc> <path_type>)
==> returns a TANGO_PATH node.
<from_loc> is a COMPLEX number #C(<from_x> <from_y>),
where <from_x>, <from_y> are FLONUMs.
<to_loc> is a COMPLEX number #C(<to_x> <to_y>),
where <to_x>, <to_y> are FLONUMs.
<path_type> is a keyword, either :STRAIGHT,
:CLOCKWISE, or :COUNTERCLOCKWISE.
This routine returns a path with movement characteristics of the
given <path_type>, but that also begins at the location with logical
X and Y coordinates of <from_loc> and proceeds to the location with
logical X and Y coordinates of the <to_loc>. Note that the provided
from and to locations need not have absolute screen coordinate
meaning. Because a path is made up of a group of relative offsets,
these locations are provided just as necessary aids in the path
creation. For example, the same path will be created using from ==
#C(0.2 0.2) and to == #C(0.4 0.4) as using from == #C(0.7 0.7) and to
== #C(0.9 0.9). Most often however, the provided locations will be
specific window coordinates chosen to move a certain image to a
specific location.
The created path will contain 20 offsets and will be modelled to fit
the given <path_type>, which may be one of the following keywords
:STRAIGHT, :CLOCKWISE, or :COUNTERCLOCKWISE. The straight option
creates a path that is a direct line from {\em fromloc} to {\em
toloc} with equally spaced offsets. The two clock motions will
create a path that curves in the given clock motion direction.
Essentially, this routine is just
(TANGO:PATH_EXAMPLE <from_loc> <to_loc>
(TANGO:PATH_TYPE <path_type>)).
*** Function TANGO:PATH_SMOOTH (TANGOpath_smooth()):
(TANGO:PATH_SMOOTH <path>)
==> returns a TANGO_PATH node.
<path> is a TANGO_PATH as returned by other TANGO:PATH_* routines.
This routine returns a path which is a "smoother" version of the
given <path>. Essentially, each offsets' value is determined by
averaging in the neighboring offsets' values. Currently, we use 2
times the designated offset plus one time the previous and subsequent
offsets.
*** Function TANGO:PATH_FREE (TANGOpath_free()):
(TANGO:PATH_FREE <path>)
==> returns NIL
<path> is a TANGO_PATH as returned by other TANGO:PATH_* routines.
This routine frees the memory space occupied by the TANGO_PATH arg
<path>.
Note that WINTERP automatically frees any TANGO_PATH node which is no
longer referenced. If you happen to store a TANGO_PATH on a global
variable, or within a closure (on function, method, lambda, etc) it
will not get garbage collected, so you may want to use this function
to explicitly free it.
If very long paths are being created, but garbage collections are
happening infrequently, the process size will grow larger than it
needs to be because memory taken up by TANGO_PATH's will not be able
to be reused until a garbage collection occurs.
Calling TANGO:PATH_FREE frees the Xtango storage used by
<path>. Subsequent references of the node passed to this function via
<path> will signal an error indicating that the path has been
freed. This might happen, for example, when you use the <path> as an
argument to a :TX_* TANGO_IMAGE_CLASS method.
** TANGO Transitions (TANGO_TRANS):
A transition is a data-type representing a graphics action to be
performed on a Tango Image object. A transition action is comprised of
1) the actual type of the transition such as fill style change,
visibility change, color change, motion, resizing, and so forth, or
some combination thereof;
2) the image to which it applies, and
3) A path along which to apply the transition. A sequence of
values, each element of which becomes a single frame of animation.
The TANGO_TRANS type is returned by the following methods on
TANGO:IMAGE_CLASS (and subclasses thereof) when they are called
without the :PERFORM keyword: :TX_MOVE, :TX_VISIBLE, :TX_COLOR,
:TX_RAISE, :TX_LOWER, :TX_DELAY, :TX_REFRESH, :TX_DELETE, :TX_ZOOM,
:TX_FILL, :TX_RESIZE, :TX_RESIZE1... :TX_RESIZE7, :TX_GRAB1...
:TX_GRAB7, and :TX_SHUFFLE. See below for details on the transition
methods and the particular subclasses of TANGO:IMAGE_CLASS to which
they apply.
The results of the methods returning TANGO_TRANS can be operated on by
a variety of functions:
*** Function TANGO:TX_ITERATE (TANGOtrans_iterate()):
(TANGO:TX_ITERATE [:PERFORM] <tango_trans> <num-iterations>)
==> returns <tango_trans> object, or NIL if :PERFORM keyword
given.
This routine returns a transition which corresponds to performing the
given <tango_trans> <num> times, one immediately after the other.
One example use of this routine is to make an image repeat a given
behavior.
The optional :PERFORM keyword argument specifies that the transition
is to be performed immediately (see TANGO:TRANS_PERFORM). If :PERFORM
is omitted, then a <tango_trans> object is returned (useful for
storing- or operating-on- complex transitions via TANGO:TX_ITERATE,
TANGO:TX_CONCATENATE, TANGO:TX_COMPOSE.
The <tango_trans> argument is of type TANGO_TRANS, which is produced
by one of the :TX_* methods on TANGO:IMAGE_CLASS and its subclasses.
The <num-iterations> argument is a FIXNUM representing the number of
times to iterate..
*** Function TANGO:TX_CONCATENATE (TANGOtrans_concatenate()):
(TANGO:TX_CONCATENATE [:PERFORM] <trans-1>
[<trans-2> [<trans-3> [...]]])
==> returns <tango_trans> object,
or NIL if :PERFORM keyword given.
This routine returns a transition which corresponds to the
concatenation of the transitions in the <trans-i> parameters. The
order of the incoming transitions corresponds to the order that they
will be performed in the concatenation, with transition <trans-1>
being first. This one logical transition can then be composed,
iterated, etc., with other transitions to achieve various desired
animations.
The optional :PERFORM keyword argument specifies that the transition
is to be performed immediately (see TANGO:TRANS_PERFORM). If :PERFORM
is omitted, then a <tango_trans> object is returned (useful for
storing- or operating-on- complex transitions via TANGO:TX_ITERATE,
TANGO:TX_CONCATENATE, TANGO:TX_COMPOSE.
Each <trans-i> argument is of type TANGO_TRANS, which is produced by
one of the :TX_* methods on TANGO:IMAGE_CLASS and its subclasses.
*** Function TANGO:TX_COMPOSE (TANGOtrans_compose()):
(TANGO:TX_COMPOSE [:PERFORM] <trans-1> [<trans-2> [<trans-3> [...]]])
==> returns <tango_trans> object,
or NIL if :PERFORM keyword given.
This routine is very important because it provides the ability to
have many images moving and changing around the screen at the same
time. It returns a transition which is the composition of the
<trans-i> arguments. By composition, we mean the "concurrent"
execution of all the transitions involved. When transitions are
composed, individual frames of the transition are combined, e.g., the
first frames, the second frames, etc. For transitions, each offset
in the path utilized corresponds to one frame. Transitions of
unequal "length" can be composed. Transitions shorter than the
longest transition will simply have null action frames added to their
tails. Consequently, all the action will start together but will
finish according to how many frames are in the transition. Note: to
compose more than 50 transitions, you need to call this routine twice
with the result of the first call as a parameter to the second call.
The optional :PERFORM keyword argument specifies that the transition
is to be performed immediately (see TANGO:TRANS_PERFORM). If :PERFORM
is omitted, then a <tango_trans> object is returned (useful for
storing- or operating-on- complex transitions via TANGO:TX_ITERATE,
TANGO:TX_CONCATENATE, TANGO:TX_COMPOSE.
Each <trans-i> argument is of type TANGO_TRANS, which is produced by
one of the :TX_* methods on TANGO:IMAGE_CLASS and its subclasses.
*** Function TANGO:TX_PERFORM (TANGOtrans_perform()):
(TANGO:TX_PERFORM <tango_trans>)
==> returns NIL
TANGO:TX_PERFORM actually carries out the given transition which has
been created via one of the transition creation routines (:TX_*
methods). All the involved graphical images are animated in the ways
specified in the transition when it was created.
The <tango_trans> argument is of type TANGO_TRANS, which is produced
by one of the :TX_* methods on TANGO:IMAGE_CLASS and its subclasses.
Note that simple transitions may be achieved via the :PERFORM keyword
on the TANGO:IMAGE_CLASS :TX_* methods -- the :PERFORM keyword allows
:TX_* method to directly invoke the functionality of
TANGO:TX_PERFORM. More complex transitions require calls to
TANGO:TX_PERFORM; these transitions are stored in the user's program
and performed later; alternately the transitions may be the result of
functions like TANGO:TX_ITERATE, TANGO:TX_CONCATENATE,
TANGO:TX_COMPOSE.
*** Function TANGO:TX_FREE (TANGOtrans_free()):
(TANGO:TX_FREE <tango_trans>)
==> returns NIL.
This routine frees the space associated with <tango_trans>. Calling
this routine is not absolutely necessary, since WINTERP's garbage
collector will automatically free up any TANGO_TRANS data. However,
if you are creating many transitions which are briefly used, then
discarded, you may be able to prevent un-necessary memory-size growth
by explicitly freeing TANGO_TRANS objects -- in the worst case, where
the only "garbage" being generated is TANGO_TRANS objects, you may
end up allocating 2000 (default) nodes before any of the space gets
freed by the garbage collector. The XLISP ALLOC function allows the
2000 default to be changed.
The <tango_trans> argument is of type TANGO_TRANS, which is produced
by one of the :TX_* methods on TANGO:IMAGE_CLASS and its subclasses.
** TANGO:WIDGET_CLASS -- the Xtango 2-D animation/graphics widget
*** equivalent Xt 'WidgetClass':
xmDrawingAreaWidgetClass --
TANGO:WIDGET_CLASS is a Motif XmDrawingArea widget subclass which
interfaces to Stasko&Hayes' XTANGO 2-D Animation Package
(xtangovararg, VERSION 1.52). All resources, callbacks, and behavior
of this widget are documented in XmDrawingArea(3x).
xmDrawnButtonWidgetClass --
If the widget is created with the optional :BUTTON argument,
then then Xtango functionality will be available
in a Motif XmDrawnButton subclass. All resources, callbacks, and
behavior of this widget are documented in XmDrawnButton(3x).
*** TANGO:WIDGET_CLASS Method :NEW/:ISNEW (XtCreateWidget()):
(send TANGO:WIDGET_CLASS :new [:managed/:unmanaged] ...)
--> XtCreateWidget(... xmDrawingAreaWidgetClass ...)
(send TANGO:WIDGET_CLASS :new [:managed/:unmanaged] :BUTTON ...)
--> XtCreateWidget(... xmDrawnButtonWidgetClass ...)
See WIDGET_CLASS :NEW method for information on the standard
widget creation parameters depicted by "..." above.
The optional :BUTTON argument causes the Xtango drawing area
semantics to be included in a Motif XmDrawnButton widget.
This is useful for pushbuttons, menu entries, etc in which
you want to have graphics and/or animations appear.
*** TANGO:WIDGET_CLASS Method :ADD_CALLBACK/:SET_CALLBACK (XtAddCallback()):
(send <tangowidget> :ADD_CALLBACK ...)
--> returns: <callback_id_object> of type CALLBACKOBJ
(send <tangowidget> :SET_CALLBACK ...)
--> returns: <callback_id_object> of type CALLBACKOBJ
These methods work just like the :ADD_CALLBACK/:SET_CALLBACK
methods on WIDGET_CLASS except that this method knows
how to get call_data values from the XmDrawingAreaCallbackStruct:
typedef struct
{
int reason;
XEvent *event;
Window window;
} XmDrawingAreaCallbackStruct;
or, if created with the :BUTTON submessage,
XmDrawnButtonCallbackStruct:
typedef struct
{
int reason;
XEvent *event;
Window window;
#ifdef MOTIF_1.1
int click_count; /* FIELD EXISTS ONLY IN MOTIF 1.1 */
#endif MOTIF_1.1
} XmDrawnButtonCallbackStruct;
If the <tangowidget> was created without the :BUTTON submessage,
the following symbols are valid for the callback
bindings list; When the callback fires, it will bind that symbol's
value in the lexical environment of the callback:
CALLBACK_WIDGET -- the WIDGETOBJ of the callback
CALLBACK_REASON -- the reason symbol for the callback
CALLBACK_XEVENT -- the XEvent* that caused the callback
CALLBACK_WINDOW -- the Window of the callback
If the <tangowidget. was created with the :BUTTON submessage, then
the following callback symbols are valid:
CALLBACK_WIDGET -- the WIDGETOBJ of the callback
CALLBACK_REASON -- the reason symbol for the callback
CALLBACK_XEVENT -- the XEvent* that caused the callback
CALLBACK_WINDOW -- the Window of the callback
#ifdef MOTIF_1.1
CALLBACK_CLICK_COUNT -- a FIXNUM representing the number of
clicks upon the button. The click count
will only be > 1 when resource
:XMN_MULTI_CLICK == :MULTICLICK_KEEP
#endif /* MOTIF_1.1 */
*** TANGO:WIDGET_CLASS Method :BEGIN_DRAWING (animate_begin()):
(send <tango-widget> :BEGIN_DRAWING)
==> returns NIL.
You must call this routine prior to doing any drawing in a
TANGO:WIDGET_CLASS instance, but after the widget's windows have
been created. Typically, one should call this on the first expose
event received by the widget -- use an :XMN_EXPOSE_CALLBACK.
XTANGO-WIDGET-CLASS, and XTANGO-BUTTON-WIDGET-CLASS are subclasses
of TANGO:WIDGET_CLASS which automatically call this method in an
:XMN_EXPOSE_CALLBACK. To get those subclasses, do:
(require "xtango/cls-widget")
(require "xtango/cls-image")
*** TANGO:WIDGET_CLASS Method :PAN :
(send <tango-widget> :PAN <direction> [<pan-amount-flonum>])
==> returns NIL.
<direction> can be one of
:UP -- pans the xtango view-window up.
:DOWN -- pans the xtango view-window down.
:LEFT -- pans the xtango view-window left.
:RIGHT -- pans the xtango view-window right.
<pan-amount-flonum> is an optional flonum indicating amount to
pan the viewer. If ommitted, it defaults to 0.2.
This method pans the viewing area such that the top/left corner
of the viewing area is no longer #C(0.0 0.0) and the bottom/right
corner is no longer located at #C(1.0 1.0).
To reset the viewing area back to the default, call:
(send <tango-wdiget> :SET_COORD 0.0 1.0 1.0 0.0)
The current coordinates associated with the viewing area may be
retrieved via
(send <tango-wdiget> :INQ_COORD)
*** TANGO:WIDGET_CLASS Method :ZOOM :
(send <tango-widget> :ZOOM <direction> [<zoom-amount-flonum>])
==> returns NIL.
<direction> can be one of
:IN -- zoom in
:OUT -- zoom out
<zoom-amount-flonum> is an optional FLONUM indicating amount to
zoom the viewer. If ommitted, it defaults to 0.8
This method zooms the viewing area in or out, causing the images
displayed within to change in size. Note that the current version
of WINTERP/Xtango has a bug -- bitmap, text, and gif images don't
resize upon zooming. After zooming, the top/left corner of the viewing
area is no longer #C(0.0 0.0) and the bottom/right corner is no longer
located at #C(1.0 1.0).
To reset the viewing area back to the default, call:
(send <tango-wdiget> :SET_COORD 0.0 1.0 1.0 0.0)
The current coordinates associated with the viewing area may be
retrieved via
(send <tango-wdiget> :INQ_COORD)
*** TANGO:WIDGET_CLASS Method :SET_COORD (TANGOset_coord()):
(send <tango-widget> :SET_COORD <lx> <by> <rx> <ty>)
==> returns NIL.
where: <lx> - left x coord (flonum) (default, 0.0)
<by> - bottom y coord (flonum) (default, 1.0)
<rx> - right x coord (flonum) (default, 1.0)
<ty> - top y coord (flonum) (default, 0.0)
This method is used to manually set the window boundary coordinates
which start by default at 0.0 to 1.0 in both directions (origin is at
upper left corner). This routine then allows you to zoom or pan the
display from with an animation file. It is advisable to maintain the
same aspect ratio between <x> and <y> or weird things may happen. A
sequence of calls to this routine with gradually tightening window
coordinates will provide a very nice smooth zooming functionality.
*** TANGO:WIDGET_CLASS Method :INQ_COORD (TANGOinq_coord()):
(send <tango-widget> :INQ_COORD)
==> returns list of FLONUMs (<lx> <by> <rx> <ty>)
(this data can subsequently be APPLY'd to :SET_COORD)
This routine returns the current value of the window's boundary
coordinates.
*** TANGO:WIDGET_CLASS Method :SET_ANIMATION_EVENT_PROCESSING :
(send <tango-widget> :SET_ANIMATION_EVENT_PROCESSING <event_mask>)
--> returns NIL.
<event_mask> is a FIXNUM, created by taking the LOGIOR of
KEY_PRESS_MASK BUTTON_PRESS_MASK, and EXPOSURE_MASK. Any other mask
values (as used perhaps by :ADD_EVENT_HANDLER/:SET_EVENT_HANDLER
methods) are ignored.
KEY_PRESS_MASK: interrupts running animation when Control-C
entered in the window running the animation.
BUTTON_PRESS_MASK interrupts running animation when any mouse
button is clicked within the window running
the animation.
EXPOSURE_MASK: if the window running the animation is
obscured then exposed, LOGIORing this value
to the event mask will cause the entire
window to refresh its graphics. When not
set, animation windows will not completely
refresh themselves until the current
animation's transition has finished.
NOTE: By default, all TANGO:WIDGET_CLASS instances are created with
the following setting:
(send <tango-widget> :SET_ANIMATION_EVENT_PROCESSING
(logior KEY_PRESS_MASK EXPOSURE_MASK))
*** TANGO:WIDGET_CLASS Method :SET_DELAY :
(send <tango-widget> :SET_DELAY <sleep_usecs_fixnum>)
==> returns NIL.
This method slows down an animation if it is running too fast on
your host/display. <sleep_usecs_fixnum> is a FIXNUM representing
the number of miscroseconds to sleep between frames of the
animation. If the value is 0, then no delay occurs between
frames of animation. The default value is 0.
*** TANGO:WIDGET_CLASS Method :SET_DEBUG :
(send <tango-widget> :SET_DEBUG <debug_p>)
==> returns NIL.
When <debug_p> is non-NIL, this method turns on Xtango's internal
debugging output -- prints out names of Xtango functions being called
during the course of an animation. The output is sent to *TRACE-OUTPUT*
which defaults to *TERMINAL-IO* unless redirected.
*** TANGO:WIDGET_CLASS Method :MONO_PATTERN_REPRESENTATION :
(send <tango-widget> :MONO_PATTERN_REPRESENTATION <kind>)
--> returns NIL if <tango-widget> is on a color screen, and
doesn't make any changes.
--> returns T if <tango-widget> is on a monochrome screen,
where <kind> can be
:COLORS -- patterns represent colors on mono displays.
:FILLS -- patterns represent fill-styles on mono displays.
*** TANGO:WIDGET_CLASS Method :REFRESH (TANGO_refresh()):
(send <tango-widget> :REFRESH)
==> returns NIL.
This method redraws all the tango images visible in <tango-widget>.
Typically, one calls :REFRESH from an :XMN_EXPOSE_CALLBACK on
<tango-widget>. One might also call :REFRESH to force the next frame
of animation to be displayed thereby displaying any images or
transitions that have not yet been displayed via a call to TANGO_IMAGE
method :TAP_SHOW...
*** TANGO:WIDGET_CLASS Method :INPUT_COORD (TANGOinput_coord()):
(send <tango-widget> :INPUT_COORD)
==> on success, returns a COMPLEX FLONUM number #C(<x> <y>).
==> on failure, returns NIL.
This method prompts the user to select a coordinate from the animation
window. If a successful choice is made, the routine returns
#C(<x> <y>). If for some reason the selection was not successful
(e.g., the mouse selection was made outside <tango-widget>), the
routine returns NIL.
*** TANGO:WIDGET_CLASS Method :INPUT_IMAGE (TANGOinput_image()):
(send <tango-widget> :INPUT_IMAGE)
==> returns <tango_image> on success, NIL on failure
This routine prompts the user to select an image from <tango-widget>.
The user clicks down the mouse and this routine returns the uppermost
visible image object whose bounding box (with a little padding, hence
you can select vertical and horizontal lines) encloses the point of
the mouse selection. If a successful image choice is made, the
routine returns the TANGOIMAGEOBJ. If no image was selected, the
routine returns NIL. Be careful with lines; they often have big
bounding boxes. The :TX_RAISE and :TX_LOWER transitions are often
useful aids for inputting images.
*** TANGO:WIDGET_CLASS Method :GET_EVENT_IMAGE (TANGOget_event_image()):
(send <tango-widget> :GET_EVENT_IMAGE <xevent>)
==> returns <tango_image> on success, NIL on failure
<xevent> is typically taken from the CALLBACK_XEVENT or
EVHANDLER_XEVENT values set within widget-class methods
:SET_CALLBACK/:ADD_CALLBACK or :SET_EVHANDLER/:ADD_EVHANDLER.
<xevent> is used to determine the x,y location of a KeyPress,
KeyRelease, ButtonPress, ButtonRelease, MotionNotify, EnterNotify,
or LeaveNotify type event.
Note that if you use the TANGO:WIDGET_CLASS's :XMN_INPUT_CALLBACK
(set by :SET_CALLBACK/:ADD_CALLBACK method), you'll achieve the
semi-useless result of calling the callback function on all
ButtonPress, ButtonRelease, KeyPress, and KeyRelease events.
Instead, you should call the action procedure
Lisp(send ACTION_WIDGET :GET_EVENT_IMAGE ACTION_XEVENT)
from a translation table set-up on <tango-widget> by method
:OVERRIDE_TRANSLATIONS.
(defun printit (act-w act-e)
(print (send act-w :GET_EVENT_IMAGE act-e)))
(send <tango-widget> :override_translations
"<Btn1Down>,<Btn1Up>: Lisp(printit ACTION_WIDGET ACTION_XEVENT)")
One may also use standard event handlers without having to alter the
translation table. Use :SET_EVHANDLER/:ADD_EVHANDLER while specifying
the desired event-mask. (e.g. BUTTON_PRESS_MASK, BUTTON_RELEASE_MASK,
KEY_PRESS_MASK, KEY_RELEASE_MASK).
For example, the following event-handler flashes the tango-image
which was clicked via mouse, as specified by the event-mask
BUTTON_PRESS_MASK.
(send tango_w :set_event_handler BUTTON_PRESS_MASK
'(EVHANDLER_WIDGET EVHANDLER_XEVENT)
'(
(let ((timage (send EVHANDLER_WIDGET :get_event_image
EVHANDLER_XEVENT)))
(if timage
(send timage :tap_flash :perform 1)
))
))
*** TANGO:WIDGET_CLASS Method :GET_EVENT_COORD (TANGOget_event_coord()):
(send <tango-widget> :GET_EVENT_COORD <xevent>)
==> returns #C(<x> <y>) on success, NIL on failure
<xevent> is typically taken from the CALLBACK_XEVENT or
EVHANDLER_XEVENT values set within widget-class methods
:SET_CALLBACK/:ADD_CALLBACK or :SET_EVHANDLER/:ADD_EVHANDLER. <xevent>
is used to determine the x,y location of a KeyPress, KeyRelease,
ButtonPress, ButtonRelease, MotionNotify, EnterNotify, or
LeaveNotify type event.
See method :GET_EVENT_IMAGE above for other useage details.
*** TANGO:WIDGET_CLASS Method :LOAD_COLOR :
(send <tango-widget> :LOAD_COLOR <color-str>)
==> returns a FIXNUM representing a new TANGO_COLOR pixel
value.
<color-str> is a STRING name of a color, typically a name
from /usr/lib/X11/rgb.txt, e.g. "red". One may also specify a
hexadecimal value for the color, e.g. "#FF0000".
See also <<TANGO Colors (TANGO_COLOR):>> for details on
colors in Xtango.
*** TANGO:WIDGET_CLASS Method :SET_BGCOLOR (TANGOset_bgcolor()):
(send <tango-widget> :SET_BGCOLOR <color-str>)
==> returns NIL.
Method :SET_BGCOLOR sets the background color of <tango-widget>
to <color-str>. <color-str> is a STRING name of a color, typically
a name from /usr/lib/X11/rgb.txt, e.g. "red". One may also specify a
hexadecimal value for the color, e.g. "#FF0000".
*** TANGO:WIDGET_CLASS Method :GET_IMAGES :
(send <tango-widget> :GET_IMAGES [<visibility_kwd>])
==> returns a LIST of TANGOIMAGEOBJs.
[<visibility_kwd>] is an optional argument; if the argument is absent,
all the images are returned, both visible and invisible. If
:VISIBLE, then only visible images are returned; if :INVISIBLE,
then only invisible images are returned.
This method queries <tango-widget> returning the desired list
of TANGOIMAGEOBJs, instances of TANGO:IMAGE_CLASS. This
method can be used to save the set of images being displayed
by calling :COLORS_STOREON to save the colormap, followed by
calling :STOREON method on each image...
*** TANGO:WIDGET_CLASS Method :COLORS_STOREON :
(send <tango-widget> :COLORS_STOREON)
==> returns LIST of s-expressions representing calls to
method :LOAD_COLOR which when evaluated, recreates
the colormap of <tango-widget>.
An example of the output LIST from :COLORS_STOREON:
(
(SEND *TANGO_WIDGET* :LOAD_COLOR "black")
(SEND *TANGO_WIDGET* :LOAD_COLOR "maroon")
(SEND *TANGO_WIDGET* :LOAD_COLOR "red")
(SEND *TANGO_WIDGET* :LOAD_COLOR "orange")
(SEND *TANGO_WIDGET* :LOAD_COLOR "blue")
(SEND *TANGO_WIDGET* :LOAD_COLOR "green")
(SEND *TANGO_WIDGET* :LOAD_COLOR "yellow")
(SEND *TANGO_WIDGET* :LOAD_COLOR "white")
...
)
Note: this method should be used prior to 'eval'ing results of
:STOREON on any TANGO:IMAGE_CLASS subclasses. For an example
of using :COLOR_STOREON and :STOREON, see
<winterp-top-dir>/examples/xtango/cls-widget.lsp
which defines a subclass of TANGO:WIDGET_CLASS,
XTANGO-WIDGET-CLASS, and methods :SAVE-IMAGES and :LOAD-IMAGES.
*** TANGO:WIDGET_CLASS Method :COPY_TO_2D_BITMAP_ARRAY :
(send <tango-widget> :COPY_TO_2D_BITMAP_ARRAY <x> <y> <width> <height>)
==> returns ARRAY of TANGO_COLOR values of the form:
#(#( <0,0> ... <width-1,0> )
.
.
.
#( <0,height-1> ... <width-1,height-1>)
)
<x> <y> <width> and <height> are FLONUM's representing the area of
the <tango-widget> to copy into a 2D_BITMAP_ARRAY. The size of the
returned array is the integer size represented by those args.
USAGE: (send <tango-w> :COPY_TO_2D_BITMAP_ARRAY 0.0 0.0 1.0 1.0)
returns a bitmap representing all the images in <tango-w> (where
values 0.0,1.0 represent default initial :PAN/:ZOOM factors. To
reset <tango-widget> to defaults prior to calling this routine,
evaluate the following:
(send <tango-widget> :SET_COORD 0.0 1.0 1.0 0.0)
NOTE: you should 'eval' the results of :COLORS_STOREON prior to
creating a new bitmap image with the results of
:COPY_TO_2D_BITMAP_ARRAY.
** TANGO Images (TANGO_IMAGE):
The TANGOIMAGEOBJ is an object describing a particular
graphical image being displayed within a TANGO:WIDGET_CLASS
instance. In this implementation an image can be a line,
rectangle, circle, ellipse, polyline, polygon, spline,
bitmap, GIF, text, or a composite of the previous types.
Rectangles, circles, ellipses, and polygons can have varying fill
styles. Lines can have different thicknesses and styles. Currently,
this base set of images is limited to provide a simpler basis to
design animations.
The WINTERP interface to XTANGO allows programmers to use the XLISP
object system to create new images with new functionality and
encapsulated animation capabilities by subclassing and/or composing the
previously mentioned image types.
*** Function TANGO:IMAGEOBJP:
(TANGOIMAGEOBJP <expr>)
==> returns T if argument is a TANGOIMAGEOBJ, else NIL.
*** Function TANGO:TAP_EXCHANGE (TAPexchange()):
(TANGO:TAP_EXCHANGE [:PERFORM] <image-1> <image-2>)
==> returns <tango_trans> object,
or NIL if :PERFORM keyword given.
This function exchanges the positions of TANGOIMAGEOBJs
<image-1> and <image-2>. It is similar to TANGO:TAP_SWITCH,
however, it moves each image over a path of length 20 using
TANGO:PATH_MOTION, causing the positions to switch "smoothly".
*** Function TANGO:TAP_SWITCH (TAPswitch()):
(TANGO:TAP_SWITCH [:PERFORM] <image-1> <image-2>)
==> returns <tango_trans> object,
or NIL if :PERFORM keyword given.
This routine swaps two images; that is, <image-1> will acquire
<image-2>'s location and vice versa. The path that each image
follows has a length of one, so the two images will appear to "jump"
to their new locations. For a "smooth" version of this functionality,
see TANGO:TAP_EXCHANGE.
*** TANGO:IMAGE_CLASS -- the xtango image base class
All other WINTERP/Xtango image classes are subclasses of this class.
**** TANGO:IMAGE_CLASS method :NEW/:ISNEW :
TANGO:IMAGE_CLASS is not instantiable. An error will occur if
you try to instantiate this class. Subclasses of this class
are instantiable.
**** TANGO:IMAGE_CLASS method :EXISTS_P :
(send <tiobj> :EXISTS_P)
==> returns T if the TANGOIMAGEOBJ exists (hasn't been
destroyed)
==> returns NIL if the TANGOIMAGEOBJ has been destroyed
or has never been initialized.
**** TANGO:IMAGE_CLASS method :IMAGE_COPY (TANGOimage_copy()):
(send <tiobj> :IMAGE_COPY)
==> returns a TANGOIMAGEOBJ.
This method returns a new instance of TANGO:IMAGE_CLASS (or a
subclass thereof) which is an exact copy of the one given as a
parameter <tiobj> (at that instant in time). The new image will not
appear until a transition is performed, or until a :REFRESH message
is sent to the TANGO:WIDGET_CLASS instance in which the image
resides. This behavior is similar to other cases of TANGO:IMAGE_CLASS
instance creation (method :NEW).
**** TANGO:IMAGE_CLASS method :TX_MOVE (TANGO_TRANS_TYPE_MOVE):
(send <t-image-obj> :TX_MOVE [:PERFORM] [<path>])
==> returns <tango_trans> object, or NIL if :PERFORM given
The MOVE transition moves the given <t-image-obj> along the given
<path> (see below). The first movement of the image corresponds to
the first relative offset in the path. All these relative offsets are
with respect to the image's previous position on the screen.
The optional :PERFORM keyword argument specifies that the transition
is to be performed immediately (see TANGO:TRANS_PERFORM). If :PERFORM
is omitted, then a <tango_trans> object is returned (useful for
storing- or operating-on- complex transitions via TANGO:TX_ITERATE,
TANGO:TX_CONCATENATE, TANGO:TX_COMPOSE.
The [<path>] argument is optional, and may be of multiple types:
* if the <path> argument is omitted, then a path of length one with
both x and y offsets set to 0.0 is used as the path for the
transition (see TANGOpath_null() in doc/xtangodoc.tex);
* else, if <path> is of type TANGO_PATH, then that is used as the path
for the transition to take. TANGO:PATH_CREATE, and other
TANGO:PATH_* functions return such TANGO_PATH typed results;
* else, if <path> is of type FIXNUM, then a path of length <path> with
both x and y offsets set to 0.0 is used as the path for the
transition (see TANGOpath_null() in doc/xtangodoc.tex);
* else, if <path> is of type COMPLEX (e.g. #C(<x> <y>), then a path of
length one is used with x and y offsets set to <x> and <y>.)
* else, if <path> is a sequence (LIST or ARRAY) of COMPLEX #C(<x> <y>),
then a path of the same length as the sequence is created,
with the x and y offsets set to the corresponding <x> <y>.
Note: all <path> arg types other than TANGO_PATH are used here for
convenience in creating transitions over simple, unique
paths. "Simple cases" constitute paths which don't need to be be
re-used, or altered via calls to TANGO:PATH_* functions.
**** TANGO:IMAGE_CLASS method :TX_VISIBLE (TANGO_TRANS_TYPE_VISIBLE):
(send <t-image-obj> :TX_VISIBLE [:PERFORM] [<path>])
==> returns <tango_trans> object, or NIL if :PERFORM given
The VISIBLE transition switches the visibility of the given
<t-image-obj> for each offset in the given <path>. At each offset in
the path, if the image is visible, it will become invisible, and
vice-versa. Note that the actual <x>,<y> offsets in the path are
ignored for this transition, therefore the optional <path> argument
could be ommitted (to create a "null" path of length 1) or a FIXNUM
(to create a "null" path of length of the FIXNUM).
The optional :PERFORM keyword argument specifies that the transition
is to be performed immediately (see TANGO:TRANS_PERFORM). If :PERFORM
is omitted, then a <tango_trans> object is returned (useful for
storing- or operating-on- complex transitions via TANGO:TX_ITERATE,
TANGO:TX_CONCATENATE, TANGO:TX_COMPOSE.
The [<path>] argument is optional, and may be of multiple types:
* if the <path> argument is omitted, then a path of length one with
both x and y offsets set to 0.0 is used as the path for the
transition (see TANGOpath_null() in doc/xtangodoc.tex);
* else, if <path> is of type TANGO_PATH, then that is used as the path
for the transition to take. TANGO:PATH_CREATE, and other
TANGO:PATH_* functions return such TANGO_PATH typed results;
* else, if <path> is of type FIXNUM, then a path of length <path> with
both x and y offsets set to 0.0 is used as the path for the
transition (see TANGOpath_null() in doc/xtangodoc.tex);
* else, if <path> is of type COMPLEX (e.g. #C(<x> <y>), then a path of
length one is used with x and y offsets set to <x> and <y>.)
* else, if <path> is a sequence (LIST or ARRAY) of COMPLEX #C(<x> <y>),
then a path of the same length as the sequence is created,
with the x and y offsets set to the corresponding <x> <y>.
Note: all <path> arg types other than TANGO_PATH are used here for
convenience in creating transitions over simple, unique
paths. "Simple cases" constitute paths which don't need to be be
re-used, or altered via calls to TANGO:PATH_* functions.
**** TANGO:IMAGE_CLASS method :TX_RAISE (TANGO_TRANS_TYPE_RAISE):
(send <t-image-obj> :TX_RAISE [:PERFORM] [<path>])
==> returns <tango_trans> object,
or NIL if :PERFORM keyword given.
The RAISE transition brings the given <t-image-obj> to the viewing
plane closest to the viewer. The image's position is not changed,
only its relative ordering (top to bottom) with respect to other
images. Note that the actual <x>,<y> offsets in the path are ignored
for this transition, therefore the optional <path> argument could be
ommitted (to create a "null" path of length 1) or a FIXNUM (to create
a "null" path of length of the FIXNUM).
The optional :PERFORM keyword argument specifies that the transition
is to be performed immediately (see TANGO:TRANS_PERFORM). If :PERFORM
is omitted, then a <tango_trans> object is returned (useful for
storing- or operating-on- complex transitions via TANGO:TX_ITERATE,
TANGO:TX_CONCATENATE, TANGO:TX_COMPOSE.
**** TANGO:IMAGE_CLASS method :TX_LOWER (TANGO_TRANS_TYPE_LOWER):)
(send <t-image-obj> :TX_LOWER [:PERFORM] [<path>])
==> returns <tango_trans> object,
or NIL if :PERFORM keyword given.
The LOWER transition pushes the given <t-image-obj> to the viewing
plane farthest from the viewer. The image's position is not changed,
only its relative ordering (top to bottom) with respect to other
images. It will possibly be obscured by every other image. Note that
the actual <x>,<y> offsets in the path are ignored for this
transition, therefore the optional <path> argument could be ommitted
(to create a "null" path of length 1) or a FIXNUM (to create a "null"
path of length of the FIXNUM).
The optional :PERFORM keyword argument specifies that the transition
is to be performed immediately (see TANGO:TRANS_PERFORM). If :PERFORM
is omitted, then a <tango_trans> object is returned (useful for
storing- or operating-on- complex transitions via TANGO:TX_ITERATE,
TANGO:TX_CONCATENATE, TANGO:TX_COMPOSE.
**** TANGO:IMAGE_CLASS method :TX_DELAY (TANGO_TRANS_TYPE_DELAY):
(send <t-image-obj> :TX_DELAY [:PERFORM] [<path>])
==> returns <tango_trans> object,
or NIL if :PERFORM keyword given.
The DELAY transition creates a transition which has a null frame for
each offset in the path. By null frame, we mean that no action or
modification is performed. This transition is helpful when combined
with concatenation in order to produce actions that commence at
varying times. The image used in this transition does not matter.
Note that the actual <x>,<y> offsets in the path are ignored for this
transition, therefore the optional <path> argument could be ommitted
(to create a "null" path of length 1) or a FIXNUM (to create a "null"
path of length of the FIXNUM).
The optional :PERFORM keyword argument specifies that the transition
is to be performed immediately (see TANGO:TRANS_PERFORM). If :PERFORM
is omitted, then a <tango_trans> object is returned (useful for
storing- or operating-on- complex transitions via TANGO:TX_ITERATE,
TANGO:TX_CONCATENATE, TANGO:TX_COMPOSE.
**** TANGO:IMAGE_CLASS method :TX_REFRESH (TANGO_TRANS_TYPE_REFRESH):
(send <t-image-obj> :TX_REFRESH [:PERFORM] [<path>])
==> returns <tango_trans> object,
or NIL if :PERFORM keyword given.
The REFRESH transition redraws the entire animation window, restoring
it to a pristine state. This is useful when running TANGO in fast
mode (non-total frame by frame refresh) and you would like to clean
up damage to the screen. A refresh is done for each offset in the
path, i.e., there's no need for more than one offset in the path.
The image used in this transition does not matter. Note that the
actual <x>,<y> offsets in the path are ignored for this transition,
therefore the optional <path> argument could be ommitted (to create a
"null" path of length 1) or a FIXNUM (to create a "null" path of
length of the FIXNUM).
The optional :PERFORM keyword argument specifies that the transition
is to be performed immediately (see TANGO:TRANS_PERFORM). If :PERFORM
is omitted, then a <tango_trans> object is returned (useful for
storing- or operating-on- complex transitions via TANGO:TX_ITERATE,
TANGO:TX_CONCATENATE, TANGO:TX_COMPOSE.
**** TANGO:IMAGE_CLASS method :TX_DELETE (TANGO_TRANS_TYPE_DELETE):
(send <t-image-obj> :TX_DELETE [:PERFORM] [<path>])
==> returns <tango_trans> object,
or NIL if :PERFORM keyword given.
The DELETE transition makes an image invisible (if not already) and
removes it from any possible later usage. Any attempts to use this
image as a parameter in subsequent TANGO calls will result in error
messages. Also, pre-existing transitions with this image as a
parameter should not be performed (they'll be ignored in
WINTERP). Note that the actual <x>,<y> offsets in the path are
ignored for this transition, therefore the optional <path> argument
may be ommitted, to create a "null" path of length 1.
The optional :PERFORM keyword argument specifies that the transition
is to be performed immediately (see TANGO:TRANS_PERFORM). If :PERFORM
is omitted, then a <tango_trans> object is returned (useful for
storing- or operating-on- complex transitions via TANGO:TX_ITERATE,
TANGO:TX_CONCATENATE, TANGO:TX_COMPOSE.
**** TANGO:IMAGE_CLASS method :TX_ZOOM (TANGO_TRANS_TYPE_ZOOM):
(send <t-image-obj> :TX_ZOOM [:PERFORM] [<path>])
==> returns <tango_trans> object,
or NIL if :PERFORM keyword given.
The ZOOM transition zooms the window in or out on the positional
location of the image argument <t-image-obj>. The <x> and <y>
components of a path element #C(<x> <y>) determine how the zooming
should occur. They should be between 0.0 and 1.0. Values close to
1.0 will zoom in very tight. Values near 0.0 do a slow zoom. To get
a nice slow, smooth zoom in on an object, use a path with quite a few
offsets all of equal ``small'' offset values, such as #C(0.1 0.1).
Positive offset values zoom the display in, negative offset values
pull the display back out.
The optional :PERFORM keyword argument specifies that the transition
is to be performed immediately (see TANGO:TRANS_PERFORM). If :PERFORM
is omitted, then a <tango_trans> object is returned (useful for
storing- or operating-on- complex transitions via TANGO:TX_ITERATE,
TANGO:TX_CONCATENATE, TANGO:TX_COMPOSE.
The [<path>] argument is optional, and may be of multiple types:
* if the <path> argument is omitted, then a path of length one with
both x and y offsets set to 0.0 is used as the path for the
transition (see TANGOpath_null() in doc/xtangodoc.tex);
* else, if <path> is of type TANGO_PATH, then that is used as the path
for the transition to take. TANGO:PATH_CREATE, and other
TANGO:PATH_* functions return such TANGO_PATH typed results;
* else, if <path> is of type FIXNUM, then a path of length <path> with
both x and y offsets set to 0.0 is used as the path for the
transition (see TANGOpath_null() in doc/xtangodoc.tex);
* else, if <path> is of type COMPLEX (e.g. #C(<x> <y>), then a path of
length one is used with x and y offsets set to <x> and <y>.
* else, if <path> is a sequence (LIST or ARRAY) of COMPLEX #C(<x> <y>),
then a path of the same length as the sequence is created,
with the x and y offsets set to the corresponding <x> <y>.
Note: all <path> arg types other than TANGO_PATH are used here for
convenience in creating transitions over simple, unique
paths. "Simple cases" constitute paths which don't need to be be
re-used, or altered via calls to TANGO:PATH_* functions.
**** TANGO:IMAGE_CLASS method :TAP_SHOW (TAPshow()):
(send <tiobj> :TAP_SHOW)
==> returns NIL
This method simply displays the <tiobj> (i.e. uses a delay transition
to display the object -- see method :TX_DELAY). Creating a
TANGO:IMAGE_CLASS instance will not cause the image to appear on the
display until until a subsequent animation occurs, therefore this
routine is useful for making sure that an image is properly displayed.
Note that including the optional :SHOW keyword during xtango
image creation does the equivalent of calling this function
after the tango image object gets created.
Note that if a large number of images are to be displayed, it is more
efficient to do a :REFRESH on the TANGO:WIDGET_CLASS instance after
all the images have been created. The same applies to using
the optional :SHOW keyword for image creation.
**** TANGO:IMAGE_CLASS method :TAP_FILL (TAPfill()):
(send <tiobj> :TAP_FILL [:PERFORM])
==> returns <tango_trans> object
or NIL if :PERFORM keyword given.
This method creates (and optionally :PERFORMs) the transition needed
to fill the given image to a solid color. The color being the
color specified during image creation, or the color specified
by a subsequent transition, caused by :TAP_COLOR or
:TX_COLOR. This method is similar to :TX_FILL, except that it
changes the fill value to 100%...
**** TANGO:IMAGE_CLASS method :TAP_COLOR (TAPcolor()):
(send <tiobj> :TAP_COLOR [:PERFORM] <tango-color>)
==> returns <tango_trans> object,
or NIL if :PERFORM keyword given.
<tango-color> gives the color to which the image is changed when the
transition is performed. This method is a short-hand version of
:TX_COLOR. <tango-color> can either be a string color name (e.g.
"white" "black" "red" "orange" "yellow" "green" "blue" or "maroon".).
Alternately, <tango-color> can be a FIXNUM [0-7] representing the
tango-color pixel value. FIXNUM values for the standard Xtango colors
are specified via the constants TANGO_COLOR_WHITE, TANGO_COLOR_BLACK,
TANGO_COLOR_RED, TANGO_COLOR_ORANGE, TANGO_COLOR_YELLOW,
TANGO_COLOR_GREEN, TANGO_COLOR_BLUE, or TANGO_COLOR_MAROON.
Note that :TAP_COLOR, :TX_COLOR, and TANGO:PATH_COLOR only work with
the eight "basic" tango colors mentioned above. Using colors other
than the eight aforementioned colors, or using colors generated by
TANGO:WIDGET_CLASS method :LOAD_COLOR will signal an error.
**** TANGO:IMAGE_CLASS method :TAP_VIS_TOGGLE (TAPvis_toggle()):
(send <tiobj> :TAP_VIS_TOGGLE [:PERFORM])
==> returns <tango_trans> object,
or NIL if :PERFORM keyword given.
This method creates (and optionally :PERFORMs) the transition needed
to toggle the visibility of <tiobj> and returns this transition.
This method is a short-hand version of method :TX_VISIBLE.
**** TANGO:IMAGE_CLASS method :TAP_JUMP (TAPjump()):
(send <tiobj> :TAP_JUMP [:PERFORM] <image_part_kwd> <location>)
==> returns <tango_trans> object,
or NIL if :PERFORM keyword given.
<image_part_kwd> is a keyword argument, one of:
:CTR -- center
:NW -- north west
:NE -- north east
:E -- east
:SE -- south east
:S -- south
:SW -- south west
:W -- west
<location> is a COMPLEX FLONUM #C(<x> <y>) representing the x/y
coordinates of a location.
This method sets up a transition to move <tiobj> to the given
<location> using the specified <image_part_kwd> as a "handle." The
transition uses a path of length one, so essentially, the image will
appear to "jump" from its current location to the new location. The
necessary transition is returned.
**** TANGO:IMAGE_CLASS method :TAP_MOVE (TAPmove()):
(send <tiobj> :TAP_MOVE [:PERFORM] <image_part_kwd> <location>)
==> returns <tango_trans> object,
or NIL if :PERFORM keyword given.
<image_part_kwd> is a keyword argument, one of:
:CTR -- center
:NW -- north west
:NE -- north east
:E -- east
:SE -- south east
:S -- south
:SW -- south west
:W -- west
<location> is a COMPLEX FLONUM #C(<x> <y>) representing the x/y
coordinates of a location.
This method sets up a transition to move <tiobj> from the location of
its indicated <image_part_kwd> to the given <location>. This method
is similar to method :TAP_JUMP; however, instead of using a path of
length one to create the transition, it uses TANGO:PATH_MOTION to
create the transition, which means that the path length is 20. The
required transition is returned.
**** TANGO:IMAGE_CLASS method :TAP_TRAVERSE (TAPtraverse()):
(send <tiobj> :TAP_TRAVERSE [:PERFORM]
<image_part_kwd>
<location>
<path_motion_kwd>)
==> returns <tango_trans> object,
or NIL if :PERFORM keyword given.
<image_part_kwd> is a keyword argument, one of:
:CTR -- center
:NW -- north west
:NE -- north east
:E -- east
:SE -- south east
:S -- south
:SW -- south west
:W -- west
<location> is a COMPLEX FLONUM #C(<x> <y>) representing the x/y
coordinates of a location.
<path_motion_kwd> is a keyword, either :STRAIGHT, :CLOCKWISE,
or :COUNTERCLOCKWISE.
This routine creates the transition necessary to move an object
(using the specified <image_part_kwd> of the object) from its current
position to <location>. The type of path that the object follows is
given by the parameter <path_motion_kwd>; <path_motion_kwd> is simply
a path type, i.e. it is of the same form as the path types for the
TANGO:PATH_MOTION routine.
**** TANGO:IMAGE_CLASS method :TAP_FLASH (TAPflash()):
(send <tiobj> :TAP_FLASH [:PERFORM] <num_flash_fixnum>)
==> returns <tango_trans> object,
or NIL if :PERFORM keyword given.
This method causes <tiobj> to toggle between visible and invisible
for the given number of times. This makes an object appear
to flash. This method is a short-hand version of method :TX_VISIBLE.
*** TANGO:BITMAP_IMAGE_CLASS (TANGO_IMAGE_TYPE_BITMAP)
**** TANGO:BITMAP_IMAGE_CLASS method :NEW/:ISNEW (TANGOimage_create()):
(send TANGO:BITMAP_IMAGE_CLASS :new
[:show] [<visible_kwd>] <tango_widget>
<location_coord>
<bitmap_array>
)
==> RETURNS an <tango_image> object.
[:show] -- OPTIONAL :show keyword. If present, displays image
immediately, else the image will be displayed along with the next
animation frame. See :TAP_SHOW :TX_DELAY.
[<visible_kwd>] -- OPTIONAL :VISIBLE or :INVISIBLE keyword. If
omitted, :VISIBLE is assumed. See also :TX_VISIBLE, :TAP_VIS_TOGGLE.
<tango_widget> -- an instance of TANGO:WIDGET_CLASS.
<location_coord> -- the location for placing the bitmap image. A
COMPLEX number, of form #C(<loc_x> <loc_y>), where
<loc_x> is a FLONUM, typically [0.0 - 1.0] representing the X-axis
location; <loc_y> is a FLONUM, typically [0.0 - 1.0] representing the
Y-axis location. See <<TANGO Locations and Coordinates (TANGO_LOC):>>
section above.
<bitmap_array> -- a 3-D array of FIXNUMs (TANGO_COLOR). Each FIXNUM
represents a Pixel (TANGO_COLOR) value. For example, a "movie"
consisting of 3 4x4 bitmaps is represented by the following:
#(#(#(1 1 1 1)
#(7 7 7 7)
#(7 7 7 7)
#(7 7 7 7))
#(#(7 7 7 1)
#(7 7 1 7)
#(7 1 7 7)
#(1 7 7 7))
#(#(7 7 7 1)
#(7 7 7 1)
#(7 7 7 1)
#(7 7 7 1)))
**** TANGO:BITMAP_IMAGE_CLASS method :STOREON
(send <bitmap-image> :STOREON)
==> returns list
(send TANGO:BITMAP_IMAGE_CLASS :new <visibility_kwd>
*TANGO_WIDGET*
#C(<location-x> <location-y)
#( <bitmap-array-1> <bitmap-array-2> ... ))
See <<TANGO:BITMAP_IMAGE_CLASS method :NEW/:ISNEW...>>
for details on the returned data.
Evaluating the results of this method will create a copy of the given
image at a later time. Printing the results of this method to a file
enables one to store a persistent copy of the given image to
disk. See also TANGO:WIDGET_CLASS method :GET_IMAGES and
:COLORS_STOREON.
**** TANGO:BITMAP_IMAGE_CLASS method :TX_SHUFFLE
(send <bitmap-image> :TX_SHUFFLE [:PERFORM] [<path>])
==> returns <tango_trans> object, or NIL if :PERFORM keyword given
The SHUFFLE transition affects only the TANGO:BITMAP_IMAGE_CLASS. For
each offset in the <path> argument, the next 2-d bitmap in the image's
series will be displayed. The series is considered circular, i.e.,
the successor of the last bitmap is the first bitmap. This transition
is useful to get a certain effect such as a door opening. To do this,
define a BITMAP image with a series of individual bitmaps showing the
various stages of the door opening. Then run a SHUFFLE transition to
animate that occurrance. Note that the actual <x>,<y> offsets in the
path are ignored for this transition, therefore the optional <path>
argument could be ommitted (to create a "null" path of length 1) or a
FIXNUM (to create a "null" path of length of the FIXNUM).
The optional :PERFORM keyword argument specifies that the transition
is to be performed immediately (see TANGO:TRANS_PERFORM). If :PERFORM
is omitted, then a <tango_trans> object is returned (useful for
storing- or operating-on- complex transitions via TANGO:TX_ITERATE,
TANGO:TX_CONCATENATE, TANGO:TX_COMPOSE.
The [<path>] argument is optional, and may be of multiple types:
* if the <path> argument is omitted, then a path of length one
with both x and y offsets set to 0.0 is used as the path for
the transition (see TANGOpath_null() in doc/xtangodoc.tex);
* else, if <path> is of type TANGO_PATH, then that is used as
the path for the transition to take. TANGO:PATH_CREATE, and
other TANGO:PATH_* functions return such TANGO_PATH typed
results;
* else, if <path> is of type FIXNUM, then a path of length
<path> with both x and y offsets set to 0.0 is used as the
path for the transition (see TANGOpath_null() in
doc/xtangodoc.tex);
* else, if <path> is of type COMPLEX (e.g. #C(<x> <y>), then
a path of length one is used with x and y offsets set to <x>
and <y>.)
* else, if <path> is a sequence (LIST or ARRAY) of COMPLEX
#C(<x> <y>), then a path of the same length as the sequence
is created, with the x and y offsets set to the corresponding
<x> <y>.
Note: all <path> arg types other than TANGO_PATH are used here for
convenience in creating transitions over simple, unique paths.
"Simple cases" constitute paths which don't need to be be re-used, or
altered via calls to TANGO:PATH_* functions.
**** TANGO:BITMAP_IMAGE_CLASS method :IMAGE_LOC (TANGOimage_loc()):
(send <tiobj> :IMAGE_LOC <image_part_kwd>)
==> returns a COMPLEX number #C(<x> <y>), where <x> and <y>
are FLONUMS representing the location of the image
<image_part_kwd> is a keyword argument, one of:
:CTR -- center
:NW -- north west
:NE -- north east
:E -- east
:SE -- south east
:S -- south
:SW -- south west
:W -- west
This routine returns a COMPLEX FLONUM #C(<x> <y>) that corresponds to
the location of the given <image_part_kwd> of the given <tiobj>.
Valid <image_part_kwd> include :CTR (center), and the compass
directions :NW, :N, :NE, :E, :SE, :S, :SW, :W. Given that the
bitmap is a rectangular image, the locations specified by
<image_part_kwd> represent the actual boundaries of the image.
*** TANGO:CIRCLE_IMAGE_CLASS (TANGO_IMAGE_TYPE_CIRCLE):
**** TANGO:CIRCLE_IMAGE_CLASS method :NEW/:ISNEW (TANGOimage_create()):
(send TANGO:CIRCLE_IMAGE_CLASS :new
[:show] [<visible_kwd>] <tango_widget>
<location_coord>
<size_coord>
<tango_color>
<fill_float>
)
==> RETURNS an <tango_image> object.
[:show] -- OPTIONAL :show keyword. If present, displays image
immediately, else the image will be displayed along with the next
animation frame. See :TAP_SHOW :TX_DELAY.
[<visible_kwd>] -- OPTIONAL :VISIBLE or :INVISIBLE keyword. If
omitted, :VISIBLE is assumed. See also :TX_VISIBLE, :TAP_VIS_TOGGLE.
<tango_widget> -- an instance of TANGO:WIDGET_CLASS.
<location_coord> -- the location for placing the circle image. A
COMPLEX number, of form #C(<loc_x> <loc_y>), where
<loc_x> is a FLONUM, typically [0.0 - 1.0] representing the X-axis
location; <loc_y> is a FLONUM, typically [0.0 - 1.0] representing the
Y-axis location. See <<TANGO Locations and Coordinates (TANGO_LOC):>>
section above.
<size_coord> -- The radius of the circle image, COMPLEX or
FLONUM. If COMPLEX, then the 'realpart' is taken as the radius.
Type COMPLEX is accepted for this parameter for consistency
with TANGO:RECTANGLE_IMAGE_CLASS and TANGO:ELLIPSE_IMAGE_CLASS
<tango_color> -- The color of the image; it can either be a string
color name, or a FIXNUM representing the tango pixel value. If given
a string, it is looked up in the X11 file /usr/lib/X11/rgb.txt.
See <<TANGO Colors (TANGO_COLOR):>> section above for details.
<fill_float> -- the fill value of the image, a FLONUM between
0.0 and 1.0. 0.0 corresponds to an unfilled outline and 1.0
corresponds to 100 per cent fill in the given color.
(Forty graduated fill styles are actually implemented.)
**** TANGO:CIRCLE_IMAGE_CLASS method :STOREON
(send <circle-image> :STOREON)
==> returns list
(send TANGO:CIRCLE_IMAGE_CLASS :new <visibility_kwd>
*TANGO_WIDGET*
#C(<location-x> <location-y)
<radius_float>
<tango_color>
<fill_float>)
See <<TANGO:CIRCLE_IMAGE_CLASS method :NEW/:ISNEW...>>
for details on the returned data.
Evaluating the results of this method will create a copy of the given
image at a later time. Printing the results of this method to a file
enables one to store a persistent copy of the given image to
disk. See also TANGO:WIDGET_CLASS method :GET_IMAGES and
:COLORS_STOREON.
**** TANGO:CIRCLE_IMAGE_CLASS method :IMAGE_LOC (TANGOimage_loc()):
(send <tiobj> :IMAGE_LOC <image_part_kwd>)
==> returns a COMPLEX number #C(<x> <y>), where <x> and <y>
are FLONUMS representing the location of the image
<image_part_kwd> is a keyword argument, one of:
:CTR -- center
:NW -- north west
:NE -- north east
:E -- east
:SE -- south east
:S -- south
:SW -- south west
:W -- west
This routine returns a COMPLEX FLONUM #C(<x> <y>) that corresponds to
the location of the given <image_part_kwd> of the given <tiobj>.
Valid <image_part_kwd> include :CTR (center), and the compass
directions :NW, :N, :NE, :E, :SE, :S, :SW, :W. Given that the
bitmap is a circle, the locations specified by
<image_part_kwd> represent the actual boundaries of the image.
**** TANGO:CIRCLE_IMAGE_CLASS method :TX_COLOR (TANGO_TRANS_TYPE_COLOR):
(send <t-image-obj> :TX_COLOR [:PERFORM] [<path>])
==> returns <tango_trans> object,
or NIL if :PERFORM keyword given.
The COLOR transition changes the given <t-image-obj> to the color
indicated by the given <path>. See the routine TANGO:PATH_COLOR to
create a special path which will change the image to a certain
color. Using an arbitrary TANGO_PATH type argument, or using one of
the other alternatives for the <path> argument list (as used
in other :TX_* methods) will generate undefined results.
The optional :PERFORM keyword argument specifies that the transition
is to be performed immediately (see TANGO:TRANS_PERFORM). If :PERFORM
is omitted, then a <tango_trans> object is returned (useful for
storing- or operating-on- complex transitions via TANGO:TX_ITERATE,
TANGO:TX_CONCATENATE, TANGO:TX_COMPOSE.
**** TANGO:CIRCLE_IMAGE_CLASS method :TX_FILL (TANGO_TRANS_TYPE_FILL):
(send <t-image-obj> :TX_FILL [:PERFORM] [<path>])
==> returns <tango_trans> object,
or NIL if :PERFORM keyword given.
The FILL transition changes the "fill" component of the given image
<t-image-obj>. This transition alters the image's fill style value by
the <x> value of the offsets in <path>. The <x> value is simply
added to the existing fill value of <t-image-obj>, the <y> value is
ignored. If the image's fill value goes below 0.0, it is
automatically set back to 0.0. If it goes above 1.0, it is set back
to 1.0. Actually, the full range of values between 0.0 and 1.0 is
not available. We currently implement 40 different fills that range
between the two extremes.
The optional :PERFORM keyword argument specifies that the transition
is to be performed immediately (see TANGO:TRANS_PERFORM). If :PERFORM
is omitted, then a <tango_trans> object is returned (useful for
storing- or operating-on- complex transitions via TANGO:TX_ITERATE,
TANGO:TX_CONCATENATE, TANGO:TX_COMPOSE.
The [<path>] argument is optional, and may be of multiple types:
* if the <path> argument is omitted, then a path of length one with
both x and y offsets set to 0.0 is used as the path for the
transition (see TANGOpath_null() in doc/xtangodoc.tex);
* else, if <path> is of type TANGO_PATH, then that is used as the path
for the transition to take. TANGO:PATH_CREATE, and other
TANGO:PATH_* functions return such TANGO_PATH typed results;
* else, if <path> is of type FIXNUM, then a path of length <path> with
both x and y offsets set to 0.0 is used as the path for the
transition (see TANGOpath_null() in doc/xtangodoc.tex);
* else, if <path> is of type COMPLEX (e.g. #C(<x> <y>), then a path of
length one is used with x and y offsets set to <x> and <y>.
* else, if <path> is a sequence (LIST or ARRAY) of COMPLEX #C(<x> <y>),
then a path of the same length as the sequence is created,
with the x and y offsets set to the corresponding <x> <y>.
Note: all <path> arg types other than TANGO_PATH are used here for
convenience in creating transitions over simple, unique
paths. "Simple cases" constitute paths which don't need to be be
re-used, or altered via calls to TANGO:PATH_* functions.
**** TANGO:CIRCLE_IMAGE_CLASS method :TX_RESIZE (TANGO_TRANS_TYPE_RESIZE):
(send <t-image-obj> :TX_RESIZE [:PERFORM] [<path>])
==> returns <tango_trans> object,
or NIL if :PERFORM keyword given.
The RESIZE transition resizes the given <t-image-obj> along the given
<path>. TANGO:CIRCLE_IMAGE_CLASS instances are resized by modifying
the circle's radius by the amount given in the <x> component of each
offset in the <path>. The <y> component of <path> is ignored.
The optional :PERFORM keyword argument specifies that the transition
is to be performed immediately (see TANGO:TRANS_PERFORM). If :PERFORM
is omitted, then a <tango_trans> object is returned (useful for
storing- or operating-on- complex transitions via TANGO:TX_ITERATE,
TANGO:TX_CONCATENATE, TANGO:TX_COMPOSE.
The [<path>] argument is optional, and may be of multiple types:
* if the <path> argument is omitted, then a path of length one with
both x and y offsets set to 0.0 is used as the path for the
transition (see TANGOpath_null() in doc/xtangodoc.tex);
* else, if <path> is of type TANGO_PATH, then that is used as the path
for the transition to take. TANGO:PATH_CREATE, and other
TANGO:PATH_* functions return such TANGO_PATH typed results;
* else, if <path> is of type FIXNUM, then a path of length <path> with
both x and y offsets set to 0.0 is used as the path for the
transition (see TANGOpath_null() in doc/xtangodoc.tex);
* else, if <path> is of type COMPLEX (e.g. #C(<x> <y>), then a path of
length one is used with x and y offsets set to <x> and <y>.
* else, if <path> is a sequence (LIST or ARRAY) of COMPLEX #C(<x> <y>),
then a path of the same length as the sequence is created,
with the x and y offsets set to the corresponding <x> <y>.
Note: all <path> arg types other than TANGO_PATH are used here for
convenience in creating transitions over simple, unique
paths. "Simple cases" constitute paths which don't need to be be
re-used, or altered via calls to TANGO:PATH_* functions.
*** TANGO:COMPOSITE_IMAGE_CLASS (TANGO_IMAGE_TYPE_COMPOSITE):
**** TANGO:COMPOSITE_IMAGE_CLASS method :NEW/:ISNEW (TANGOimage_create()):
(send TANGO:COMPOSITE_IMAGE_CLASS :new
[:show] [<visible_kwd>] <tango_widget>
<location_coord>
<class-specific-image-instance-creation-arg>
[<class-specific-image-instance-creation-arg>
...
[<class-specific-image-instance-creation-arg>]]
)
==> RETURNS an <tango_image> object.
[:show] -- OPTIONAL :show keyword. If present, displays image
immediately, else the image will be displayed along with the next
animation frame. See :TAP_SHOW :TX_DELAY.
[<visible_kwd>] -- OPTIONAL :VISIBLE or :INVISIBLE keyword. If
omitted, :VISIBLE is assumed. See also :TX_VISIBLE, :TAP_VIS_TOGGLE.
<tango_widget> -- an instance of TANGO:WIDGET_CLASS.
<location_coord> -- the location for placing the composite image. A
COMPLEX number, of form #C(<loc_x> <loc_y>), where <loc_x> is a FLONUM,
typically [0.0 - 1.0] representing the X-axis location; <loc_y> is a
FLONUM, typically [0.0 - 1.0] representing the Y-axis location. See
<<TANGO Locations and Coordinates (TANGO_LOC):>> section above.
[class-specific-image-instance-creation-arg> is a sequence of
arguments representing the image-class-specific data needed to create
an instance of the specified class, e.g.
TANGO:TEXT_IMAGE_CLASS #C(0.25 0.25) :ctr "text image class"
TANGO_COLOR_MAROON "6x13"
Each sequence [class-specific-image-instance-creation-args...] becomes
an element displayed in the composite image. The order, types and
numbers of parameters correspond to the arguments used in creating a
tango-image (see :NEW method descriptions for all the other subclasses
of TANGO:IMAGE_CLASS). For example, if some images were created with
the following code
(send TANGO:CIRCLE_IMAGE_CLASS :new :show tango_w
#C(0.25 0.25) 0.2 t TANGO_COLOR_MAROON 1.0)
(send TANGO:POLYGON_IMAGE_CLASS :new :show tango_w
#C(0.50 0.50) #C(0.10 0.10) #C(0.10 0.10)
"red" 1.0)
then you might use the following to create a composite image containing
the above images with the following call:
(send TANGO:COMPOSITE_IMAGE_CLASS :new
:show tango_w #C(0.25 0.25)
TANGO:CIRCLE_IMAGE_CLASS
#C(0.25 0.25) 0.2 TANGO_COLOR_MAROON 1.0
TANGO:POLYGON_IMAGE_CLASS
#C(0.50 0.50) #C(0.10 0.10)#C(0.10 0.10) "red" 1.0
)
**** TANGO:COMPOSITE_IMAGE_CLASS method :STOREON
(send <composite_image> :STOREON)
==> returns list of form
(send TANGO:COMPOSITE_IMAGE_CLASS :new <visibility_kwd>
*TANGO_WIDGET*
#C(<location-x> <location-y>)
[class-specific-image-instance-creation-args...]
[class-specific-image-instance-creation-args...]
...)
See <<TANGO:COMPOSITE_IMAGE_CLASS method :NEW/:ISNEW ...>> for details
on the returned data.
Evaluating the results of this method will create a copy of the given
image at a later time. Printing the results of this method to a file
enables one to store a persistent copy of the given image to
disk. See also TANGO:WIDGET_CLASS method :GET_IMAGES and
:COLORS_STOREON.
**** TANGO:COMPOSITE_IMAGE_CLASS method :IMAGE_LOC (TANGOimage_loc()):
(send <composite_image> :IMAGE_LOC <image_part_kwd>)
==> returns a COMPLEX number #C(<x> <y>), where <x> and <y>
are FLONUMS representing the location of the image
<image_part_kwd> is a keyword argument, one of:
:CTR -- center
:NW -- north west
:NE -- north east
:E -- east
:SE -- south east
:S -- south
:SW -- south west
:W -- west
This routine returns a COMPLEX FLONUM #C(<x> <y>) that corresponds to
the location of the given <image_part_kwd> of the given <tiobj>.
Valid <image_part_kwd> include :CTR (center), and the compass
directions :NW, :N, :NE, :E, :SE, :S, :SW, :W. These
represent locations on the bounding box surrounding the set
of images contained in the TANGO:COMPOSITE_IMAGE_CLASS instance.
**** TANGO:COMPOSITE_IMAGE_CLASS method :TX_COLOR (TANGO_TRANS_TYPE_COLOR):
(send <composite_image> :TX_COLOR [:PERFORM] [<path>])
==> returns <tango_trans> object,
or NIL if :PERFORM keyword given.
The COLOR transition changes the given <composite_image> to the color
indicated by the given <path>. See the routine TANGO:PATH_COLOR to
create a special path which will change the image to a certain
color. Using an arbitrary TANGO_PATH type argument, or using one of
the other alternatives for the <path> argument list will generate
undefined results.
For composite images, method :TX_COLOR will apply :TX_COLOR
to all the subimages contained in the given composite image.
The optional :PERFORM keyword argument specifies that the transition
is to be performed immediately (see TANGO:TRANS_PERFORM). If :PERFORM
is omitted, then a <tango_trans> object is returned (useful for
storing- or operating-on- complex transitions via TANGO:TX_ITERATE,
TANGO:TX_CONCATENATE, TANGO:TX_COMPOSE.
**** TANGO:COMPOSITE_IMAGE_CLASS method :TX_FILL (TANGO_TRANS_TYPE_FILL):
(send <composite_image> :TX_FILL [:PERFORM] [<path>])
==> returns <tango_trans> object,
or NIL if :PERFORM keyword given.
This method alters the fill value of each subimage of <composite_image>
This will affect different subimage types differently:
For instances of TANGO:RECTANGLE_IMAGE_CLASS,
TANGO:CIRCLE_IMAGE_CLASS, TANGO:ELLIPSE_IMAGE_CLASS, and
TANGO:POLYGON_IMAGE_CLASS, this transition alters the image's fill
style value by the <x> value of the offsets in <path>. The <x> value
is simply added to the existing fill value of <composite_image>, the
<y> value is ignored. If the image's fill value goes below 0.0, it is
automatically set back to 0.0. If it goes above 1.0, it is set back
to 1.0. Actually, the full range of values between 0.0 and 1.0 is
not available. We currently implement 40 different fills that range
between the two extremes.
For instances of TANGO:LINE_IMAGE_CLASS, TANGO:POLYLINE_IMAGE_CLASS,
and TANGO:SPLINE_IMAGE_CLASS, the <x> value of each offset in <path>
is added to the line's <width> parameter value, and the <y> value is
added to the line's <style> parameter value (see the documentation
accompanying the :NEW method on the associated tango image classes
for further information on <width> and <style>). Extreme values are
reset to 0.0 and 1.0 as in rectangles and circles.
The optional :PERFORM keyword argument specifies that the transition
is to be performed immediately (see TANGO:TRANS_PERFORM). If :PERFORM
is omitted, then a <tango_trans> object is returned (useful for
storing- or operating-on- complex transitions via TANGO:TX_ITERATE,
TANGO:TX_CONCATENATE, TANGO:TX_COMPOSE.
The [<path>] argument is optional, and may be of multiple types:
* if the <path> argument is omitted, then a path of length one with
both x and y offsets set to 0.0 is used as the path for the
transition (see TANGOpath_null() in doc/xtangodoc.tex);
* else, if <path> is of type TANGO_PATH, then that is used as the path
for the transition to take. TANGO:PATH_CREATE, and other
TANGO:PATH_* functions return such TANGO_PATH typed results;
* else, if <path> is of type FIXNUM, then a path of length <path> with
both x and y offsets set to 0.0 is used as the path for the
transition (see TANGOpath_null() in doc/xtangodoc.tex);
* else, if <path> is of type COMPLEX (e.g. #C(<x> <y>), then a path of
length one is used with x and y offsets set to <x> and <y>.
* else, if <path> is a sequence (LIST or ARRAY) of COMPLEX #C(<x> <y>),
then a path of the same length as the sequence is created,
with the x and y offsets set to the corresponding <x> <y>.
Note: all <path> arg types other than TANGO_PATH are used here for
convenience in creating transitions over simple, unique
paths. "Simple cases" constitute paths which don't need to be be
re-used, or altered via calls to TANGO:PATH_* functions.
**** TANGO:COMPOSITE_IMAGE_CLASS method :TX_RESIZE (TANGO_TRANS_TYPE_RESIZE):
(send <composite_image> :TX_RESIZE [:PERFORM] [<path>])
==> returns <tango_trans> object,
or NIL if :PERFORM keyword given.
The RESIZE transition resizes the given <composite_image> along the
given <path>. For composite images, a resize transition will be passed
on to all the subimages of <composite_image>, each handling resize
differently:
* TANGO:LINE_IMAGE_CLASS instances can have positive or
negative sizes, they are resized by altering the line's
size for each offset in the path.
* TANGO:RECTANGLE_IMAGE_CLASS instances can have only
positive sizes, so resizing a rectangle corresponds to
"dragging" the lower right corner of the rectangle along
the given path. If one of the rectangle's dimensions would
become negative, it is set to 0.
* TANGO:CIRCLE_IMAGE_CLASS instances are resized by modifying
the circle's radius by the amount given in the <x>
component of each offset in the <path>. The <y> component
of <path> is ignored.
* TANGO:ELLIPSE_IMAGE_CLASS instances are resized by adding
the <x> part of <path> value to the ellipse's <x> radius
and the <y> part of <path> to the <y> radius.
* other subimage types ignore :TX_RESIZE...
The optional :PERFORM keyword argument specifies that the transition
is to be performed immediately (see TANGO:TRANS_PERFORM). If :PERFORM
is omitted, then a <tango_trans> object is returned (useful for
storing- or operating-on- complex transitions via TANGO:TX_ITERATE,
TANGO:TX_CONCATENATE, TANGO:TX_COMPOSE.
The [<path>] argument is optional, and may be of multiple types:
* if the <path> argument is omitted, then a path of length one with
both x and y offsets set to 0.0 is used as the path for the
transition (see TANGOpath_null() in doc/xtangodoc.tex);
* else, if <path> is of type TANGO_PATH, then that is used as the path
for the transition to take. TANGO:PATH_CREATE, and other
TANGO:PATH_* functions return such TANGO_PATH typed results;
* else, if <path> is of type FIXNUM, then a path of length <path> with
both x and y offsets set to 0.0 is used as the path for the
transition (see TANGOpath_null() in doc/xtangodoc.tex);
* else, if <path> is of type COMPLEX (e.g. #C(<x> <y>), then a path of
length one is used with x and y offsets set to <x> and <y>.
* else, if <path> is a sequence (LIST or ARRAY) of COMPLEX #C(<x> <y>),
then a path of the same length as the sequence is created,
with the x and y offsets set to the corresponding <x> <y>.
Note: all <path> arg types other than TANGO_PATH are used here for
convenience in creating transitions over simple, unique
paths. "Simple cases" constitute paths which don't need to be be
re-used, or altered via calls to TANGO:PATH_* functions.
**** TANGO:COMPOSITE_IMAGE_CLASS method :TX_RESIZE[1-7]:
(send <composite_image> :TX_RESIZE1 [:PERFORM] [<path>])
==> returns <tango_trans> object,
or NIL if :PERFORM keyword given.
.
.
.
(send <composite_image> :TX_RESIZE7 [:PERFORM] [<path>])
==> returns <tango_trans> object,
or NIL if :PERFORM keyword given.
For <composite_image>, the transitions :TX_RESIZE1-:TX_RESIZE7 are
passed on to any subimages that are instances of instance of class
TANGO:POLYLINE_IMAGE_CLASS, TANGO:POLYGON_IMAGE_CLASS, or
TANGO:SPLINE_IMAGE_CLASS. The transitions :TX_RESIZE1-:TX_RESIZE7
modify the relative positions of the respective vertex number, plus
all others after it in numerical order, by the relative <x> <y>
offsets of <path>. These transitions are useful, for example, with a
forward arrow polyline that has many of its edges compressed down to
start. They can subsequently be grown out in all different
directions, one at a time.
The optional :PERFORM keyword argument specifies that the transition
is to be performed immediately (see TANGO:TRANS_PERFORM). If :PERFORM
is omitted, then a <tango_trans> object is returned (useful for
storing- or operating-on- complex transitions via TANGO:TX_ITERATE,
TANGO:TX_CONCATENATE, TANGO:TX_COMPOSE.
The [<path>] argument is optional, and may be of multiple types:
* if the <path> argument is omitted, then a path of length one with
both x and y offsets set to 0.0 is used as the path for the
transition (see TANGOpath_null() in doc/xtangodoc.tex);
* else, if <path> is of type TANGO_PATH, then that is used as the path
for the transition to take. TANGO:PATH_CREATE, and other
TANGO:PATH_* functions return such TANGO_PATH typed results;
* else, if <path> is of type FIXNUM, then a path of length <path> with
both x and y offsets set to 0.0 is used as the path for the
transition (see TANGOpath_null() in doc/xtangodoc.tex);
* else, if <path> is of type COMPLEX (e.g. #C(<x> <y>), then a path of
length one is used with x and y offsets set to <x> and <y>.
* else, if <path> is a sequence (LIST or ARRAY) of COMPLEX #C(<x> <y>),
then a path of the same length as the sequence is created,
with the x and y offsets set to the corresponding <x> <y>.
Note: all <path> arg types other than TANGO_PATH are used here for
convenience in creating transitions over simple, unique
paths. "Simple cases" constitute paths which don't need to be be
re-used, or altered via calls to TANGO:PATH_* functions.
**** TANGO:COMPOSITE_IMAGE_CLASS method :TX_GRAB[1-7]:
(send <composite_image> :TX_GRAB1 [:PERFORM] [<path>])
==> returns <tango_trans> object,
or NIL if :PERFORM keyword given.
.
.
.
(send <composite_image> :TX_GRAB7 [:PERFORM] [<path>])
==> returns <tango_trans> object,
or NIL if :PERFORM keyword given.
For <composite_image>, the transitions :TX_GRAB1-:TX_GRAB7 are passed
on to any subimages that are instances of instance of class
TANGO:POLYLINE_IMAGE_CLASS, TANGO:POLYGON_IMAGE_CLASS, or
TANGO:SPLINE_IMAGE_CLASS. The transitions :TX_GRAB1-:TX_GRAB7 modify
the relative position of a particular vertex on the image (except the
one denoting the image's position) by the relative offsets of the
path. As opposed to :TX_RESIZE[1-7], the transitions :TX_GRAB[1-7]
alter only one particular vertex in the image's definition. Think of
grabbing that vertex and swinging it around while all the other
points stay anchored.
The optional :PERFORM keyword argument specifies that the transition
is to be performed immediately (see TANGO:TRANS_PERFORM). If :PERFORM
is omitted, then a <tango_trans> object is returned (useful for
storing- or operating-on- complex transitions via TANGO:TX_ITERATE,
TANGO:TX_CONCATENATE, TANGO:TX_COMPOSE.
The [<path>] argument is optional, and may be of multiple types:
* if the <path> argument is omitted, then a path of length one with
both x and y offsets set to 0.0 is used as the path for the
transition (see TANGOpath_null() in doc/xtangodoc.tex);
* else, if <path> is of type TANGO_PATH, then that is used as the path
for the transition to take. TANGO:PATH_CREATE, and other
TANGO:PATH_* functions return such TANGO_PATH typed results;
* else, if <path> is of type FIXNUM, then a path of length <path> with
both x and y offsets set to 0.0 is used as the path for the
transition (see TANGOpath_null() in doc/xtangodoc.tex);
* else, if <path> is of type COMPLEX (e.g. #C(<x> <y>), then a path of
length one is used with x and y offsets set to <x> and <y>.
* else, if <path> is a sequence (LIST or ARRAY) of COMPLEX #C(<x> <y>),
then a path of the same length as the sequence is created,
with the x and y offsets set to the corresponding <x> <y>.
Note: all <path> arg types other than TANGO_PATH are used here for
convenience in creating transitions over simple, unique
paths. "Simple cases" constitute paths which don't need to be be
re-used, or altered via calls to TANGO:PATH_* functions.
*** TANGO:ELLIPSE_IMAGE_CLASS (TANGO_IMAGE_TYPE_ELLIPSE):
**** TANGO:ELLIPSE_IMAGE_CLASS method :NEW/:ISNEW (TANGOimage_create()):
(send TANGO:ELLIPSE_IMAGE_CLASS :new
[:show] [<visible_kwd>] <tango_widget>
<location_coord>
<size_coord>
<tango_color>
<fill_float>
)
==> RETURNS an <tango_image> object.
[:show] -- OPTIONAL :show keyword. If present, displays image
immediately, else the image will be displayed along with the next
animation frame. See :TAP_SHOW :TX_DELAY.
[<visible_kwd>] -- OPTIONAL :VISIBLE or :INVISIBLE keyword. If
omitted, :VISIBLE is assumed. See also :TX_VISIBLE, :TAP_VIS_TOGGLE.
<tango_widget> -- an instance of TANGO:WIDGET_CLASS.
<location_coord> -- the location for placing the ellipse image. A
COMPLEX number, of form #C(<loc_x> <loc_y>), where <loc_x> is a
FLONUM, typically [0.0 - 1.0] representing the X-axis location;
<loc_y> is a FLONUM, typically [0.0 - 1.0] representing the Y-axis
location. See <<TANGO Locations and Coordinates (TANGO_LOC):>>
section above.
<size_coord> -- The size of the ellipse image, a COMPLEX number of
form #C(<size_x> <size_y>), where <size_x> is a FLONUM, typically
[0.0 - 1.0] representing the X-axis radius; <size_y> is a FLONUM,
typically [0.0 - 1.0] representing the Y-axis radius.
<tango_color> -- The color of the image; it can either be a string
color name, or a FIXNUM representing the tango pixel value. If given
a string, it is looked up in the X11 file /usr/lib/X11/rgb.txt. See
<<TANGO Colors (TANGO_COLOR):>> section above for details.
<fill_float> -- the fill value of the image, a FLONUM between 0.0 and
1.0. 0.0 corresponds to an unfilled outline and 1.0 corresponds to
100 per cent fill in the given color. (Forty graduated fill styles
are actually implemented.)
**** TANGO:ELLIPSE_IMAGE_CLASS method :STOREON
(send <ellipse-image> :STOREON)
==> returns list
(send TANGO:ELLIPSE_IMAGE_CLASS :new <visibility_kwd>
*TANGO_WIDGET*
#C(<location-x> <location-y)
#C(<radius-x> <radius-y>)
<tango_color>
<fill_float>)
See <<TANGO:ELLIPSE_IMAGE_CLASS method :NEW/:ISNEW...>>
for details on the returned data.
Evaluating the results of this method will create a copy of the given
image at a later time. Printing the results of this method to a file
enables one to store a persistent copy of the given image to
disk. See also TANGO:WIDGET_CLASS method :GET_IMAGES and
:COLORS_STOREON.
**** TANGO:ELLIPSE_IMAGE_CLASS method :IMAGE_LOC (TANGOimage_loc()):
(send <tiobj> :IMAGE_LOC <image_part_kwd>)
==> returns a COMPLEX number #C(<x> <y>), where <x> and <y>
are FLONUMS representing the location of the image
<image_part_kwd> is a keyword argument, one of:
:CTR -- center
:NW -- north west
:NE -- north east
:E -- east
:SE -- south east
:S -- south
:SW -- south west
:W -- west
This routine returns a COMPLEX FLONUM #C(<x> <y>) that corresponds to
the location of the given <image_part_kwd> of the given <tiobj>.
Valid <image_part_kwd> include :CTR (center), and the compass
directions :NW, :N, :NE, :E, :SE, :S, :SW, :W. These
represent locations on the bounding box of the ellipse.
**** TANGO:ELLIPSE_IMAGE_CLASS method :TX_COLOR (TANGO_TRANS_TYPE_COLOR):
(send <t-image-obj> :TX_COLOR [:PERFORM] [<path>])
==> returns <tango_trans> object,
or NIL if :PERFORM keyword given.
The COLOR transition changes the given <t-image-obj> to the color
indicated by the given <path>. See the routine TANGO:PATH_COLOR to
create a special path which will change the image to a certain
color. Using an arbitrary TANGO_PATH type argument, or using one of
the other alternatives for the <path> argument list (as used
in other :TX_* methods) will generate undefined results.
The optional :PERFORM keyword argument specifies that the transition
is to be performed immediately (see TANGO:TRANS_PERFORM). If :PERFORM
is omitted, then a <tango_trans> object is returned (useful for
storing- or operating-on- complex transitions via TANGO:TX_ITERATE,
TANGO:TX_CONCATENATE, TANGO:TX_COMPOSE.
**** TANGO:ELLIPSE_IMAGE_CLASS method :TX_FILL (TANGO_TRANS_TYPE_FILL):
(send <t-image-obj> :TX_FILL [:PERFORM] [<path>])
==> returns <tango_trans> object,
or NIL if :PERFORM keyword given.
The FILL transition changes the "fill" component of the given image
<t-image-obj>. This transition alters the image's fill style value by
the <x> value of the offsets in <path>. The <x> value is simply
added to the existing fill value of <t-image-obj>, the <y> value is
ignored. If the image's fill value goes below 0.0, it is
automatically set back to 0.0. If it goes above 1.0, it is set back
to 1.0. Actually, the full range of values between 0.0 and 1.0 is
not available. We currently implement 40 different fills that range
between the two extremes.
The optional :PERFORM keyword argument specifies that the transition
is to be performed immediately (see TANGO:TRANS_PERFORM). If :PERFORM
is omitted, then a <tango_trans> object is returned (useful for
storing- or operating-on- complex transitions via TANGO:TX_ITERATE,
TANGO:TX_CONCATENATE, TANGO:TX_COMPOSE.
The [<path>] argument is optional, and may be of multiple types:
* if the <path> argument is omitted, then a path of length one with
both x and y offsets set to 0.0 is used as the path for the
transition (see TANGOpath_null() in doc/xtangodoc.tex);
* else, if <path> is of type TANGO_PATH, then that is used as the path
for the transition to take. TANGO:PATH_CREATE, and other
TANGO:PATH_* functions return such TANGO_PATH typed results;
* else, if <path> is of type FIXNUM, then a path of length <path> with
both x and y offsets set to 0.0 is used as the path for the
transition (see TANGOpath_null() in doc/xtangodoc.tex);
* else, if <path> is of type COMPLEX (e.g. #C(<x> <y>), then a path of
length one is used with x and y offsets set to <x> and <y>.
* else, if <path> is a sequence (LIST or ARRAY) of COMPLEX #C(<x> <y>),
then a path of the same length as the sequence is created,
with the x and y offsets set to the corresponding <x> <y>.
Note: all <path> arg types other than TANGO_PATH are used here for
convenience in creating transitions over simple, unique
paths. "Simple cases" constitute paths which don't need to be be
re-used, or altered via calls to TANGO:PATH_* functions.
**** TANGO:ELLIPSE_IMAGE_CLASS method :TX_RESIZE (TANGO_TRANS_TYPE_RESIZE):
(send <t-image-obj> :TX_RESIZE [:PERFORM] [<path>])
==> returns <tango_trans> object,
or NIL if :PERFORM keyword given.
The RESIZE transition resizes the given <t-image-obj> along the given
<path>. TANGO:ELLIPSE_IMAGE_CLASS instances are resized by adding the
<x> part of <path> value to the ellipse's <x> radius and the <y> part
of <path> to the <y> radius.
The optional :PERFORM keyword argument specifies that the transition
is to be performed immediately (see TANGO:TRANS_PERFORM). If :PERFORM
is omitted, then a <tango_trans> object is returned (useful for
storing- or operating-on- complex transitions via TANGO:TX_ITERATE,
TANGO:TX_CONCATENATE, TANGO:TX_COMPOSE.
The [<path>] argument is optional, and may be of multiple types:
* if the <path> argument is omitted, then a path of length one with
both x and y offsets set to 0.0 is used as the path for the
transition (see TANGOpath_null() in doc/xtangodoc.tex);
* else, if <path> is of type TANGO_PATH, then that is used as the path
for the transition to take. TANGO:PATH_CREATE, and other
TANGO:PATH_* functions return such TANGO_PATH typed results;
* else, if <path> is of type FIXNUM, then a path of length <path> with
both x and y offsets set to 0.0 is used as the path for the
transition (see TANGOpath_null() in doc/xtangodoc.tex);
* else, if <path> is of type COMPLEX (e.g. #C(<x> <y>), then a path of
length one is used with x and y offsets set to <x> and <y>.
* else, if <path> is a sequence (LIST or ARRAY) of COMPLEX #C(<x> <y>),
then a path of the same length as the sequence is created,
with the x and y offsets set to the corresponding <x> <y>.
Note: all <path> arg types other than TANGO_PATH are used here for
convenience in creating transitions over simple, unique
paths. "Simple cases" constitute paths which don't need to be be
re-used, or altered via calls to TANGO:PATH_* functions.
*** TANGO:GIF_IMAGE_CLASS (TANGO_IMAGE_TYPE_PIXMAP):
**** TANGO:GIF_IMAGE_CLASS method :NEW/:ISNEW (TANGOimage_create()):
(send TANGO:GIF_IMAGE_CLASS :new
[:show] [<visible_kwd>] <tango_widget>
<location_coord>
<gif_file_name>
[:VERBOSE|:NOVERBOSE]
)
==> RETURNS an <tango_image> object.
[:show] -- OPTIONAL :show keyword. If present, displays image
immediately, else the image will be displayed along with the next
animation frame. See :TAP_SHOW :TX_DELAY.
[<visible_kwd>] -- OPTIONAL :VISIBLE or :INVISIBLE keyword. If
omitted, :VISIBLE is assumed. See also :TX_VISIBLE, :TAP_VIS_TOGGLE.
<tango_widget> -- an instance of TANGO:WIDGET_CLASS.
<location_coord> -- the location for placing the image. A
COMPLEX number, of form #C(<loc_x> <loc_y>), where <loc_x> is a
FLONUM, typically [0.0 - 1.0] representing the X-axis location;
<loc_y> is a FLONUM, typically [0.0 - 1.0] representing the Y-axis
location. See <<TANGO Locations and Coordinates (TANGO_LOC):>>
section above.
<gif_file_name> -- a STRING, the full path to the GIF file.
[:VERBOSE|:NOVERBOSE] -- optional keyword. If :NOVERBOSE or
no argument passed, information on the GIF is not printed.
If :VERBOSE argument passed, then information on the size of
the GIF, number of colors allocated exactly and number of colors
approximated, is printed to stdout.
Note: GIF colormaps are allocated exactly if your global colormap has
enough free colors. If not, then it attempts to substitute the
closest fit of colors from the global colormap. For the applications
the author has considered, it was decided not to allocate a private
colormap for GIF images so that exact colors could be achieved on an
8 bit system. This is because the GIF image is just one image among
many other tango images and Motif widgets that need to share a
colormap. For such situations, having the system colors go
"technicolor" in order to display GIF colors exactly was deemed
inappropriate... (Yes, there are solutions for this, but at the
current time, they are not portable across platforms).
Automatic memory/resource management note: colors allocated for a
particular GIF image are deallocated when the GIF image is
:TX_DELETE'd or when the TANGO:WIDGET_CLASS instance displaying the
GIF image gets destroyed. Likewise, the GIF data is also destroyed.
If you are running out of colors, you may find that you can reclaim
colors by explicitly destroying the image and forcing a garbage
collect. Likewise, if you are running out of client-side or
server-side memory, you will aslo want to destroy uneeded images.
Here's what you need to do:
(send <gif-image> :tx_delete :perform)
(gc)
**** TANGO:GIF_IMAGE_CLASS method :STOREON
TODO: This method still needs to be implemented! (Sorry...)
**** TANGO:GIF_IMAGE_CLASS method :IMAGE_LOC (TANGOimage_loc()):
(send <tiobj> :IMAGE_LOC <image_part_kwd>)
==> returns a COMPLEX number #C(<x> <y>), where <x> and <y>
are FLONUMS representing the location of the image
<image_part_kwd> is a keyword argument, one of:
:CTR -- center
:NW -- north west
:NE -- north east
:E -- east
:SE -- south east
:S -- south
:SW -- south west
:W -- west
This routine returns a COMPLEX FLONUM #C(<x> <y>) that corresponds to
the location of the given <image_part_kwd> of the given <tiobj>.
Valid <image_part_kwd> include :CTR (center), and the compass
directions :NW, :N, :NE, :E, :SE, :S, :SW, :W. Given that the
GIF is a rectangular image, the locations specified by
<image_part_kwd> represent the actual boundaries of the image.
*** TANGO:LINE_IMAGE_CLASS (TANGO_IMAGE_TYPE_LINE):
**** TANGO:LINE_IMAGE_CLASS method :NEW/:ISNEW (TANGOimage_create()):
(send TANGO:LINE_IMAGE_CLASS :new
[:show] [<visible_kwd>] <tango_widget>
<location_coord>
<size_coord>
<tango_color>
<line_width_float>
<line_style>
<arrow_kwd>)
==> RETURNS an <tango_image> object.
[:show] -- OPTIONAL :show keyword. If present, displays image
immediately, else the image will be displayed along with the next
animation frame. See :TAP_SHOW :TX_DELAY.
[<visible_kwd>] -- OPTIONAL :VISIBLE or :INVISIBLE keyword. If
omitted, :VISIBLE is assumed. See also :TX_VISIBLE, :TAP_VIS_TOGGLE.
<tango_widget> -- an instance of TANGO:WIDGET_CLASS.
<location_coord> -- the location for placing the image. A
COMPLEX number, of form #C(<loc_x> <loc_y>), where <loc_x> is a
FLONUM, typically [0.0 - 1.0] representing the X-axis location;
<loc_y> is a FLONUM, typically [0.0 - 1.0] representing the Y-axis
location. See <<TANGO Locations and Coordinates (TANGO_LOC):>>
section above.
<size_coord> -- a COMPLEX number of form #C(<size-x> #<size-y>)
where <size-x> represents the x-offset and <size-y> represents
the y-offset of line/arrow destination; the source being at
<location_coor>. Line sizes can be either positive or negative.
<tango_color> -- The color of the image; it can either be a string
color name, or a FIXNUM representing the tango pixel value. If given
a string, it is looked up in the X11 file /usr/lib/X11/rgb.txt. See
<<TANGO Colors (TANGO_COLOR):>> section above for details.
<line_width_float> -- defines the width of the line; it can range
from 0.0 to 1.0 (corresponding roughly to percentages). 0.0
corresponds to a thin line, and 1.0 corresponds to the thickest line.
Currently, we have implemented three thicknesses that are achieved by
values in the range 0.0 to 0.333, 0.333 to 0.667, and 0.667 to 1.0,
respectively.
<line_style> -- defines the line's style. It ranges from 0.0 to 1.0
also. We have implemented three styles: 0.0 to 0.333 defines a dotted
line, 0.333 to 0.667 defines a dashed line, and 0.667 to 1.0 defines a
solid line.
<arrow_kwd> -- one of the following keywords :NO_ARROW, :FORW_ARROW,
:BACK_ARROW, or :BOTH_ARROW .
**** TANGO:LINE_IMAGE_CLASS method :STOREON
(send <line-image> :STOREON)
==> returns list
(send TANGO:LINE_IMAGE_CLASS :new <visibility_kwd>
*TANGO_WIDGET*
#C(<location-x> <location-y)
#C(<size-x> <size-y>)
<tango_color>
<line_width_float>
<line_style>
<arrow-kwd>)
See <<TANGO:LINE_IMAGE_CLASS method :NEW/:ISNEW...>>
for details on the returned data.
Evaluating the results of this method will create a copy of the given
image at a later time. Printing the results of this method to a file
enables one to store a persistent copy of the given image to
disk. See also TANGO:WIDGET_CLASS method :GET_IMAGES and
:COLORS_STOREON.
**** TANGO:LINE_IMAGE_CLASS method :IMAGE_LOC (TANGOimage_loc()):
(send <tiobj> :IMAGE_LOC <image_part_kwd>)
==> returns a COMPLEX number #C(<x> <y>), where <x> and <y>
are FLONUMS representing the location of the image
<image_part_kwd> is a keyword argument, one of:
:CTR -- center
:NW -- north west
:NE -- north east
:E -- east
:SE -- south east
:S -- south
:SW -- south west
:W -- west
This routine returns a COMPLEX FLONUM #C(<x> <y>) that corresponds to
the location of the given <image_part_kwd> of the given <tiobj>.
Valid <image_part_kwd> include :CTR (center), and the compass
directions :NW, :N, :NE, :E, :SE, :S, :SW, :W. These
represent locations on the bounding box of the line.
**** TANGO:LINE_IMAGE_CLASS method :TX_COLOR (TANGO_TRANS_TYPE_COLOR):
(send <t-image-obj> :TX_COLOR [:PERFORM] [<path>])
==> returns <tango_trans> object,
or NIL if :PERFORM keyword given.
The COLOR transition changes the given <t-image-obj> to the color
indicated by the given <path>. See the routine TANGO:PATH_COLOR to
create a special path which will change the image to a certain
color. Using an arbitrary TANGO_PATH type argument, or using one of
the other alternatives for the <path> argument list (as used
in other :TX_* methods) will generate undefined results.
The optional :PERFORM keyword argument specifies that the transition
is to be performed immediately (see TANGO:TRANS_PERFORM). If :PERFORM
is omitted, then a <tango_trans> object is returned (useful for
storing- or operating-on- complex transitions via TANGO:TX_ITERATE,
TANGO:TX_CONCATENATE, TANGO:TX_COMPOSE.
**** TANGO:LINE_IMAGE_CLASS method :TX_FILL (TANGO_TRANS_TYPE_FILL):
(send <t-image-obj> :TX_FILL [:PERFORM] [<path>])
==> returns <tango_trans> object,
or NIL if :PERFORM keyword given.
The FILL transition changes the "fill" component of the given image
<t-image-obj>. For line images, this method takes the <x> value of each
offset in <path> and adds it to the line's <width> parameter value;
the <y> value is added to the line's <style> parameter value (see
<<TANGO:LINE_IMAGE_CLASS method :NEW (TANGOimage_create()):>> for
information on <line_width_float> and <line_style>. Extreme values
are reset to 0.0 and 1.0 as in rectangles and circles.
The optional :PERFORM keyword argument specifies that the transition
is to be performed immediately (see TANGO:TRANS_PERFORM). If :PERFORM
is omitted, then a <tango_trans> object is returned (useful for
storing- or operating-on- complex transitions via TANGO:TX_ITERATE,
TANGO:TX_CONCATENATE, TANGO:TX_COMPOSE.
The [<path>] argument is optional, and may be of multiple types:
* if the <path> argument is omitted, then a path of length one with
both x and y offsets set to 0.0 is used as the path for the
transition (see TANGOpath_null() in doc/xtangodoc.tex);
* else, if <path> is of type TANGO_PATH, then that is used as the path
for the transition to take. TANGO:PATH_CREATE, and other
TANGO:PATH_* functions return such TANGO_PATH typed results;
* else, if <path> is of type FIXNUM, then a path of length <path> with
both x and y offsets set to 0.0 is used as the path for the
transition (see TANGOpath_null() in doc/xtangodoc.tex);
* else, if <path> is of type COMPLEX (e.g. #C(<x> <y>), then a path of
length one is used with x and y offsets set to <x> and <y>.
* else, if <path> is a sequence (LIST or ARRAY) of COMPLEX #C(<x> <y>),
then a path of the same length as the sequence is created,
with the x and y offsets set to the corresponding <x> <y>.
Note: all <path> arg types other than TANGO_PATH are used here for
convenience in creating transitions over simple, unique
paths. "Simple cases" constitute paths which don't need to be be
re-used, or altered via calls to TANGO:PATH_* functions.
**** TANGO:LINE_IMAGE_CLASS method :TX_RESIZE (TANGO_TRANS_TYPE_RESIZE):
(send <t-image-obj> :TX_RESIZE [:PERFORM] [<path>])
==> returns <tango_trans> object,
or NIL if :PERFORM keyword given.
The RESIZE transition resizes the given <t-image-obj> along the given
<path>. For TANGO:LINE_IMAGE_CLASS instances the path elements can
have positive or negative sizes; Line images are resized by altering
the line's size for each offset in the path.
The optional :PERFORM keyword argument specifies that the transition
is to be performed immediately (see TANGO:TRANS_PERFORM). If :PERFORM
is omitted, then a <tango_trans> object is returned (useful for
storing- or operating-on- complex transitions via TANGO:TX_ITERATE,
TANGO:TX_CONCATENATE, TANGO:TX_COMPOSE.
The [<path>] argument is optional, and may be of multiple types:
* if the <path> argument is omitted, then a path of length one with
both x and y offsets set to 0.0 is used as the path for the
transition (see TANGOpath_null() in doc/xtangodoc.tex);
* else, if <path> is of type TANGO_PATH, then that is used as the path
for the transition to take. TANGO:PATH_CREATE, and other
TANGO:PATH_* functions return such TANGO_PATH typed results;
* else, if <path> is of type FIXNUM, then a path of length <path> with
both x and y offsets set to 0.0 is used as the path for the
transition (see TANGOpath_null() in doc/xtangodoc.tex);
* else, if <path> is of type COMPLEX (e.g. #C(<x> <y>), then a path of
length one is used with x and y offsets set to <x> and <y>.
* else, if <path> is a sequence (LIST or ARRAY) of COMPLEX #C(<x> <y>),
then a path of the same length as the sequence is created,
with the x and y offsets set to the corresponding <x> <y>.
Note: all <path> arg types other than TANGO_PATH are used here for
convenience in creating transitions over simple, unique
paths. "Simple cases" constitute paths which don't need to be be
re-used, or altered via calls to TANGO:PATH_* functions.
*** TANGO:POLYGON_IMAGE_CLASS (TANGO_IMAGE_TYPE_POLYGON):
**** TANGO:POLYGON_IMAGE_CLASS method :NEW/:ISNEW (TANGOimage_create()):
(send TANGO:POLYGON_IMAGE_CLASS :new
[:show] [<visible_kwd>] <tango_widget>
<location_coord>
<vertex-offset-coord-0>
[<vertex-offset-coord-1> [<vertex-offset-coord-2>
...
[<vertex-offset-coord-N>]]]
<tango_color>
<fill_float>)
==> RETURNS an <tango_image> object.
[:show] -- OPTIONAL :show keyword. If present, displays image
immediately, else the image will be displayed along with the next
animation frame. See :TAP_SHOW :TX_DELAY.
[<visible_kwd>] -- OPTIONAL :VISIBLE or :INVISIBLE keyword. If
omitted, :VISIBLE is assumed. See also :TX_VISIBLE, :TAP_VIS_TOGGLE.
<tango_widget> -- an instance of TANGO:WIDGET_CLASS.
<location_coord> -- the location for placing the image. A
COMPLEX number, of form #C(<loc_x> <loc_y>), where <loc_x> is a
FLONUM, typically [0.0 - 1.0] representing the X-axis location;
<loc_y> is a FLONUM, typically [0.0 - 1.0] representing the Y-axis
location. See <<TANGO Locations and Coordinates (TANGO_LOC):>>
section above.
<vertex-offset-coord-N> -- for i=0 to 6, this represents a COMPLEX
number of form #C(<offset-x> #<offset-y>) where <offset-x> represents
the x-offset and <offset-y> represents the y-offset of the polygon
vertex from its <location_coor>. These offsets can be either
positive or negative. Xtango polygon images support polygons with
eight or less sides. Therefore the sequence of offsets must be <= 7
elements -- the first vertex is implicity <0,0> and is not to be
included in the sequence.
<tango_color> -- The color of the image; it can either be a string
color name, or a FIXNUM representing the tango pixel value. If given
a string, it is looked up in the X11 file /usr/lib/X11/rgb.txt. See
<<TANGO Colors (TANGO_COLOR):>> section above for details.
<fill_float> -- the fill value of the image, a FLONUM between 0.0 and
1.0. 0.0 corresponds to an unfilled outline and 1.0 corresponds to
100 per cent fill in the given color. (Forty graduated fill styles
are actually implemented.)
**** TANGO:POLYGON_IMAGE_CLASS method :STOREON
(send <tango_polygon_image> :STOREON)
==> returns list
(send TANGO:POLYGON_IMAGE_CLASS :new <visibility_kwd>
*TANGO_WIDGET*
<location_coord>
<vertex-offset-coord-0>
[<vertex-offset-coord-1> [<vertex-offset-coord-2>
...
[<vertex-offset-coord-N>]]]
<tango_color>
<fill_float>)
See <<TANGO:POLYGON_IMAGE_CLASS method :NEW/:ISNEW...>>
for details on the returned data.
Evaluating the results of this method will create a copy of the given
image at a later time. Printing the results of this method to a file
enables one to store a persistent copy of the given image to
disk. See also TANGO:WIDGET_CLASS method :GET_IMAGES and
:COLORS_STOREON.
**** TANGO:POLYGON_IMAGE_CLASS method :IMAGE_LOC (TANGOimage_loc()):
(send <tango_polygon_image> :IMAGE_LOC <image_part>)
==> returns a COMPLEX number #C(<x> <y>), where <x> and
<y> are FLONUMS representing the location of the image.
<image_part> is either a KEYWORD SYMBOL or FIXNUM [0-7]
0 -- the "location", aka, the 0th vertex.
1 -- the 1st vertex
... ...
7 -- the 7th vertex
:CTR -- center
:NW -- north west
:NE -- north east
:E -- east
:SE -- south east
:S -- south
:SW -- south west
:W -- west
This routine returns a COMPLEX FLONUM #C(<x> <y>) that corresponds to
the location of the given <image_part> of the given
<tango_polygon_image>. Valid <image_part> include :CTR (center),
and the compass directions :NW, :N, :NE, :E, :SE, :S, :SW, :W. These
locations represent points on the bounding box of the polygon. If
<image_part> is a FIXNUM [0..7], then the location returned is the
actual location of the vertex, where vertex 0 is <location_coord> and
vertex 1 thru 7 represent the locations of the other vertices.
**** TANGO:POLYGON_IMAGE_CLASS method :TX_COLOR (TANGO_TRANS_TYPE_COLOR):
(send <t-image-obj> :TX_COLOR [:PERFORM] [<path>])
==> returns <tango_trans> object,
or NIL if :PERFORM keyword given.
The COLOR transition changes the given <t-image-obj> to the color
indicated by the given <path>. See the routine TANGO:PATH_COLOR to
create a special path which will change the image to a certain
color. Using an arbitrary TANGO_PATH type argument, or using one of
the other alternatives for the <path> argument list (as used
in other :TX_* methods) will generate undefined results.
The optional :PERFORM keyword argument specifies that the transition
is to be performed immediately (see TANGO:TRANS_PERFORM). If :PERFORM
is omitted, then a <tango_trans> object is returned (useful for
storing- or operating-on- complex transitions via TANGO:TX_ITERATE,
TANGO:TX_CONCATENATE, TANGO:TX_COMPOSE.
**** TANGO:POLYGON_IMAGE_CLASS method :TX_FILL (TANGO_TRANS_TYPE_FILL):
(send <t-image-obj> :TX_FILL [:PERFORM] [<path>])
==> returns <tango_trans> object,
or NIL if :PERFORM keyword given.
The FILL transition changes the "fill" component of the given image
<t-image-obj>. This transition alters the image's fill style value by
the <x> value of the offsets in <path>. The <x> value is simply
added to the existing fill value of <t-image-obj>, the <y> value is
ignored. If the image's fill value goes below 0.0, it is
automatically set back to 0.0. If it goes above 1.0, it is set back
to 1.0. Actually, the full range of values between 0.0 and 1.0 is
not available. We currently implement 40 different fills that range
between the two extremes.
The optional :PERFORM keyword argument specifies that the transition
is to be performed immediately (see TANGO:TRANS_PERFORM). If :PERFORM
is omitted, then a <tango_trans> object is returned (useful for
storing- or operating-on- complex transitions via TANGO:TX_ITERATE,
TANGO:TX_CONCATENATE, TANGO:TX_COMPOSE.
The [<path>] argument is optional, and may be of multiple types:
* if the <path> argument is omitted, then a path of length one with
both x and y offsets set to 0.0 is used as the path for the
transition (see TANGOpath_null() in doc/xtangodoc.tex);
* else, if <path> is of type TANGO_PATH, then that is used as the path
for the transition to take. TANGO:PATH_CREATE, and other
TANGO:PATH_* functions return such TANGO_PATH typed results;
* else, if <path> is of type FIXNUM, then a path of length <path> with
both x and y offsets set to 0.0 is used as the path for the
transition (see TANGOpath_null() in doc/xtangodoc.tex);
* else, if <path> is of type COMPLEX (e.g. #C(<x> <y>), then a path of
length one is used with x and y offsets set to <x> and <y>.
* else, if <path> is a sequence (LIST or ARRAY) of COMPLEX #C(<x> <y>),
then a path of the same length as the sequence is created,
with the x and y offsets set to the corresponding <x> <y>.
Note: all <path> arg types other than TANGO_PATH are used here for
convenience in creating transitions over simple, unique
paths. "Simple cases" constitute paths which don't need to be be
re-used, or altered via calls to TANGO:PATH_* functions.
**** TANGO:POLYGON_IMAGE_CLASS method :TX_RESIZE[1-7]:
(send <polygon_image> :TX_RESIZE1 [:PERFORM] [<path>])
==> returns <tango_trans> object,
or NIL if :PERFORM keyword given.
.
.
.
(send <polygon_image> :TX_RESIZE7 [:PERFORM] [<path>])
==> returns <tango_trans> object,
or NIL if :PERFORM keyword given.
The transitions :TX_RESIZE1-:TX_RESIZE7 modify the relative
positions of the respective vertex number, plus all others after it
in numerical order, by the relative <x> <y> offsets of <path>.
The optional :PERFORM keyword argument specifies that the transition
is to be performed immediately (see TANGO:TRANS_PERFORM). If :PERFORM
is omitted, then a <tango_trans> object is returned (useful for
storing- or operating-on- complex transitions via TANGO:TX_ITERATE,
TANGO:TX_CONCATENATE, TANGO:TX_COMPOSE.
The [<path>] argument is optional, and may be of multiple types:
* if the <path> argument is omitted, then a path of length one with
both x and y offsets set to 0.0 is used as the path for the
transition (see TANGOpath_null() in doc/xtangodoc.tex);
* else, if <path> is of type TANGO_PATH, then that is used as the path
for the transition to take. TANGO:PATH_CREATE, and other
TANGO:PATH_* functions return such TANGO_PATH typed results;
* else, if <path> is of type FIXNUM, then a path of length <path> with
both x and y offsets set to 0.0 is used as the path for the
transition (see TANGOpath_null() in doc/xtangodoc.tex);
* else, if <path> is of type COMPLEX (e.g. #C(<x> <y>), then a path of
length one is used with x and y offsets set to <x> and <y>.
* else, if <path> is a sequence (LIST or ARRAY) of COMPLEX #C(<x> <y>),
then a path of the same length as the sequence is created,
with the x and y offsets set to the corresponding <x> <y>.
Note: all <path> arg types other than TANGO_PATH are used here for
convenience in creating transitions over simple, unique
paths. "Simple cases" constitute paths which don't need to be be
re-used, or altered via calls to TANGO:PATH_* functions.
**** TANGO:POLYGON_IMAGE_CLASS method :TX_GRAB[1-7]:
(send <polygon_image> :TX_GRAB1 [:PERFORM] [<path>])
==> returns <tango_trans> object,
or NIL if :PERFORM keyword given.
.
.
.
(send <polygon_image> :TX_GRAB7 [:PERFORM] [<path>])
==> returns <tango_trans> object,
or NIL if :PERFORM keyword given.
The transitions :TX_GRAB1-:TX_GRAB7 modify the relative position of
a particular vertex on the image (except the one denoting the image's
position) by the relative offsets of the path. As opposed to
:TX_RESIZE[1-7], the transitions :TX_GRAB[1-7] alter only one
particular vertex in the image's definition. Think of grabbing that
vertex and swinging it around while all the other points stay anchored.
The optional :PERFORM keyword argument specifies that the transition
is to be performed immediately (see TANGO:TRANS_PERFORM). If :PERFORM
is omitted, then a <tango_trans> object is returned (useful for
storing- or operating-on- complex transitions via TANGO:TX_ITERATE,
TANGO:TX_CONCATENATE, TANGO:TX_COMPOSE.
The [<path>] argument is optional, and may be of multiple types:
* if the <path> argument is omitted, then a path of length one with
both x and y offsets set to 0.0 is used as the path for the
transition (see TANGOpath_null() in doc/xtangodoc.tex);
* else, if <path> is of type TANGO_PATH, then that is used as the path
for the transition to take. TANGO:PATH_CREATE, and other
TANGO:PATH_* functions return such TANGO_PATH typed results;
* else, if <path> is of type FIXNUM, then a path of length <path> with
both x and y offsets set to 0.0 is used as the path for the
transition (see TANGOpath_null() in doc/xtangodoc.tex);
* else, if <path> is of type COMPLEX (e.g. #C(<x> <y>), then a path of
length one is used with x and y offsets set to <x> and <y>.
* else, if <path> is a sequence (LIST or ARRAY) of COMPLEX #C(<x> <y>),
then a path of the same length as the sequence is created,
with the x and y offsets set to the corresponding <x> <y>.
Note: all <path> arg types other than TANGO_PATH are used here for
convenience in creating transitions over simple, unique
paths. "Simple cases" constitute paths which don't need to be be
re-used, or altered via calls to TANGO:PATH_* functions.
*** TANGO:POLYLINE_IMAGE_CLASS (TANGO_IMAGE_TYPE_POLYLINE):
**** TANGO:POLYLINE_IMAGE_CLASS method :NEW/:ISNEW (TANGOimage_create()):
(send TANGO:POLYLINE_IMAGE_CLASS :new
[:show] [<visible_kwd>] <tango_widget>
<location_coord>
<vertex-offset-coord-0>
[<vertex-offset-coord-1> [<vertex-offset-coord-2>
...
[<vertex-offset-coord-N>]]]
<tango_color>
<line_width_float>
<line_style>
<arrow_kwd>)
==> RETURNS an <tango_image> object.
[:show] -- OPTIONAL :show keyword. If present, displays image
immediately, else the image will be displayed along with the next
animation frame. See :TAP_SHOW :TX_DELAY.
[<visible_kwd>] -- OPTIONAL :VISIBLE or :INVISIBLE keyword. If
omitted, :VISIBLE is assumed. See also :TX_VISIBLE, :TAP_VIS_TOGGLE.
<tango_widget> -- an instance of TANGO:WIDGET_CLASS.
<location_coord> -- the location for placing the image. A
COMPLEX number, of form #C(<loc_x> <loc_y>), where <loc_x> is a
FLONUM, typically [0.0 - 1.0] representing the X-axis location;
<loc_y> is a FLONUM, typically [0.0 - 1.0] representing the Y-axis
location. See <<TANGO Locations and Coordinates (TANGO_LOC):>>
section above.
<vertex-offset-coord-N> -- for i=0 to 6, this represents a COMPLEX
number of form #C(<offset-x> #<offset-y>) where <offset-x> represents
the x-offset and <offset-y> represents the y-offset of the polyline
vertex from its <location_coor>. These offsets can be either
positive or negative. Xtango polyline images support polylines with
eight or less sides. Therefore the sequence of offsets must be <= 7
elements -- the first vertex is implicity <0,0> and is not to be
included in the sequence.
<tango_color> -- The color of the image; it can either be a string
color name, or a FIXNUM representing the tango pixel value. If given
a string, it is looked up in the X11 file /usr/lib/X11/rgb.txt. See
<<TANGO Colors (TANGO_COLOR):>> section above for details.
<line_width_float> -- defines the width of the polyline; it can range
from 0.0 to 1.0 (corresponding roughly to percentages). 0.0
corresponds to a thin line, and 1.0 corresponds to the thickest line.
Currently, we have implemented three thicknesses that are achieved by
values in the range 0.0 to 0.333, 0.333 to 0.667, and 0.667 to 1.0,
respectively.
<line_style> -- defines the line's style. It ranges from 0.0 to 1.0
also. We have implemented three styles: 0.0 to 0.333 defines a dotted
line, 0.333 to 0.667 defines a dashed line, and 0.667 to 1.0 defines a
solid line.
<arrow_kwd> -- one of the following keywords :NO_ARROW, :FORW_ARROW,
:BACK_ARROW, or :BOTH_ARROW .
**** TANGO:POLYLINE_IMAGE_CLASS method :STOREON
(send <tango_polyline_image> :STOREON)
==> returns list
(send TANGO:POLYLINE_IMAGE_CLASS :new <visibility_kwd>
*TANGO_WIDGET*
<location_coord>
<vertex-offset-coord-0>
[<vertex-offset-coord-1> [<vertex-offset-coord-2>
...
[<vertex-offset-coord-N>]]]
<tango_color>
<line_width_float>
<line_style>
<arrow_kwd>)
See <<TANGO:POLYLINE_IMAGE_CLASS method :NEW/:ISNEW...>>
for details on the returned data.
Evaluating the results of this method will create a copy of the given
image at a later time. Printing the results of this method to a file
enables one to store a persistent copy of the given image to
disk. See also TANGO:WIDGET_CLASS method :GET_IMAGES and
:COLORS_STOREON.
**** TANGO:POLYLINE_IMAGE_CLASS method :IMAGE_LOC (TANGOimage_loc()):
(send <tango_polyline_image> :IMAGE_LOC <image_part>)
==> returns a COMPLEX number #C(<x> <y>), where <x> and <y>
are FLONUMS representing the location of the image.
<image_part> is either a KEYWORD SYMBOL or FIXNUM [0-7]
0 -- the "location", aka, the 0th vertex.
1 -- the 1st vertex
... ...
7 -- the 7th vertex
:CTR -- center
:NW -- north west
:NE -- north east
:E -- east
:SE -- south east
:S -- south
:SW -- south west
:W -- west
This routine returns a COMPLEX FLONUM #C(<x> <y>) that corresponds to
the location of the given <image_part> of the given
<tango_polyline_image>. Valid <image_part> include :CTR (center),
and the compass directions :NW, :N, :NE, :E, :SE, :S, :SW, :W. These
locations represent points on the bounding box of the polyline. If
<image_part> is a FIXNUM [0..7], then the location returned is the
actual location of the vertex, where vertex 0 is <location_coord> and
vertex 1 thru 7 represent the locations of the other vertices.
**** TANGO:POLYLINE_IMAGE_CLASS method :TX_COLOR (TANGO_TRANS_TYPE_COLOR):
(send <t-image-obj> :TX_COLOR [:PERFORM] [<path>])
==> returns <tango_trans> object,
or NIL if :PERFORM keyword given.
The COLOR transition changes the given <t-image-obj> to the color
indicated by the given <path>. See the routine TANGO:PATH_COLOR to
create a special path which will change the image to a certain
color. Using an arbitrary TANGO_PATH type argument, or using one of
the other alternatives for the <path> argument list (as used
in other :TX_* methods) will generate undefined results.
The optional :PERFORM keyword argument specifies that the transition
is to be performed immediately (see TANGO:TRANS_PERFORM). If :PERFORM
is omitted, then a <tango_trans> object is returned (useful for
storing- or operating-on- complex transitions via TANGO:TX_ITERATE,
TANGO:TX_CONCATENATE, TANGO:TX_COMPOSE.
**** TANGO:POLYLINE_IMAGE_CLASS method :TX_FILL (TANGO_TRANS_TYPE_FILL):
(send <t-image-obj> :TX_FILL [:PERFORM] [<path>])
==> returns <tango_trans> object,
or NIL if :PERFORM keyword given.
The FILL transition changes the "fill" component of the given image
<t-image-obj>. For polyline images, this method takes the <x> value of
each offset in <path> and adds it to the polyline's <line_width_float>
parameter value; the <y> value is added to the polyline's <line_style>
parameter value (see
<<TANGO:POLYLINE_IMAGE_CLASS method :NEW (TANGOimage_create()):>>
for information on <line_width_float> and <line_style>. Extreme
values are reset to 0.0 and 1.0 as in rectangles and circles.
The optional :PERFORM keyword argument specifies that the transition
is to be performed immediately (see TANGO:TRANS_PERFORM). If :PERFORM
is omitted, then a <tango_trans> object is returned (useful for
storing- or operating-on- complex transitions via TANGO:TX_ITERATE,
TANGO:TX_CONCATENATE, TANGO:TX_COMPOSE.
The [<path>] argument is optional, and may be of multiple types:
* if the <path> argument is omitted, then a path of length one with
both x and y offsets set to 0.0 is used as the path for the
transition (see TANGOpath_null() in doc/xtangodoc.tex);
* else, if <path> is of type TANGO_PATH, then that is used as the path
for the transition to take. TANGO:PATH_CREATE, and other
TANGO:PATH_* functions return such TANGO_PATH typed results;
* else, if <path> is of type FIXNUM, then a path of length <path> with
both x and y offsets set to 0.0 is used as the path for the
transition (see TANGOpath_null() in doc/xtangodoc.tex);
* else, if <path> is of type COMPLEX (e.g. #C(<x> <y>), then a path of
length one is used with x and y offsets set to <x> and <y>.
* else, if <path> is a sequence (LIST or ARRAY) of COMPLEX #C(<x> <y>),
then a path of the same length as the sequence is created,
with the x and y offsets set to the corresponding <x> <y>.
Note: all <path> arg types other than TANGO_PATH are used here for
convenience in creating transitions over simple, unique
paths. "Simple cases" constitute paths which don't need to be be
re-used, or altered via calls to TANGO:PATH_* functions.
**** TANGO:POLYLINE_IMAGE_CLASS method :TX_RESIZE[1-7]:
(send <polyline_image> :TX_RESIZE1 [:PERFORM] [<path>])
==> returns <tango_trans> object,
or NIL if :PERFORM keyword given.
.
.
.
(send <polyline_image> :TX_RESIZE7 [:PERFORM] [<path>])
==> returns <tango_trans> object,
or NIL if :PERFORM keyword given.
The transitions :TX_RESIZE1-:TX_RESIZE7 modify the relative
positions of the respective vertex number, plus all others after it
in numerical order, by the relative <x> <y> offsets of <path>.
These transitions are useful, for example, with a forward arrow
polyline that has many of its edges compressed down to start.
They can subsequently be grown out in all different directions, one
at a time.
The optional :PERFORM keyword argument specifies that the transition
is to be performed immediately (see TANGO:TRANS_PERFORM). If :PERFORM
is omitted, then a <tango_trans> object is returned (useful for
storing- or operating-on- complex transitions via TANGO:TX_ITERATE,
TANGO:TX_CONCATENATE, TANGO:TX_COMPOSE.
The [<path>] argument is optional, and may be of multiple types:
* if the <path> argument is omitted, then a path of length one with
both x and y offsets set to 0.0 is used as the path for the
transition (see TANGOpath_null() in doc/xtangodoc.tex);
* else, if <path> is of type TANGO_PATH, then that is used as the path
for the transition to take. TANGO:PATH_CREATE, and other
TANGO:PATH_* functions return such TANGO_PATH typed results;
* else, if <path> is of type FIXNUM, then a path of length <path> with
both x and y offsets set to 0.0 is used as the path for the
transition (see TANGOpath_null() in doc/xtangodoc.tex);
* else, if <path> is of type COMPLEX (e.g. #C(<x> <y>), then a path of
length one is used with x and y offsets set to <x> and <y>.
* else, if <path> is a sequence (LIST or ARRAY) of COMPLEX #C(<x> <y>),
then a path of the same length as the sequence is created,
with the x and y offsets set to the corresponding <x> <y>.
Note: all <path> arg types other than TANGO_PATH are used here for
convenience in creating transitions over simple, unique
paths. "Simple cases" constitute paths which don't need to be be
re-used, or altered via calls to TANGO:PATH_* functions.
**** TANGO:POLYLINE_IMAGE_CLASS method :TX_GRAB[1-7]:
(send <polyline_image> :TX_GRAB1 [:PERFORM] [<path>])
==> returns <tango_trans> object,
or NIL if :PERFORM keyword given.
.
.
.
(send <polyline_image> :TX_GRAB7 [:PERFORM] [<path>])
==> returns <tango_trans> object,
or NIL if :PERFORM keyword given.
The transitions :TX_GRAB1-:TX_GRAB7 modify the relative position of
a particular vertex on the image (except the one denoting the image's
position) by the relative offsets of the path. As opposed to
:TX_RESIZE[1-7], the transitions :TX_GRAB[1-7] alter only one
particular vertex in the image's definition. Think of grabbing that
vertex and swinging it around while all the other points stay anchored.
The optional :PERFORM keyword argument specifies that the transition
is to be performed immediately (see TANGO:TRANS_PERFORM). If :PERFORM
is omitted, then a <tango_trans> object is returned (useful for
storing- or operating-on- complex transitions via TANGO:TX_ITERATE,
TANGO:TX_CONCATENATE, TANGO:TX_COMPOSE.
The [<path>] argument is optional, and may be of multiple types:
* if the <path> argument is omitted, then a path of length one with
both x and y offsets set to 0.0 is used as the path for the
transition (see TANGOpath_null() in doc/xtangodoc.tex);
* else, if <path> is of type TANGO_PATH, then that is used as the path
for the transition to take. TANGO:PATH_CREATE, and other
TANGO:PATH_* functions return such TANGO_PATH typed results;
* else, if <path> is of type FIXNUM, then a path of length <path> with
both x and y offsets set to 0.0 is used as the path for the
transition (see TANGOpath_null() in doc/xtangodoc.tex);
* else, if <path> is of type COMPLEX (e.g. #C(<x> <y>), then a path of
length one is used with x and y offsets set to <x> and <y>.
* else, if <path> is a sequence (LIST or ARRAY) of COMPLEX #C(<x> <y>),
then a path of the same length as the sequence is created,
with the x and y offsets set to the corresponding <x> <y>.
Note: all <path> arg types other than TANGO_PATH are used here for
convenience in creating transitions over simple, unique
paths. "Simple cases" constitute paths which don't need to be be
re-used, or altered via calls to TANGO:PATH_* functions.
*** TANGO:RECTANGLE_IMAGE_CLASS (TANGO_IMAGE_TYPE_RECTANGLE):
**** TANGO:RECTANGLE_IMAGE_CLASS method :NEW/:ISNEW (TANGOimage_create()):
(send TANGO:RECTANGLE_IMAGE_CLASS :new
[:show] [<visible_kwd>] <tango_widget>
<location_coord>
<size_coord>
<tango_color>
<fill_float>
)
==> RETURNS an <tango_image> object.
[:show] -- OPTIONAL :show keyword. If present, displays image
immediately, else the image will be displayed along with the next
animation frame. See :TAP_SHOW :TX_DELAY.
[<visible_kwd>] -- OPTIONAL :VISIBLE or :INVISIBLE keyword. If
omitted, :VISIBLE is assumed. See also :TX_VISIBLE, :TAP_VIS_TOGGLE.
<tango_widget> -- an instance of TANGO:WIDGET_CLASS.
<location_coord> -- the location for placing the rectangle
image, corresponds to the upper left corner. <location_coord> is
COMPLEX number, of form #C(<loc_x> <loc_y>), where <loc_x> is a
FLONUM, typically [0.0 - 1.0] representing the X-axis location;
<loc_y> is a FLONUM, typically [0.0 - 1.0] representing the Y-axis
location. See <<TANGO Locations and Coordinates (TANGO_LOC):>>
section above.
<size_coord> -- The size of the rectangle image, a COMPLEX number of
form #C(<size_x> <size_y>), where <size_x> is a FLONUM, typically
[0.0 - 1.0] representing the X-axis size; <size_y> is a FLONUM,
typically [0.0 - 1.0] representing the Y-axis size.
<tango_color> -- The color of the image; it can either be a string
color name, or a FIXNUM representing the tango pixel value. If given
a string, it is looked up in the X11 file /usr/lib/X11/rgb.txt. See
<<TANGO Colors (TANGO_COLOR):>> section above for details.
<fill_float> -- the fill value of the image, a FLONUM between 0.0 and
1.0. 0.0 corresponds to an unfilled outline and 1.0 corresponds to
100 per cent fill in the given color. (Forty graduated fill styles
are actually implemented.)
**** TANGO:RECTANGLE_IMAGE_CLASS method :STOREON
(send <rectangle-image> :STOREON)
==> returns list
(send TANGO:RECTANGLE_IMAGE_CLASS :new <visibility_kwd>
*TANGO_WIDGET*
#C(<location-x> <location-y)
#C(<size-x> <size-y>)
<tango_color>
<fill_float>)
See <<TANGO:RECTANGE_IMAGE_CLASS method :NEW/:ISNEW...>>
for details on the returned data.
Evaluating the results of this method will create a copy of the given
image at a later time. Printing the results of this method to a file
enables one to store a persistent copy of the given image to
disk. See also TANGO:WIDGET_CLASS method :GET_IMAGES and
:COLORS_STOREON.
**** TANGO:RECTANGLE_IMAGE_CLASS method :IMAGE_LOC (TANGOimage_loc()):
(send <tiobj> :IMAGE_LOC <image_part_kwd>)
==> returns a COMPLEX number #C(<x> <y>), where <x> and <y>
are FLONUMS representing the location of the image
<image_part_kwd> is a keyword argument, one of:
:CTR -- center
:NW -- north west
:NE -- north east
:E -- east
:SE -- south east
:S -- south
:SW -- south west
:W -- west
This routine returns a COMPLEX FLONUM #C(<x> <y>) that corresponds to
the location of the given <image_part_kwd> of the given <tiobj>.
Valid <image_part_kwd> include :CTR (center), and the compass
directions :NW, :N, :NE, :E, :SE, :S, :SW, :W. These
locations represent the actual boundaries of the rectangle.
**** TANGO:POLYLINE_IMAGE_CLASS method :TX_COLOR (TANGO_TRANS_TYPE_COLOR):
(send <t-image-obj> :TX_COLOR [:PERFORM] [<path>])
==> returns <tango_trans> object,
or NIL if :PERFORM keyword given.
The COLOR transition changes the given <t-image-obj> to the color
indicated by the given <path>. See the routine TANGO:PATH_COLOR to
create a special path which will change the image to a certain
color. Using an arbitrary TANGO_PATH type argument, or using one of
the other alternatives for the <path> argument list (as used
in other :TX_* methods) will generate undefined results.
The optional :PERFORM keyword argument specifies that the transition
is to be performed immediately (see TANGO:TRANS_PERFORM). If :PERFORM
is omitted, then a <tango_trans> object is returned (useful for
storing- or operating-on- complex transitions via TANGO:TX_ITERATE,
TANGO:TX_CONCATENATE, TANGO:TX_COMPOSE.
**** TANGO:RECTANGLE_IMAGE_CLASS method :TX_FILL (TANGO_TRANS_TYPE_FILL):
(send <t-image-obj> :TX_FILL [:PERFORM] [<path>])
==> returns <tango_trans> object,
or NIL if :PERFORM keyword given.
The FILL transition changes the "fill" component of the given image
<t-image-obj>. This transition alters the image's fill style value by
the <x> value of the offsets in <path>. The <x> value is simply
added to the existing fill value of <t-image-obj>, the <y> value is
ignored. If the image's fill value goes below 0.0, it is
automatically set back to 0.0. If it goes above 1.0, it is set back
to 1.0. Actually, the full range of values between 0.0 and 1.0 is
not available. We currently implement 40 different fills that range
between the two extremes.
The optional :PERFORM keyword argument specifies that the transition
is to be performed immediately (see TANGO:TRANS_PERFORM). If :PERFORM
is omitted, then a <tango_trans> object is returned (useful for
storing- or operating-on- complex transitions via TANGO:TX_ITERATE,
TANGO:TX_CONCATENATE, TANGO:TX_COMPOSE.
The [<path>] argument is optional, and may be of multiple types:
* if the <path> argument is omitted, then a path of length one with
both x and y offsets set to 0.0 is used as the path for the
transition (see TANGOpath_null() in doc/xtangodoc.tex);
* else, if <path> is of type TANGO_PATH, then that is used as the path
for the transition to take. TANGO:PATH_CREATE, and other
TANGO:PATH_* functions return such TANGO_PATH typed results;
* else, if <path> is of type FIXNUM, then a path of length <path> with
both x and y offsets set to 0.0 is used as the path for the
transition (see TANGOpath_null() in doc/xtangodoc.tex);
* else, if <path> is of type COMPLEX (e.g. #C(<x> <y>), then a path of
length one is used with x and y offsets set to <x> and <y>.
* else, if <path> is a sequence (LIST or ARRAY) of COMPLEX #C(<x> <y>),
then a path of the same length as the sequence is created,
with the x and y offsets set to the corresponding <x> <y>.
Note: all <path> arg types other than TANGO_PATH are used here for
convenience in creating transitions over simple, unique
paths. "Simple cases" constitute paths which don't need to be be
re-used, or altered via calls to TANGO:PATH_* functions.
**** TANGO:RECTANGLE_IMAGE_CLASS method :TX_RESIZE (TANGO_TRANS_TYPE_RESIZE):
(send <t-image-obj> :TX_RESIZE [:PERFORM] [<path>])
==> returns <tango_trans> object,
or NIL if :PERFORM keyword given.
The RESIZE transition resizes the given <t-image-obj> along the given
<path>. TANGO:RECTANGLE_IMAGE_CLASS instances are resized by adding the
<x> part of <path> value to the rectangle's <x> size and the <y> part
of <path> to the <y> size. Rectangles can have only positive sizes,
so resizing a rectangle corresponds to "dragging" the lower right
corner of the rectangle along the given path. If one of the rectangle's
dimensions would become negative, it is set to 0.
The optional :PERFORM keyword argument specifies that the transition
is to be performed immediately (see TANGO:TRANS_PERFORM). If :PERFORM
is omitted, then a <tango_trans> object is returned (useful for
storing- or operating-on- complex transitions via TANGO:TX_ITERATE,
TANGO:TX_CONCATENATE, TANGO:TX_COMPOSE.
The [<path>] argument is optional, and may be of multiple types:
* if the <path> argument is omitted, then a path of length one with
both x and y offsets set to 0.0 is used as the path for the
transition (see TANGOpath_null() in doc/xtangodoc.tex);
* else, if <path> is of type TANGO_PATH, then that is used as the path
for the transition to take. TANGO:PATH_CREATE, and other
TANGO:PATH_* functions return such TANGO_PATH typed results;
* else, if <path> is of type FIXNUM, then a path of length <path> with
both x and y offsets set to 0.0 is used as the path for the
transition (see TANGOpath_null() in doc/xtangodoc.tex);
* else, if <path> is of type COMPLEX (e.g. #C(<x> <y>), then a path of
length one is used with x and y offsets set to <x> and <y>.
* else, if <path> is a sequence (LIST or ARRAY) of COMPLEX #C(<x> <y>),
then a path of the same length as the sequence is created,
with the x and y offsets set to the corresponding <x> <y>.
Note: all <path> arg types other than TANGO_PATH are used here for
convenience in creating transitions over simple, unique
paths. "Simple cases" constitute paths which don't need to be be
re-used, or altered via calls to TANGO:PATH_* functions.
*** TANGO:SPLINE_IMAGE_CLASS (TANGO_IMAGE_TYPE_SPLINE):
**** TANGO:SPLINE_IMAGE_CLASS method :NEW/:ISNEW (TANGOimage_create()):
(send TANGO:SPLINE_IMAGE_CLASS :new
[:show] [<visible_kwd>] <tango_widget>
<location_coord>
<vertex-offset-coord-0>
[<vertex-offset-coord-1> [<vertex-offset-coord-2>
...
[<vertex-offset-coord-N>]]]
<tango_color>
<line_width_float>
<line_style>
)
==> RETURNS an <tango_image> object.
[:show] -- OPTIONAL :show keyword. If present, displays image
immediately, else the image will be displayed along with the next
animation frame. See :TAP_SHOW :TX_DELAY.
[<visible_kwd>] -- OPTIONAL :VISIBLE or :INVISIBLE keyword. If
omitted, :VISIBLE is assumed. See also :TX_VISIBLE, :TAP_VIS_TOGGLE.
<tango_widget> -- an instance of TANGO:WIDGET_CLASS.
<location_coord> -- the location for placing the image. A
COMPLEX number, of form #C(<loc_x> <loc_y>), where <loc_x> is a
FLONUM, typically [0.0 - 1.0] representing the X-axis location;
<loc_y> is a FLONUM, typically [0.0 - 1.0] representing the Y-axis
location. See <<TANGO Locations and Coordinates (TANGO_LOC):>>
section above.
<vertex-offset-coord-N> -- for i=0 to 6, this represents a COMPLEX
number of form #C(<offset-x> #<offset-y>) where <offset-x> represents
the x-offset and <offset-y> represents the y-offset of the spline
vertex from its <location_coor>. These offsets can be either
positive or negative. Xtango spline images support splines with
eight or less vertices. Therefore the sequence of offsets must be <= 7
elements -- the first vertex is implicity <0,0> and is not to be
included in the sequence.
<tango_color> -- The color of the image; it can either be a string
color name, or a FIXNUM representing the tango pixel value. If given
a string, it is looked up in the X11 file /usr/lib/X11/rgb.txt. See
<<TANGO Colors (TANGO_COLOR):>> section above for details.
<line_width_float> -- defines the width of the spline; it can range
from 0.0 to 1.0 (corresponding roughly to percentages). 0.0
corresponds to a thin line, and 1.0 corresponds to the thickest line.
Currently, we have implemented three thicknesses that are achieved by
values in the range 0.0 to 0.333, 0.333 to 0.667, and 0.667 to 1.0,
respectively.
<line_style> -- defines the line's style. It ranges from 0.0 to 1.0
also. We have implemented three styles: 0.0 to 0.333 defines a dotted
line, 0.333 to 0.667 defines a dashed line, and 0.667 to 1.0 defines a
solid line.
**** TANGO:SPLINE_IMAGE_CLASS method :STOREON
(send <tango_spline_image> :STOREON)
==> returns list
(send TANGO:SPLINE_IMAGE_CLASS :new <visibility_kwd>
*TANGO_WIDGET*
<location_coord>
<vertex-offset-coord-0>
[<vertex-offset-coord-1> [<vertex-offset-coord-2>
...
[<vertex-offset-coord-N>]]]
<tango_color>
<line_width_float>
<line_style>
)
See <<TANGO:SPLINE_IMAGE_CLASS method :NEW/:ISNEW...>>
for details on the returned data.
Evaluating the results of this method will create a copy of the given
image at a later time. Printing the results of this method to a file
enables one to store a persistent copy of the given image to
disk. See also TANGO:WIDGET_CLASS method :GET_IMAGES and
:COLORS_STOREON.
**** TANGO:SPLINE_IMAGE_CLASS method :IMAGE_LOC (TANGOimage_loc()):
(send <tango_spline_image> :IMAGE_LOC <image_part>)
==> returns a COMPLEX number #C(<x> <y>), where <x> and <y>
are FLONUMS representing the location of the image.
<image_part> is either a KEYWORD SYMBOL or FIXNUM [0-7]
0 -- the "location", aka, the 0th vertex.
1 -- the 1st vertex
... ...
7 -- the 7th vertex
:CTR -- center
:NW -- north west
:NE -- north east
:E -- east
:SE -- south east
:S -- south
:SW -- south west
:W -- west
This routine returns a COMPLEX FLONUM #C(<x> <y>) that corresponds to
the location of the given <image_part> of the given
<tango_spline_image>. Valid <image_part> include :CTR (center),
and the compass directions :NW, :N, :NE, :E, :SE, :S, :SW, :W. These
locations represent points on the bounding box of the spline. If
<image_part> is a FIXNUM [0..7], then the location returned is the
actual location of the vertex, where vertex 0 is <location_coord> and
vertex 1 thru 7 represent the locations of the other vertices.
**** TANGO:SPLINE_IMAGE_CLASS method :TX_COLOR (TANGO_TRANS_TYPE_COLOR):
(send <t-image-obj> :TX_COLOR [:PERFORM] [<path>])
==> returns <tango_trans> object,
or NIL if :PERFORM keyword given.
The COLOR transition changes the given <t-image-obj> to the color
indicated by the given <path>. See the routine TANGO:PATH_COLOR to
create a special path which will change the image to a certain
color. Using an arbitrary TANGO_PATH type argument, or using one of
the other alternatives for the <path> argument list (as used
in other :TX_* methods) will generate undefined results.
The optional :PERFORM keyword argument specifies that the transition
is to be performed immediately (see TANGO:TRANS_PERFORM). If :PERFORM
is omitted, then a <tango_trans> object is returned (useful for
storing- or operating-on- complex transitions via TANGO:TX_ITERATE,
TANGO:TX_CONCATENATE, TANGO:TX_COMPOSE.
**** TANGO:SPLINE_IMAGE_CLASS method :TX_FILL (TANGO_TRANS_TYPE_FILL):
(send <t-image-obj> :TX_FILL [:PERFORM] [<path>])
==> returns <tango_trans> object,
or NIL if :PERFORM keyword given.
The FILL transition changes the "fill" component of the given image
<t-image-obj>. For spline images, this method takes the <x> value of
each offset in <path> and adds it to the spline's <line_width_float>
parameter value; the <y> value is added to the spline's <line_style>
parameter value
(see <<TANGO:POLYLINE_IMAGE_CLASS method :NEW (TANGOimage_create()):>>
for information on <line_width_float> and <line_style>. Extreme
values are reset to 0.0 and 1.0 as in rectangles and circles.
The optional :PERFORM keyword argument specifies that the transition
is to be performed immediately (see TANGO:TRANS_PERFORM). If :PERFORM
is omitted, then a <tango_trans> object is returned (useful for
storing- or operating-on- complex transitions via TANGO:TX_ITERATE,
TANGO:TX_CONCATENATE, TANGO:TX_COMPOSE.
The [<path>] argument is optional, and may be of multiple types:
* if the <path> argument is omitted, then a path of length one with
both x and y offsets set to 0.0 is used as the path for the
transition (see TANGOpath_null() in doc/xtangodoc.tex);
* else, if <path> is of type TANGO_PATH, then that is used as the path
for the transition to take. TANGO:PATH_CREATE, and other
TANGO:PATH_* functions return such TANGO_PATH typed results;
* else, if <path> is of type FIXNUM, then a path of length <path> with
both x and y offsets set to 0.0 is used as the path for the
transition (see TANGOpath_null() in doc/xtangodoc.tex);
* else, if <path> is of type COMPLEX (e.g. #C(<x> <y>), then a path of
length one is used with x and y offsets set to <x> and <y>.
* else, if <path> is a sequence (LIST or ARRAY) of COMPLEX #C(<x> <y>),
then a path of the same length as the sequence is created,
with the x and y offsets set to the corresponding <x> <y>.
Note: all <path> arg types other than TANGO_PATH are used here for
convenience in creating transitions over simple, unique
paths. "Simple cases" constitute paths which don't need to be be
re-used, or altered via calls to TANGO:PATH_* functions.
**** TANGO:SPLINE_IMAGE_CLASS method :TX_RESIZE[1-7]:
(send <spline_image> :TX_RESIZE1 [:PERFORM] [<path>])
==> returns <tango_trans> object,
or NIL if :PERFORM keyword given.
.
.
.
(send <spline_image> :TX_RESIZE7 [:PERFORM] [<path>])
==> returns <tango_trans> object,
or NIL if :PERFORM keyword given.
The transitions :TX_RESIZE1-:TX_RESIZE7 modify the relative
positions of the respective vertex number, plus all others after it
in numerical order, by the relative <x> <y> offsets of <path>.
The optional :PERFORM keyword argument specifies that the transition
is to be performed immediately (see TANGO:TRANS_PERFORM). If :PERFORM
is omitted, then a <tango_trans> object is returned (useful for
storing- or operating-on- complex transitions via TANGO:TX_ITERATE,
TANGO:TX_CONCATENATE, TANGO:TX_COMPOSE.
The [<path>] argument is optional, and may be of multiple types:
* if the <path> argument is omitted, then a path of length one with
both x and y offsets set to 0.0 is used as the path for the
transition (see TANGOpath_null() in doc/xtangodoc.tex);
* else, if <path> is of type TANGO_PATH, then that is used as the path
for the transition to take. TANGO:PATH_CREATE, and other
TANGO:PATH_* functions return such TANGO_PATH typed results;
* else, if <path> is of type FIXNUM, then a path of length <path> with
both x and y offsets set to 0.0 is used as the path for the
transition (see TANGOpath_null() in doc/xtangodoc.tex);
* else, if <path> is of type COMPLEX (e.g. #C(<x> <y>), then a path of
length one is used with x and y offsets set to <x> and <y>.
* else, if <path> is a sequence (LIST or ARRAY) of COMPLEX #C(<x> <y>),
then a path of the same length as the sequence is created,
with the x and y offsets set to the corresponding <x> <y>.
Note: all <path> arg types other than TANGO_PATH are used here for
convenience in creating transitions over simple, unique
paths. "Simple cases" constitute paths which don't need to be be
re-used, or altered via calls to TANGO:PATH_* functions.
**** TANGO:SPLINE_IMAGE_CLASS method :TX_GRAB[1-7]:
(send <spline_image> :TX_GRAB1 [:PERFORM] [<path>])
==> returns <tango_trans> object,
or NIL if :PERFORM keyword given.
.
.
.
(send <spline_image> :TX_GRAB7 [:PERFORM] [<path>])
==> returns <tango_trans> object,
or NIL if :PERFORM keyword given.
The transitions :TX_GRAB1-:TX_GRAB7 modify the relative position of
a particular vertex on the image (except the one denoting the image's
position) by the relative offsets of the path. As opposed to
:TX_RESIZE[1-7], the transitions :TX_GRAB[1-7] alter only one
particular vertex in the image's definition. Think of grabbing that
vertex and swinging it around while all the other points stay anchored.
The optional :PERFORM keyword argument specifies that the transition
is to be performed immediately (see TANGO:TRANS_PERFORM). If :PERFORM
is omitted, then a <tango_trans> object is returned (useful for
storing- or operating-on- complex transitions via TANGO:TX_ITERATE,
TANGO:TX_CONCATENATE, TANGO:TX_COMPOSE.
The [<path>] argument is optional, and may be of multiple types:
* if the <path> argument is omitted, then a path of length one with
both x and y offsets set to 0.0 is used as the path for the
transition (see TANGOpath_null() in doc/xtangodoc.tex);
* else, if <path> is of type TANGO_PATH, then that is used as the path
for the transition to take. TANGO:PATH_CREATE, and other
TANGO:PATH_* functions return such TANGO_PATH typed results;
* else, if <path> is of type FIXNUM, then a path of length <path> with
both x and y offsets set to 0.0 is used as the path for the
transition (see TANGOpath_null() in doc/xtangodoc.tex);
* else, if <path> is of type COMPLEX (e.g. #C(<x> <y>), then a path of
length one is used with x and y offsets set to <x> and <y>.
* else, if <path> is a sequence (LIST or ARRAY) of COMPLEX #C(<x> <y>),
then a path of the same length as the sequence is created,
with the x and y offsets set to the corresponding <x> <y>.
Note: all <path> arg types other than TANGO_PATH are used here for
convenience in creating transitions over simple, unique
paths. "Simple cases" constitute paths which don't need to be be
re-used, or altered via calls to TANGO:PATH_* functions.
*** TANGO:TEXT_IMAGE_CLASS (TANGO_IMAGE_TYPE_TEXT):
**** TANGO:TEXT_IMAGE_CLASS method :NEW/:ISNEW (TANGOimage_create()):
(send TANGO:TEXT_IMAGE_CLASS :new
[:show] [<visible_kwd>] <tango_widget>
<location_coord> [:CTR]
<text_str>
<tango_color>
<font_str>
)
==> RETURNS an <tango_image> object.
[:show] -- OPTIONAL :show keyword. If present, displays image
immediately, else the image will be displayed along with the next
animation frame. See :TAP_SHOW :TX_DELAY.
[<visible_kwd>] -- OPTIONAL :VISIBLE or :INVISIBLE keyword. If
omitted, :VISIBLE is assumed. See also :TX_VISIBLE, :TAP_VIS_TOGGLE.
<tango_widget> -- an instance of TANGO:WIDGET_CLASS
<location_coord> -- the location for placing the text image. A
COMPLEX number, of form #C(<loc_x> <loc_y>), where
<loc_x> is a FLONUM, typically [0.0 - 1.0] representing the X-axis
location; <loc_y> is a FLONUM, typically [0.0 - 1.0] representing the
Y-axis location. See <<TANGO Locations and Coordinates (TANGO_LOC):>>
section above.
[:CTR] -- an optional KEYWORD. If this keyword is supplied,
then <location_coord> above refers to the center of the text image.
If :CTR keyword not supplied, then <location_coord> refers
to the lower left corner of the text image.
<text_string> is the text to be displayed by the the tango image.
Special characters such as tab, newline, carriage-return, etc
are rendered by the associated character specified by <font_string>
rather than tabbing, or starting a new line of text. See
"note" below for hints on creating multiline text.
<tango_color> -- The color of the image; it can either be a string
color name, or a FIXNUM representing the tango pixel value. If given
a string, it is looked up in the X11 file /usr/lib/X11/rgb.txt. See
<<TANGO Colors (TANGO_COLOR):>> section above for details.
<font_string> a STRING representing the font used for drawing.
If the value of <font_string> is NIL, then Xtango's default
font is used.
NOTE: to display multi-line text, one might consider using function
below to render the multiline text string <str> via multiple
text images stored as a composite image containing multiple
single-line text images. (Probably makes more sense to create
a new class TANGO:MULTILINE_TEXT_IMAGE_CLASS, feel free to
use the code below as a starting point...):
(require "xtango/cls-image")
(require "xtango/cls-widget")
;; for each line of text, create a TANGO:TEXT_IMAGE_CLASS
;; if multiple lines of text, group all the images
;; into one composite image
(defun create-multiline-text-image (str location_coord
tango_color font_string)
(let (pos
(imgs '())
)
(loop
(setq pos (search "\n" str))
(setq imgs
(cons
(send TANGO:TEXT_IMAGE_CLASS :new :show tango_w
location_coord
(subseq str 0 pos) ;text_string
tango_color
font_string
)
imgs))
(if (null pos) (return))
(setq str
(subseq str (1+ pos) nil))
(setq coords
(+ coords (- (send (car imgs) :IMAGE_LOC :s)
(send (car imgs) :IMAGE_LOC :n))))
)
(if (> (length imgs) 1)
(progn ;group multiline text into one object
(send tango_w :set-multi-selected-images imgs)
(send tango_w :group-selected-images)
)
(send tango_w :set-selected-image (car imgs)))
)
)
**** TANGO:TEXT_IMAGE_CLASS method :STOREON
(send <text-image> :STOREON)
==> returns list
(send TANGO:TEXT_IMAGE_CLASS :new <visibility_kwd>
*TANGO_WIDGET*
#C(<location-x> <location-y) [:ctr]
<text_str>
<tango_color>
<font_str>)
See <<TANGO:TEXT_IMAGE_CLASS method :NEW/:ISNEW...>>
for details on the returned data.
Evaluating the results of this method will create a copy of the given
image at a later time. Printing the results of this method to a file
enables one to store a persistent copy of the given image to
disk. See also TANGO:WIDGET_CLASS method :GET_IMAGES and
:COLORS_STOREON.
**** TANGO:TEXT_IMAGE_CLASS method :IMAGE_LOC (TANGOimage_loc()):
(send <tiobj> :IMAGE_LOC <image_part_kwd>)
==> returns a COMPLEX number #C(<x> <y>), where <x> and <y>
are FLONUMS representing the location of the image
<image_part_kwd> is a keyword argument, one of:
:CTR -- center
:NW -- north west
:NE -- north east
:E -- east
:SE -- south east
:S -- south
:SW -- south west
:W -- west
This routine returns a COMPLEX FLONUM #C(<x> <y>) that corresponds to
the location of the given <image_part_kwd> of the given <tiobj>.
Valid <image_part_kwd> include :CTR (center), and the compass
directions :NW, :N, :NE, :E, :SE, :S, :SW, :W. These
represent locations on the bounding box of the text.
**** TANGO:TEXT_IMAGE_CLASS method :TX_COLOR (TANGO_TRANS_TYPE_COLOR):
(send <t-image-obj> :TX_COLOR [:PERFORM] [<path>])
==> returns <tango_trans> object,
or NIL if :PERFORM keyword given.
The COLOR transition changes the given <t-image-obj> to the color
indicated by the given <path>. See the routine TANGO:PATH_COLOR to
create a special path which will change the image to a certain
color. Using an arbitrary TANGO_PATH type argument, or using one of
the other alternatives for the <path> argument list (as used
in other :TX_* methods) will generate undefined results.
The optional :PERFORM keyword argument specifies that the transition
is to be performed immediately (see TANGO:TRANS_PERFORM). If :PERFORM
is omitted, then a <tango_trans> object is returned (useful for
storing- or operating-on- complex transitions via TANGO:TX_ITERATE,
TANGO:TX_CONCATENATE, TANGO:TX_COMPOSE.
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
= Niels Mayer ..... mayer@eit.com .... http://www.eit.com/people/mayer.html =
= Multimedia Engineering Collaboration Environment (MM authoring for WWW) =
= Enterprise Integration Technologies, 459 Hamilton Ave, Palo Alto CA 94301 =
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=