Class Animation2D

All Implemented Interfaces:
ISWriterOps.AnimationParameters, GraphCreator, ObjectNamerOps<SimObject>

public class Animation2D extends Simulation implements ISWriterOps.AnimationParameters, GraphCreator
Class for scheduling the sequence of events for a 2D animation. Nearly all the methods are inherited from the Simulation class. Simulation time is represented in integral units called 'ticks', implemented as long integers. The constructors set the number of ticks per animation frame and the number of ticks per second. With this choice of units,the method currentTicks() provides the time in ticks whereas the method currentTime() provides the time in seconds (i.e., dividing the number of ticks per second by the number of ticks per frame provides the frame rate in units of frames per second).

Users should first create an instance of this class and call the method initFrames(int,String,String) (or initFrames(int,String,ISWriterOps). Various subclasses of AnimationObject2D will have to be created as well, and simulation events will have to be scheduled. The method scheduleFrames will schedule events needed to create a sequence of frames, and may be called multiple times as long as the sequences of frames specified do not overlap and are in the order in which they will appear. To produce the simulation, the method run can be used, with additional arguments if the animation generates a non-terminating sequence of events.

Some of the constructors allow the use of a parent simulation or scripting context. Because a simulation and its parent (if the parent is a simulation) share the same event queue and the look-up methods allow a simulation to find objects in a parent simulation, it is relatively easy to add an animation to an existing simulation, whether to create a visual representation of a simulation or to simply create a graph that varies with time. One add can multiple, independent animations to the same simulation if desired.

The method setImageType(Graph.ImageType) can be used to change the image type of the animation's graph's buffered image. The default should be changed if the animation is to have a transparent background: some formats (e.g., JPEG) do not work when the graph's image type includes an alpha channel. Similarly, the method requestAlpha(boolean) can be used to configure graphs that use an instance of ISWriterOps. While not applicable to the file-based class ImageSequenceWriter, it is appropriate for instances of ISWriterOps associated with graphics displays.

See Also:
  • Constructor Details

    • Animation2D

      public Animation2D()
      Constructor.
    • Animation2D

      public Animation2D(double ticksPerSecond, long ticksPerFrame)
      Constructor given frame-rate data.
      Parameters:
      ticksPerSecond - the number of animation time units per second
      ticksPerFrame - the number of animation time units per frame
    • Animation2D

      public Animation2D(int width, int height)
      Constructor given a width and height of the animation.
      Parameters:
      width - the width of the image in pixels
      height - the height of the image in pixels
    • Animation2D

      public Animation2D(int width, int height, double ticksPerSecond, long ticksPerFrame)
      Constructor given a width and height of the animation, and frame-rate data.
      Parameters:
      width - the width of the image in pixels
      height - the height of the image in pixels
      ticksPerSecond - the number of animation time units per second
      ticksPerFrame - the number of animation time units per frame
    • Animation2D

      public Animation2D(ScriptingContext parent)
      Constructor with a parent simulation or scripting context. When an animation has a parent, the parent's scripting context is used, unless specific methods are overridden. When an animation has a parent that is an instance of Simulation, the parent's event queue is used instead of the simulation's event queue and time structures. This allows multiple simulations, perhaps with different flavors, to be combined into a single simulation. While the event queue and simulation time are shared, tables of simulation objects are not. Running any of the simulations sharing a parent will run all of them. Default values are used for the image height and width and for the frame-rate data
      Parameters:
      parent - the simulation's parent
    • Animation2D

      public Animation2D(ScriptingContext parent, double ticksPerSecond, long ticksPerFrame)
      Constructor with parent simulation and frame-rate data. When an animation has a parent, the parent's scripting context is used, unless specific methods are overridden. When an animation has a parent that is an instance of Simulation, the parent's event queue is used instead of the simulation's event queue and time structures. This allows multiple simulations, perhaps with different flavors, to be combined into a single simulation. While the event queue and simulation time are shared, tables of simulation objects are not. Running any of the simulations sharing a parent will run all of them.
      Parameters:
      parent - the simulation's parent
      ticksPerSecond - the number of animation time units per second
      ticksPerFrame - the number of animation time units per frame
    • Animation2D

      public Animation2D(ScriptingContext parent, int width, int height)
      Constructor with parent simulation and an image height and width. When an animation has a parent, the parent's scripting context is used, unless specific methods are overridden. When an animation has a parent that is an instance of Simulation, the parent's event queue is used instead of the simulation's event queue and time structures. This allows multiple simulations, perhaps with different flavors, to be combined into a single simulation. While the event queue and simulation time are shared, tables of simulation objects are not. Running any of the simulations sharing a parent will run all of them. Default values are used for the image height and width and for the frame-rate data
      Parameters:
      parent - the simulation's parent
      width - the width of the image in pixels
      height - the height of the image in pixels
    • Animation2D

      public Animation2D(ScriptingContext parent, int width, int height, double ticksPerSecond, long ticksPerFrame)
      Constructor with parent simulation and image and frame-rate data. When an animation has a parent, the parent's scripting context is used, unless specific methods are overridden. When an animation has a parent that is an instance of Simulation, the parent's event queue is used instead of the simulation's event queue and time structures. This allows multiple simulations, perhaps with different flavors, to be combined into a single simulation. While the event queue and simulation time are shared, tables of simulation objects are not. Running any of the simulations sharing a parent will run all of them.
      Parameters:
      parent - the simulation's parent
      width - the width of the image in pixels
      height - the height of the image in pixels
      ticksPerSecond - the number of animation time units per second
      ticksPerFrame - the number of animation time units per frame
  • Method Details

    • nullPath

      public AnimationPath2D nullPath()
      Return the null path for this animation. A null path is used by some of the factories to indicate that a path should be set to null, indicating that an existing function should be removed. This is used in factories that support timelines.
      Returns:
      a null path.
    • nullFunction

      public SimFunction nullFunction()
      Return the null SimFunction for this animation. A null SimFunction is used by some of the factories to indicate that a function should be set to null, indicating that an existing function should be removed. This is used in factories that support timelines.

      A null SimFunction is a SimFunction for which SimFunction.getFunction() will return null, as opposed to a variable of type SimFunction whose value is null.

      Returns:
      a null SimFunction.
    • getTicksPerFrame

      public long getTicksPerFrame()
      Get the number of simulation ticks per frame.
      Returns:
      the number of ticks per frame
    • getObjectsByZorder

      public SortedSet<AnimationObject2D> getObjectsByZorder()
      Get the set of animation objects that are associated with this animation and that are visible, ordered by their z-order.

      Note: this method would rarely, if ever, be used when an animation is running. It is used mostly when an animation is being developed (for example, the program EPTS uses it to create a background image from an animation that has been configured using a scripting environment but has not been run).

      Returns:
      a sorted set of visible animation objects
    • setFramePriority

      public void setFramePriority(double value)
      Set the priority for simulation events that generate frames. The default is the largest value for the primitive type double because normally frames should be created after other simulation events at the current time complete. If this behavior is not desired, the priority can be changed.
      Parameters:
      value - the priority
    • getFramePriority

      public double getFramePriority()
      Get the priority for simulation events that generate frames.
      Returns:
      value the priority
    • setSupplyGraphicsContexts

      public void setSupplyGraphicsContexts(boolean mode)
      Determine how graphics contexts are provided when an animation object is drawn.

      Setting this mode to true reduces the number of times a new graphics context has to be created and disposed, but some programming errors may cause erratic behavior. Setting it to false is safer but less efficient.

      Parameters:
      mode - true if Animation2D supplies graphics contexts that will be shared by all objects at a given time; false if a graph supplies the graphics contexts each time an object is drawn
    • scheduleFrames

      public void scheduleFrames(long startingFrameTick, int nframes) throws IllegalStateException
      Schedule a subsequence of frames. This schedules a subsequence of frames that will be part of the sequence of frames of which an animation consists. An initFrames method must be called before this method is called.
      Parameters:
      startingFrameTick - the starting time of a frame in units of simulation ticks
      nframes - the number of frames to schedule
      Throws:
      IllegalStateException - the frames are out of order due to previous calls of this method or the maximum number of frames (specified in initFrames) would be exceeded
      See Also:
    • initFrames

      public void initFrames(int maxFrames, String filenamePrefix, String imageType) throws IOException
      Initialize a sequence of frames given a file-name prefix and image type. The file-name prefix should not include a format directive (e.g., %03d) as this will be computed based on the maximum number of frames.

      Once, called, any method names initFrames may not be called again until the simulation has created the number of frames specified by the first argument. The imageType argument must be a string listed by the method ImageIO.getWriterFormatNames() or by ImageMimeInfo.getFormatNames().

      Parameters:
      maxFrames - the maximum number of frames in the sequence.
      filenamePrefix - the initial part of an image file name
      imageType - the type of the images making up a sequence of frames ("png", "jpeg", etc.)
      Throws:
      IOException - an IO error occurred
    • initFrames

      public void initFrames(int maxFrames, String filenamePrefix, String imageType, DirectoryAccessor da) throws IOException
      Initialize a sequence of frames given a file-name prefix, image type, and directory accessor. The file-name prefix should not include a format directive (e.g., %03d) as this will be computed based on the maximum number of frames. The file-name prefix must not specify a parent directory.

      Once, called, any method names initFrames may not be called again until the simulation has created the number of frames specified by the first argument.

      Parameters:
      maxFrames - the maximum number of frames in the sequence.
      filenamePrefix - the initial part of an image file name
      imageType - the type of the images making up a sequence of frames
      da - a directory accessor for the directory that will contain the sequence of images
      Throws:
      IOException - an IO error occurred
    • initFrames

      public void initFrames(int maxFrames, String imageFormat, ISWriterOps isw) throws IOException, IllegalArgumentException
      Initialize a sequence of frames given an image type and image sequence writer.

      Once, called, any method names initFrames may not be called again until the simulation has created the number of frames specified by the first argument.

      Parameters:
      maxFrames - the maximum number of frames in the sequence.
      imageFormat - the format name for the images making up a sequence of frames
      isw - an image sequence writer that will store the images produced by the animation
      Throws:
      IOException - an IO error occurred
      IllegalArgumentException
    • initFrames

      public void initFrames(int maxFrames, ISWriterOps isw) throws IOException, IllegalArgumentException
      Initialize a sequence of frames given an image sequence writer. The second argument's type is an interface implemented by ImageSequenceWriter and AnimatedPanelGraphics, so by merely changing this argument, the animation can be either stored in a file (or passed to an output stream), that will contain a sequence of images, or displayed directly in a window.

      Once, called, any method names initFrames may not be called again until the simulation has created the number of frames specified by the first argument.

      Parameters:
      maxFrames - the maximum number of frames in the sequence.
      isw - an image sequence writer that will store the images produced by the animation
      Throws:
      IOException - an IO error occurred
      IllegalArgumentException
    • getGraph

      public Graph getGraph()
      Get the graph used to represent image frames. The animation will create its graph when one of the initFrames methods are called.
      Specified by:
      getGraph in interface GraphCreator
      Returns:
      the graph; null if the graph has not yet been created
      See Also:
    • getHeightAsInt

      public int getHeightAsInt()
      Get the height of the animation's graph as an integer. The value returned is the same as the height passed to the constructor (or the default height for constructors that do not specify one).

      Note: this method is provided for convenience: it simply calls the method with the same name on the animation's graph.

      Specified by:
      getHeightAsInt in interface GraphCreator
      Specified by:
      getHeightAsInt in interface ISWriterOps.AnimationParameters
      Returns:
      the height
      See Also:
    • getWidthAsInt

      public int getWidthAsInt()
      Get the width of the animation's graph as an integer. The value returned is the same as the width passed to the constructor (or the default width for constructors that do not specify one).

      Note: this method is provided for convenience: it simply calls the method with the same name on the animation's graph.

      Specified by:
      getWidthAsInt in interface GraphCreator
      Specified by:
      getWidthAsInt in interface ISWriterOps.AnimationParameters
      Returns:
      the width
      See Also:
    • getWidth

      public double getWidth()
      Get the width of the animation's graph. The value returned has the same numerical value as the width passed to the constructor (or the default width for constructors that do not specify one).

      Note: this method is provided for convenience: it simply calls the method with the same name on the animation's graph.

      Specified by:
      getWidth in interface GraphCreator
      Returns:
      the width in user-space units
      See Also:
    • getHeight

      public double getHeight()
      Get the height of the animation's graph. The value returned has the same numerical value as the height passed to the constructor (or the default height for constructors that do not specify one).

      Note: this method is provided for convenience: it simply calls the method with the same name on the animation's graph.

      Specified by:
      getHeight in interface GraphCreator
      Returns:
      the height in user-space units
      See Also:
    • setOffsets

      public void setOffsets(int x, int y)
      Set the graph offsets symmetrically.

      Note: this method may be called before getGraph() will return a non-null value. The arguments will be stored and used when the graph is actually created.

      Parameters:
      x - the x offset in user space
      y - the y offset in user space
      See Also:
    • setOffsets

      public void setOffsets(int xL, int xU, int yL, int yU)
      Set the graph offsets.

      Note: this method may be called before getGraph() will return a non-null value. The arguments will be stored and used when the graph is actually created.

      Parameters:
      xL - the lower x offset in user space
      yL - the lower y offset in user space
      xU - the upper x offset in user space
      yU - the upper y offset in user space
      See Also:
    • setRanges

      public void setRanges(double xLower, double xUpper, double yLower, double yUpper)
      Set the x and y ranges. All values are in graph coordinate space.

      Note: this method may be called before getGraph() will return a non-null value. The arguments will be stored and used when the graph is actually created.

      Parameters:
      xLower - the lower value of the range in the x direction
      xUpper - the upper value of the range in the x direction
      yLower - the lower value of the range in the y direction
      yUpper - the upper value of the range in the y direction
      See Also:
    • setRanges

      public void setRanges(double xgcs, double ygcs, double xf, double yf, double scaleFactorX, double scaleFactorY)
      Set ranges based on scale factors. A scale factor is the ratio of a distance in user space to a distance in graph coordinate space. If angles are to be preserved, the scale factors for the X and Y directions must be equal. The scale factors are the numbers by which a coordinate difference in graph coordinate space along the X or Y directions respectively must be multiplied to obtain the corresponding difference in user space.

      In animations where a single image, configured to provide pixels in graph coordinate space units, provides the background for the animation with the same scale factors for the X and Y directions and where one unit in user space matches one unit in image space, the scale factor will be the inverse of the image scale factor used to configure an instance of AnimationLayer2DFactory. If this number is multiplied by a factor f, the apparent size of the image on the screen will also be multiplied by f. If the animation's width and height are equal to f multiplied by the image's width and height respectively, the frame will be just large enough to fully contain the image.

      Note: this method modifies an animation's graph, but may be called before getGraph() will return a non-null value. The arguments will be stored and used when the graph is actually created.

      Parameters:
      xgcs - the x coordinate of a point in graph coordinate space that will be positioned at a specified location on the graph
      ygcs - the y coordinate of a point in graph coordinate space that will be positioned at a specified location on the graph
      xf - the fractional distance from the graph's left offset to its right offset at which the point xgcs in graph coordinate space appears
      yf - the fractional distance from the graph's lower offset to its upper offset at which the point ygcs in graph coordinate space appears
      scaleFactorX - the scale factor for the X direction
      scaleFactorY - the scale factor for the Y direction
      See Also:
    • getXLower

      public double getXLower()
      Get the X coordinate for the lower end of this animation's graph's range. This method may be called before the graph is created, provided that setRanges(double,double,double,double) or setRanges(double,double,double,double,double,double), and possibly setOffsets(int,int) or setOffsets(int,int,int,int), have been called.
      Returns:
      the X coordinate lower end of this animation's graph's range in graph coordinate space
      Throws:
      IllegalStateException - the method setRanges(double,double,double,double) or setRanges(double,double,double,double,double,double) has not been called
    • getYLower

      public double getYLower()
      Get the Y coordinate for the lower end of this animation's graph's range. This method may be called before the graph is created, provided that setRanges(double,double,double,double) or setRanges(double,double,double,double,double,double), and possibly setOffsets(int,int) or setOffsets(int,int,int,int), have been called.
      Returns:
      the Y coordinate lower end of this animation's graph's range in graph coordinate space
      Throws:
      IllegalStateException - the method setRanges(double,double,double,double) or setRanges(double,double,double,double,double,double) has not been called
    • getXUpper

      public double getXUpper()
      Get the X coordinate for the upper end of this animation's graph's range. This method may be called before the graph is created, provided that setRanges(double,double,double,double) or setRanges(double,double,double,double,double,double), and possibly setOffsets(int,int) or setOffsets(int,int,int,int), have been called.
      Returns:
      the X coordinate upper end of this animation's graph's range in graph coordinate space
      Throws:
      IllegalStateException - the method setRanges(double,double,double,double) or setRanges(double,double,double,double,double,double) has not been called
    • getYUpper

      public double getYUpper()
      Get the Y coordinate for the upper end of this animation's graph's range. This method may be called before the graph is created, provided that setRanges(double,double,double,double) or setRanges(double,double,double,double,double,double), and possibly setOffsets(int,int) or setOffsets(int,int,int,int), have been called.
      Returns:
      the Y coordinate upper end of this animation's graph's range in graph coordinate space
      Throws:
      IllegalStateException - the method setRanges(double,double,double,double) or setRanges(double,double,double,double,double,double) has not been called
    • getXLowerOffset

      public int getXLowerOffset()
      Get the lower X offset for this animation's graph. This method may be called before this animation's graph has been created provided that setOffsets(int,int) or setOffsets(int,int,int,int) has been called. Lower and upper refer to the left and right offsets respectively.
      Returns:
      the lower X offset in user-space units
    • getYLowerOffset

      public int getYLowerOffset()
      Get the lower X offset for this animation's graph. This method may be called before this animation's graph has been created provided that setOffsets(int,int) or setOffsets(int,int,int,int) has been called. Lower and upper refer to the left and right offsets respectively.
      Returns:
      the lower X offset in user-space units
    • getXUpperOffset

      public int getXUpperOffset()
      Get the upper X offset for this animation's graph. This method may be called before this animation's graph has been created provided that setOffsets(int,int) or setOffsets(int,int,int,int) has been called. Lower and upper refer to the left and right offsets respectively.
      Returns:
      the upper X offset in user-space units
    • getYUpperOffset

      public int getYUpperOffset()
      Get the upper Y offset for this animation's graph. This method may be called before this animation's graph has been created provided that setOffsets(int,int) or setOffsets(int,int,int,int) has been called. Lower and upper refer to the left and right offsets respectively.
      Returns:
      the upper Y offset in user-space units
    • setBackgroundColor

      public void setBackgroundColor(Color color)
      Set the color to use when clearing the animation's graph.

      Note: this method may be called before getGraph() will return a non-null value. The arguments will be stored and used when the graph is actually created.

      Parameters:
      color - the background color
      See Also:
    • setClearByFillMode

      public void setClearByFillMode(boolean mode)
      Set whether or clearing the animation's graph should add the background color to each pixel in the graph or replace the pixels. For an alpha of 255, the appearance does not depend on the mode. For other values of alpha, when the mode is true, the background color, which is transparent or translucent, will be added to each pixel; when the mode is false, each pixel will be replaced with one having the background color.

      Note: this method may be called before getGraph() will return a non-null value. The arguments will be stored and used when the graph is actually created.

      Parameters:
      mode - true for adding; false for replacing
      See Also:
    • setFont

      public void setFont(Font f)
      Set the font to use for this animation's graph.

      Note: this method may be called before getGraph() will return a non-null value. The arguments will be stored and used when the graph is actually created.

      Parameters:
      f - the font to use
      See Also:
    • setFontColor

      public void setFontColor(Color c)
      Set the font color for this graph.

      Note: this method may be called before getGraph() will return a non-null value. The arguments will be stored and used when the graph is actually created.

      Parameters:
      c - the color; null if the default color should be used
      See Also:
    • setFontJustification

      public void setFontJustification(Graph.Just j)
      Set the font justification for this animation's graph.

      Note: this method is provided for convenience: it simply calls the method with the same name on the animation's graph.

      Parameters:
      j - the font justification
      See Also:
    • setFontBaseline

      public void setFontBaseline(Graph.BLineP blp)
      Set the font vertical alignment for this animation's graph.

      Note: this method is provided for convenience: it simply calls the method with the same name on the animation's graph.

      Parameters:
      blp - the vertical alignment
      See Also:
    • setFontAngle

      public void setFontAngle(double angle)
      Set the font angle for this animation's graph.

      Note: this method is provided for convenience: it simply calls the method with the same name on the animation's graph.

      Parameters:
      angle - the angle in degrees
      See Also:
    • getTicksPerSecond

      public double getTicksPerSecond()
      Get the number of ticks per second.
      Returns:
      the number of ticks per second
    • getFrameRate

      public double getFrameRate()
      Get the animation frame rate.
      Specified by:
      getFrameRate in interface ISWriterOps.AnimationParameters
      Returns:
      the animation frame rate in units of frames per second.
    • estimateFrameCount

      public int estimateFrameCount(double seconds) throws IllegalArgumentException
      Estimate the number of frames needed for an animation to run for a specified time.
      Parameters:
      seconds - the time the animation should run in seconds
      Returns:
      the corresponding number of frames
      Throws:
      IllegalArgumentException - the argument is out of range - either negative or too large
    • setImageType

      public void setImageType(Graph.ImageType type) throws IllegalStateException
      Set the graph image type.

      When null, the Graph.ImageType.INT_RGB is used. A useful value when transparency is needed is Graph.ImageType.INT_ARBG_PRE. This is not the default because JPEG images cannot be created when an alpha channel is used.

      Parameters:
      type - the image type; null for a standard choice
      Throws:
      IllegalStateException - this method was called after an initFrames method was called
    • getImageType

      public Graph.ImageType getImageType()
      Get the image type for the graph associated with this animation. The value returned after a graph is created (by calling one of the initFrames methods) may not be the value existed before the graph was created: it can differ when an argument to initFrames is an instance of ISWriterOps that is not also an instance of ImageSequenceWriter.

      Note the value can be changed by calling setImageType(Graph.ImageType) but that method cannot be called after the graph is created. The image type provides the type of a BufferedImage. This type should not be confused with the string naming an image format used for a file or entry in an image-sequence writer.

      Returns:
      the image type
    • requestAlpha

      public void requestAlpha(boolean mode) throws IllegalStateException
      Set a flag indicating if an alpha channel is requested for the graph associated with this animation. A value of true is applicable when initFrames is called with an argument specifying an ISWriterOps that is not an instance of ImageSequenceWriter or one of its subclasses (if any).
      Parameters:
      mode - true if an alpha channel was requested; false otherwise
      Throws:
      IllegalStateException
    • getRequestAlpha

      public boolean getRequestAlpha()
      Determine if the graph associated with this animation is one for which an alpha channel is requested. The value reported by this method is used for graphs associated with an ISWriterOps that is not an instance of ImageSequenceWriter or one of its subclasses (if any).
      Returns:
      true if an alpha channel was requested; false otherwise
    • setTraceLevels

      public static void setTraceLevels(int level1, int level2, int level3, int level4) throws IllegalArgumentException
      Set the levels for org.bzdev.anim2d trace messages. The defaults are -1, indicating that no messages will be printed. Legal values are -1 or a non-negative integer. For level1, the arguments to various methods will be shown. For level2 or level4, the following parameters are shown
      • x - the X position
      • y - the Y position
      • angle - the angle in radians (absolute).
      the x & y position, and the angle. For level3, the trace will show
      • u - the path parameter
      • v - the path velocity
      • a - the path acceleration
      • angularV - the path angular velocity
      • angularA - the path angular acceleration
      the path parameter, velocity, acceleration, This is provided to allow the caller to choose appropriate values for a given application.
      Parameters:
      level1 - the level for non-update messages
      level2 - the level for update messages
      level3 - the level for additional update messages
      level4 - the level for calls to the PlacedAnimationObject2D method setPosition not shown by update messages
      Throws:
      IllegalArgumentException - an argument was illegal
    • setTraceLevels

      public static <T extends Enum<T>> void setTraceLevels(T level1, T level2, T level3, T level4)
      Set the levels for org.bzdev.anim2d trace messages given enumeration constants. The default levels are -1, indicating that no messages will be printed, corresponding to a null argument for this method. Otherwise the level is the ordinal value of the enumeration types. For level1, the arguments to various methods will be shown. For level2 or level4, the trace will show
      • x - the X position
      • y - the Y position
      • angle - the angle in radians (absolute).
      the x & y position, and the angle. For level3, the trace will show
      • u - the path parameter
      • v - the path velocity
      • a - the path acceleration
      • angularV - the path angular velocity
      • angularA - the path angular acceleration
      the path parameter, velocity, acceleration, This is provided to allow the caller to choose appropriate values for a given application.
      Type Parameters:
      T - the type of an enumeration naming trace levels
      Parameters:
      level1 - the level for non-update messages; null if level 1 messages should not be displayed
      level2 - the level for update messages; null if level 2 messages should not be displayed
      level3 - the level for additional update messages; null if level 3 messages should not be displayed
      level4 - the level for calls to the PlacedAnimationObject2D method setPosition; null if level 4 messages should not be displayed
    • getNamedObjectClass

      public Class<SimObject> getNamedObjectClass()
      Get the class common to all named objects.
      Specified by:
      getNamedObjectClass in interface ObjectNamerOps<SimObject>
      Returns:
      the class
    • addObjectNamer

      public final void addObjectNamer(ObjectNamerOps<SimObject> altNamer)
      Add an alternative object namer for use by getObject methods.
      Specified by:
      addObjectNamer in interface ObjectNamerOps<SimObject>
      Parameters:
      altNamer - the alternative object namer
    • checkAltList

      public boolean checkAltList(ObjectNamerOps<SimObject> altNamer)
      Determine if the argument is equal to this object namer or a member of this object namer's object-namer list. This test is recursive. It is specified in this interface for technical reasons, and is not intended to be called otherwise. It is called by addObjectNamer to ensure that a depth-first search will terminate.
      Specified by:
      checkAltList in interface ObjectNamerOps<SimObject>
      Parameters:
      altNamer - the object namer to test
      Returns:
      true if he argument is equal to this object namer or a member of this object namer's object-namer list, tested recursively; false otherwise
    • getObject

      public SimObject getObject(String name)
      Get an object from the object namer's tables.
      Specified by:
      getObject in interface ObjectNamerOps<SimObject>
      Parameters:
      name - the name of the object
      Returns:
      the object corresponding to the name provided
    • getObjectNames

      public Set<String> getObjectNames()
      Get all the object names from a object namer's tables.
      Specified by:
      getObjectNames in interface ObjectNamerOps<SimObject>
      Returns:
      a set containing the names of all objects interned in the object namer's tables
    • getObjectNames

      public Set<String> getObjectNames(Class<?> clazz)
      Get some the object names from a object namer's tables. The object names are those of objects for which either their classes or one of their superclasses match the class passed as an argument.
      Specified by:
      getObjectNames in interface ObjectNamerOps<SimObject>
      Parameters:
      clazz - the class of the objects whose names are to appear in the set returned
      Returns:
      a set containing the names of all objects interned in the object namer's tables such that the class of that object or the class of a subclass of that object matches the clazz argument
    • getObject

      public <T> T getObject(String name, Class<T> clazz)
      Get a named object with a particular name, provided that the object is a subclass of a specific class.
      Specified by:
      getObject in interface ObjectNamerOps<SimObject>
      Type Parameters:
      T - the type specified by the argument clazz
      Parameters:
      name - the name of the object
      clazz - the class of the object
      Returns:
      the object or null if the object cannot be found
    • getObjects

      public Collection<SimObject> getObjects()
      Get a collection of all the interned named objects assocated with an object namer.
      Specified by:
      getObjects in interface ObjectNamerOps<SimObject>
      Returns:
      an unmodifiable collection of the objects interned in the object namer's tables.
    • getObjects

      public <T> Collection<T> getObjects(Class<T> clazz)
      Get a set of objects from a object namer's tables. The objects are those for which either their classes or one of their superclasses match the class passed as an argument.
      Specified by:
      getObjects in interface ObjectNamerOps<SimObject>
      Type Parameters:
      T - the type specified by the argument clazz
      Parameters:
      clazz - the class of the objects to get.
      Returns:
      a collection containing all interned objects whose class or one of its superclasses matches the class clazz passed as the method's argument
    • getObjects

      public Collection<SimObject> getObjects(String className)
      Get a collection of objects with a class constraint, expressed as a class name, from a object namer's tables. The objects are those for which either their classes or one of their superclasses match the class passed as an argument.

      Note: this method is provided because script engines do not provide a standard way of denoting a Java class (the class not an instance of it). The collection it returns is a collection of the common named object type. Except for scripting languages that do not provide compile-time type checking, one should nearly always use ObjectNamerOps.getObjects(Class).

      Parameters:
      className - the fully qualified class name of the objects to get.
      Returns:
      an unmodifiable collection containing all interned objects whose class or one of its superclasses matches the class clazz passed as the method's argument; an empty (and unmodifiable) collection if no objects can be found
    • configureFactorySupported

      public boolean configureFactorySupported()
      Determine if the configureFactory method is supported.
      Specified by:
      configureFactorySupported in interface ObjectNamerOps<SimObject>
      Returns:
      true if configure() is supported; false otherwise
    • configureFactory

      public void configureFactory(NamedObjectFactory factory, Object scriptObject) throws UnsupportedOperationException, IllegalArgumentException
      Configure a factory. This is an optional operation.
      Specified by:
      configureFactory in interface ObjectNamerOps<SimObject>
      Parameters:
      factory - the factory to be configured
      scriptObject - an object in a scripting language representing a specification for how this factory should be configured
      Throws:
      UnsupportedOperationException - the factory cannot be configured using a script object
      IllegalArgumentException - the scriptObject is ill formed
    • createFactories

      public void createFactories(String pkg, Object scriptObject) throws UnsupportedOperationException, IllegalArgumentException
      Description copied from interface: ObjectNamerOps
      Create multiple factories from a package in a single statement. The first argument is the fully qualified name of a package. The second is a scripting-language object specifying the individual factories and how they should be named. For the object-namer subclass Simulation and its subclasses (DramaSimulation and Animation2D are defined in this class library), the specification for ECMAScript is an ECMAScript objects whose property names are used as the name of a scripting language variable and whose value is a string containing the name of the factory class (excluding its package name, which is provided by the first argument). For example, with ECMAScript for one of these subclasses,
      
          a2d = new Animation2D(scripting, ...);
          a2d.createFactories("org.bzdev.anim2d", {
             alf: "AnimationLayer2DFactory",
             gvf: "GraphViewFactory"
          });
       
      will create two ECMAScript variables whose names are alf and gvf.

      Unless explicitly implemented, this method will throw an UnsupportedOperationException.

      Specified by:
      createFactories in interface ObjectNamerOps<SimObject>
      Parameters:
      pkg - the fully-qualified package name
      scriptObject - a scripting-language object specifying factories that should be created
      Throws:
      UnsupportedOperationException - this object namer does not support scripting or creating multiple factories specified by a scripting object
      IllegalArgumentException - an argument was not suitable for creating a factory.
    • createFactory

      public NamedObjectFactory createFactory(String varName, String packageName, String className) throws UnsupportedOperationException, IllegalArgumentException
      Create a factory and store it in a scripting-language variable. The factory must have a single-argument constructor that takes its object namer as its argument.

      This method is provided for convenience - to reduce the amount of typing when adding factories to a script. It returns the factory that was created in addition to storing it in a variable in case a user of this method tries to assign the value it returns.

      Specified by:
      createFactory in interface ObjectNamerOps<SimObject>
      Parameters:
      varName - the name of a scripting-language variable
      packageName - the name of the package (null or an empty string for the unnamed package)
      className - the class name of a factory, excluding the package name
      Returns:
      the factory that was created
      Throws:
      IllegalArgumentException - the factory is not listed in a META-INF/services/org.bzdev.NamedObjectFactory resource or the class name does not refer to subclass of NamedObjectFactory
      UnsupportedOperationException - this object namer does not support scripting;
    • createFactory

      public NamedObjectFactory createFactory(String className) throws IllegalArgumentException
      Create a factory. The factory must have a single-argument constructor that takes its object namer as its argument.
      Specified by:
      createFactory in interface ObjectNamerOps<SimObject>
      Parameters:
      className - the fully-qualified class name of a factory.
      Returns:
      a new factory
      Throws:
      IllegalArgumentException - the factory is not listed in a META-INF/services/org.bzdev.NamedObjectFactory resource or the class name does not refer to subclass of NamedObjectFactory
    • createFactory

      public NamedObjectFactory createFactory(Class clazz) throws IllegalArgumentException
      Create a factory given a class. The factory must have a single-argument constructor that takes its object namer as its argument.
      Specified by:
      createFactory in interface ObjectNamerOps<SimObject>
      Parameters:
      clazz - the factory's class
      Returns:
      a new factory
      Throws:
      IllegalArgumentException - the factory is not listed in a META-INF/services/org.bzdev.NamedObjectFactory resource or the class name does not refer to subclass of NamedObjectFactory