Class Plan
All Packages  Class Hierarchy  This Package  Previous  Next  Index

Class Plan

public class netscape.constructor.Plan
    extends java.lang.Object
    implements netscape.application.ExtendedTarget,
               netscape.util.Codable,
               java.lang.Cloneable
{
    /* Fields
     */
    public final static String ASCII_FILE_EXTENSION;
    public final static int ASCII_TYPE;
    public final static String BINARY_FILE_EXTENSION;
    public final static int BINARY_TYPE;

    /* Constructors
     */
    public Plan(String);
    public Plan(String, Hashtable);
    public Plan(String, Target);
    public Plan(InputStream, int);

    /* Methods
     */
    public static Plan createPlan(String);
    public static Plan createPlan(String, Hashtable);
    public static Plan createPlan(String, Target);
    public static Plan createPlan(InputStream, int);

    public void addContentsToView(View);
    public Color backgroundColor();
    public Rect boundingRect();
    public Object componentNamed(String);
    public Vector components();
    public ExternalWindow externalWindowWithContents();
    public InternalWindow internalWindowWithContents();
    public void moveBy(int, int);
    public Hashtable nameToComponent();
    public Hashtable objectToBounds();
    public void releaseObjects();
    public Vector rootComponents();
    public Size size();
    public void sizeToFit();
    public boolean unarchiveObjects(Hashtable);
    public boolean unarchiveObjects(Target);
    public boolean unarchiveObjects();
    public String url();
    public View viewWithContents();
}
The Plan object represents the contents of a .plan file created with Netscape's Constructor. When the .plan file is saved in Constructor, the actual objects and all of their state is recorded. The Plan object allows you to reload the information stored in the .plan file and recreate the objects contained therein exactly as they were when they were saved.

One of the key features of the Plan object involves the use of the TargetProxy object within a .plan file. Many times you will want to connect events from objects within the .plan file to objects outside of the .plan file. One example of this would be the Application object. Normally, you want to get the application to perform some command by pressing a button, but the application object is not created in the .plan file, so you cannot directly connect the button's onClick event to the Application object. The TargetProxy object allows you to place a named stand-in object to represent the Application object and connect the button's onClick event to this proxy. The Plan file allows you to replace this TargetProxy with the real object at load time. This allows you to wire object events to objects outside the .plan file.

There are several ways to get the views out of the Plan object. There are methods to put all the root components into a new View, InternalWindow, or ExternalWindow. You can also get to any named component by using the componentNamed() method. A vector containing all the root components and the Hashtable containing the name to component mappings are also available.

The standard constructors take the .plan file name and some object(s) to replace the TargetProxies within the .plan file. They call one of the unarchiveObjects() methods to create the actual objects. After the constructor successfully returns, you can get to the view objects and place them in the proper view hierarchy. After you have retrived all of the view objects properly, you can throw away the Plan object. If you want to create multiple copies of the objects within the .plan file, you may call one of unarchiveObjects() methods to create these copies. All references to the previous views will be cleared. If you wish to keep the Plan object around, but remove any references to the real objects from the Plan object, call releaseObjects(). This will keep the reference to the archiveData, but remove the references to the actual objects. Here is a summary of what objects are stored where:


Note: This documentation has been limited to the mimimum information necessary to start using Plan objects. The Plan object itself has a much richer API set than is documented here. Please see the source file Plan.java for full comments on the capabilities of the Plan object.
See Also:
TargetProxy

Fields

ASCII_TYPE

  public final static int ASCII_TYPE
Plan file is saved in ASCII format and has a filename extention of ASCII_FILE_EXTENSION

BINARY_TYPE

  public final static int BINARY_TYPE
Plan file is saved in binary format and has a filename extention of BINARY_FILE_EXTENSION

ASCII_FILE_EXTENSION

  public final static String ASCII_FILE_EXTENSION
File name extension for ASCII files.

BINARY_FILE_EXTENSION

  public final static String BINARY_FILE_EXTENSION
File name extension for Binary files.

Constructors

.Plan

  public Plan(String url) throws IOException
Loads the archive data from the url, and calls unarchiveObjects(). The url should be relative to the application's codeBase(). The codeBase() will be appended to the url before the url is opened.

.Plan

  public Plan(String url,
              Hashtable targets) throws IOException
Loads the archive data from the url, and calls unarchiveObjects(targets). The url should be relative to the application's codeBase(). The codeBase() will be appended to the url before the url is opened.

.Plan

  public Plan(String url,
              Target target) throws IOException
Loads the archive data from the url, and calls unarchiveObjects(target). The url should be relative to the application's codeBase(). The codeBase() will be appended to the url before the url is opened.

.Plan

  public Plan(java.io.InputStream stream,
              int formatOfStream) throws IOException
Loads the archive data from the stream. The formatOfStream must be either ASCII_TYPE or BINARY_TYPE indicating the type of data on the stream. This constructor only creates the archive data. To get the actual objects contained within this Plan, you must call one of the unarchiveObjects() methods.

Methods

.createPlan

  public static Plan createPlan(String url)
Convience method for the Plan constructor of the same format. Returns null if the constructor throws.

.createPlan

  public static Plan createPlan(String url,
                                Hashtable targets)
Convience method for the Plan constructor of the same format. Returns null if the constructor throws.

.createPlan

  public static Plan createPlan(String url,
                                Target target)
Convience method for the Plan constructor of the same format. Returns null if the constructor throws.

.createPlan

  public static Plan createPlan(java.io.InputStream stream,
                                int formatOfStream)
Convience method for the Plan constructor of the same format. Returns null if the constructor throws.

.releaseObjects

  public void releaseObjects()
This is a convience method to release the references we have to the objects within the Plan file. Everything except the archiveData will be set to null. If you want to create another set of objects, call one of the unarchiveObjects() methods with the appropriate TargetProxy replacements.

.unarchiveObjects

  public boolean unarchiveObjects(Hashtable targets)
Creates the objects stored in the archive data that was loaded from one of the constructors. TargetProxies in the archive with names matching those in the targetProxies will be replaced with the object from the targetProxies Hashtable. Any objects in targetProxies that do not implement the Target interface will be ignored. validObjects will be set to true if the objects were unarchived correctly.

.unarchiveObjects

  public boolean unarchiveObjects(Target target)
Convience method for unarchiveObjects(Hashtable). The target object will replace all TargetProxy objects contained in the archive data. This is convient when there is only a single TargetProxy in the plan archive.

.unarchiveObjects

  public boolean unarchiveObjects()
Convience method for unarchiveObjects(Hashtable). A null Hashtable is passed in, resulting in none of the TargetProxies being replaced. Useful if you have no targetProxy objects in the plan archive, or you are going to me manipulating the archived objects and want to retain the TargetProxy objects as is.

.nameToComponent

  public Hashtable nameToComponent()
Hashtable of any name to component object mappings. This table may be empty if none of the components have been named. These names correspond to the "Constructor Name" attribute in Constructor.

.componentNamed

  public Object componentNamed(String name)
Convience method for getting a component named name Equivalent to:
 return nameToComponent().get(name); 

.objectToBounds

  public Hashtable objectToBounds()
Objects that are not derived from View generally do not store their own bounds Rect. So that these objects can maintain their visual position in the plan file, their 'bounds' are stored in this Hashtable. This Hashtable will normally have all the non-View derived objects in it. Normally all non-View objects are also stored in the rootComponents vector (because they are not views and therefore cannot participate in the view hierarchy) and additionally in the components vector.

.rootComponents

  public Vector rootComponents()
This is a list of the components that are at the top of the view heirarchy within the plan file. All views are reachable by traversing these objects. All non-View derived objects will be in this vector as well as any View based objects dropped on the background area in Constructor. Any object in rootComponents should also be in the components vector.

.components

  public Vector components()
This is a list of all views that Constructor considers to be Components. Generally, any view that was dropped from a Tray in Constructor is on this list. This list is used by Constructor to determine which views are components and which views are simply subviews of other components.

A simple example would be the ContainerView object. It normally has a single subview that displays it's title string. This subview is not in this list of components, but if you where to the traverse the view hierarchy, you would find it. Therefore Constructor ignores the title subview when determining what view you clicked on and want to edit. This Vector is normally not interesting outside of Constructor.

.size

  public Size size()
The size of the document. This is the size of the document area that was set in Constructor.

.url

  public String url()
The url used to load this plan file.

.backgroundColor

  public Color backgroundColor()
Background color used for the document area. Normally used as the background color on an ExternalWindow.

.boundingRect

  public Rect boundingRect()
Returns the bounding box that fits all View derived components. InternalWindows are ignored in calculating this Rect.

.sizeToFit

  public void sizeToFit()
Resets size() to be boundingBox() size and adjusts views accordingly, i.e. moves the upper left most component to 0,0 and moves all other components the same delta amounts.

.moveBy

  public void moveBy(int x,
                     int y)
Sends moveBy(x, y) to all the rootComponents() that are views.

.addContentsToView

  public void addContentsToView(View aView)
Adds all the rootComponents() that are views to aView.

.viewWithContents

  public View viewWithContents()
Creates a new View(size().width, size().height), adds all View based components to it and returns the view.

.internalWindowWithContents

  public InternalWindow internalWindowWithContents()
Adds all the rootComponents() that are views to the contentView() of a new InternalWindow. Uses the current document size to correctly size the internal window.

.externalWindowWithContents

  public ExternalWindow externalWindowWithContents()
Adds all the rootComponents() that are views to the rootView() of a new ExternalWindow. Uses the current document size to correctly size the internal window.

All Packages  Class Hierarchy  This Package  Previous  Next  Index

Copyright © 1997 Netscape Communications Corporation. All rights reserved
Please send any comments or corrections to ifcfeedback@netscape.com
HTML generated on 21 Oct 1997