Contents

This section is a copy of [1] , which is available at:
http://www.cc.gatech.edu/gvu/softviz/parviz/polkastuff/polkadoc-lite.ps.
The POLKA document is copyrighted by John T. Stasko, College of Computing, Georgia Institute of Technology, Atlanta, GA 30332-0280, and is available for noncommercial use.

Entry Points

Action::Action()

This constructor creates an Action with type = 0 and no offsets.
 
 
 

Action::Action (const char *t)

This constructor creates an Action with a type, but no offsets.
 
 
 

Action::Action(const char *t, int len, double dx[], double dy[])

This constructor creates an Action that has length len, designated by the given sequence of dx and dy offset pairs.
 
 
 

Action::Action(const char *t, int i)

This function creates an action with null offsets. When the function is given an integer greater than zero, it creates an Action with that number of null offsets, i.e., each dx and dy equal to 0.0.
 
 
 

Action::Action(const char *t, MOTION m)

This function creates an action with a path in one of three basic types (motions), designated by the constants STRAIGHT, CLOCKWISE, and COUNTERCLOCKWISE, then it creates a special set of offsets. STRAIGHT moves right; CLOCKWISE moves clockwise right in an upward arc; COUNTERCLOCKWISE moves counterclockwise left in an upward arc. Each of the 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. These Actions 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 modification routines.
 
 
 

Action::Action (const char *t, const char *arg)

This routine should be used to either change the color of an AnimObject or to change the string in a text AnimObject. It should be called with a first parameter of either ``COLOR'' or ``ALTER'', respectively. In the color case, it returns a one offset Action that will change an object to the color given as the arg parameter (an X11 valid color string). This will only work if the string $t$ is ``COLOR.'' In the alter case, the text string for the AnimObject will be changed to whatever string is in arg.
 
 
 

Action::Action (const char *t, Loc *from, Loc *to, int steps)

This routine returns an Action that proceeds in a straight line from the given from Loc* to the given to Loc* with the condition that the path will have the given number ( steps) of equally spaced offsets.

Note that in this routine and the two following, the provided from and to locations need not have absolute screen coordinate meaning. Because an Action 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 Action will be created using from = $\langle$0.2,0.2$\rangle$ and to =$\langle$0.4,0.4$\rangle$ as using from = $\langle$0.7,0.7$\rangle$ and to = $\langle$0.9,0.9$\rangle$. Most often however, the provided locations will be specific window coordinates chosen to move a certain image to a specific location. Typically, you want $t$ to be ``MOVE'' in these three routines.
 
 
 

Action::Action (const char *t, Loc *from, Loc *to, MOTION m)

This routine returns a path with movement characteristics of the given type m, but that also begins at the location with logical x and y coordinates of from and proceeds to the location with logical x and y coordinates of the to.

The created path will contain 20 offsets and will be modelled to fit the given path type, which may be one of STRAIGHT, CLOCKWISE, or COUNTERCLOCKWISE. The straight option creates a path that is a direct line from from to to with equally spaced offsets. The two clock motions will create a path that curves in the given clock motion direction.
 
 
 

Action::Action (const char *t, Loc *from, Loc *to, double distance)

This routine returns an Action 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 and to, the path is only given one offset. This routine is useful to create Actions that will make AnimObjects move at the same velocity.
 
 
 

int
Action::Length ()

This routine returns the numbers of offsets in the invoked Action.
 
 
 

double
Action::Deltax () 

double
Action::Deltay ()

These routines return the x or y distance, respectively, that the invoked Action traverses from start to finish.
 
 
 

Action *
Action::Copy ()

This routine returns a new Action that has an exact duplicate list of offsets and same type as the invoked Action.
 
 
 

Action *
Action::ChangeType (const char *new)

This routine returns a new Action that has an exact duplicate list of offsets as the invoked upon Action, but that has a new type, defined by the string new.
 
 
 

Action *
Action::Reverse ()

This routine returns an Action that is the inverse of the invoked Action. Being an inverse Action means that the order of offsets is reversed, and each offset points in the exact opposite direction. This routine provides a way for an object to retrace its tracks from a movement Action.
 
 
 

Action *
Action::Smooth ()

This routine returns an Action of the same type as the given one, but that has a ``smoother'' path component. Essentially, each new path offset value is determined by averaging in the neighboring offsets' values. Currently, we use twice the designated offset plus the previous and subsequent offsets, divided by four.
 
 
 

Action *
Action::Rotate (int deg)

This routine returns an Action that corresponds to the rotation of the invoked Action in a counter-clockwise motion. The number of degrees to rotate is provided by the integer parameter deg which should be between 0 and 360.
 
 
 

Action *
Action::Scale (double dx, double dy)

This routine returns an Action in which each offset is scaled by the given factors in x and y. That is, each offset's x and y values are multiplied by the dx and dy factors, respectively. So, for example, to return a movement Action that would be the reflection of an Action across an imaginary vertical line, choose x = -1.0 and y = 1.0.
 
 
 

Action *
Action::Extend (double dx, double dy)

This routine returns an Action in which each offset is extended by the given factors in x and y. That is, each offsets' x and y values have the dx and dy factors added to them, respectively.
 
 
 

Action *
Action::Interpolate (double factor)

This routine returns an Action in which the number of offsets is modified by a factor given by the factor parameter. If an Action with length 10 is interpolated with a factor of 2.0, the returned Action will have 20 offsets. If the factor is 0.3, the Action 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.
 
 
 

Action *
Action::Example (Loc *fromloc, Loc *toloc)

This routine returns an Action which "looks like" the invoked example Action, but which would move from the logical fromloc to the logical toloc. The created Action will have the same number of offsets as the invoked upon Action. The general flow of movement in the example Action is followed as closely as possible by maintaining the same ratios between control points in both Actions. Clearly, however, if the two Actions move in opposite directions, they will not look much alike. Typically, this routine will be used when one wants an AnimObject to end up in some specific position, with the AnimObject following some rough, given trajectory (from another Action) in order to get there.
 
 
 

Action *
Action::Iterate (int times)

This routine returns an Action which is an iteration of a given Action, one occurrence after another. The times parameter provides how many times the invoked Action should be repeated in the Action to be created.
 
 
 

Action *
Action::Concatenate (Action *a)

This routine creates an Action which is the concatenation of the given Action after the Action upon which invocation occurs. The first offset of an Action is relative to the last offset of the previous Action. The new Action retains the type of the referenced Action.
 
 
 

Action *
Action::Compose (Action *a)

This routine returns an Action which is the composition of the Action parameter $a$ and the invoked upon Action. By composition, we mean a cumulative combination on an offset by offset basis. If a Action is thought of as a vector, the composition of Actions produces a new vector that has the same length as the originals and is like the vector sum of the original Action vectors. Only Actions with an equal number of offsets can be composed. Otherwise, the routine returns NULL.

Essentially, Action composition takes all the first relative$\langle$ x, y$\rangle$ offsets and adds them together to make a new cumulative first $\langle$ x, y$\rangle$ offset. This is done for each offset in the Actions.

2002-11-11