home *** CD-ROM | disk | FTP | other *** search
/ Programming Languages Suite / ProgLangD.iso / VCAFE.3.0A / Main.bin / VisualProperty.java < prev    next >
Text File  |  1998-10-25  |  13KB  |  372 lines
  1. /*
  2.  * Copyright 1998 Symantec Corporation, All Rights Reserved.
  3.  */
  4.  
  5. package com.symantec.itools.vcafe.openapi;
  6.  
  7. import com.symantec.itools.vcafe.openapi.dtreflect.DTClass;
  8.  
  9. /**
  10.  * The API used to represent a property of a <code>VisualObject</code>.
  11.  *
  12.  * A plug-in can obtain a list of these objects from a <code>VisualObject</code>'s <code>getProperties</code>
  13.  * method.  A plug-in can use the methods in this class to update the property value and other attributes.
  14.  *
  15.  * The implementation of all of <code>VisualProperty</code>'s abstract methods first calls
  16.  * checkValidity().  Any method could therefore throw an <code>InvalidVisualPropertyException</code>.
  17.  * This exception extends <code>RuntimeException</code>, so doesn't have to be explicity declared or
  18.  * caught.  A <code>VisualProperty</code> can become invalid if it's <code>VisualObject</code> is removed from
  19.  * its project, or its project is closed, and the corresponding <code>VisualObjectListener</code> message is
  20.  * ignored, for example.
  21.  *
  22.  * @see VisualObject#getProperties
  23.  * @see InvalidVisualPropertyException
  24.  *
  25.  * @author Symantec Internet Tools Division
  26.  * @version 1.0
  27.  * @since VCafe 3.0
  28.  */
  29. public abstract class VisualProperty
  30. {
  31.     /**
  32.      * Gets the (human readable) name of this property.
  33.      *
  34.      * @return     the name of this property.
  35.      */
  36.     public abstract String getName();
  37.  
  38.     /**
  39.      * Gets the <code>VisualObject</code> that owns this property.
  40.      *
  41.      * @return this property's <code>VisualObject</code>.
  42.      */
  43.     public abstract VisualObject getVisualObject();
  44.  
  45.     /**
  46.      * Gets the (internal, unique) name of this property.
  47.      *
  48.      * @return the unique name for this property.
  49.      */
  50.     public abstract String getInternalPropertyName();
  51.  
  52.     /**
  53.      * Gets the nesting level of this property (for grouped properties).
  54.      *
  55.      * @return this property's nesting level.
  56.      */
  57.     public abstract int getLevel();
  58.  
  59.     /**
  60.      * Gets the first child property of this property (for folders).
  61.      * @return this property's first child.
  62.      * @see #isFolder
  63.      */
  64.     public abstract VisualProperty getFirstChild();
  65.  
  66.     /**
  67.      * Gets the sibling property of this property (for grouped properties).
  68.      *
  69.      * @return this property's sibling.
  70.      */
  71.     public abstract VisualProperty getSibling();
  72.  
  73.     /**
  74.      * Gets an <code>Object</code> representation this property's value.
  75.      * For example, if this property represents a <code>VisualObject</code>'s font, a <code>java.awt.Font</code>
  76.      * object is returned.
  77.      *
  78.      * @return this property's value as an <code>Object</code>.
  79.      */
  80.     public abstract Object getValue();
  81.  
  82.     /**
  83.      * Gets a <code>String</code> representation of this property's value.
  84.      *
  85.      * @return this property's value as a <code>String</code>.
  86.      */
  87.     public abstract String getValueString();
  88.  
  89.     /**
  90.      * Set this property's value, given a <code>String</code> representation of the new value.
  91.      *
  92.      * @param pValue <code>String</code> representation of the new value.
  93.      * @return <code>true</code> if successfully set, <code>false</code> otherwise.
  94.      */
  95.     public abstract boolean setValueString(String pValue);
  96.  
  97.     /**
  98.      * Appends a new element with the given value to this property (for arrays).
  99.      * @param pValue <code>String</code> representation of the new value.
  100.      * @see #isArray
  101.      */
  102.     public abstract void appendValueString(String pValue);
  103.  
  104.     /**
  105.      * Gets the value of an array element (for arrays).
  106.      * @param index the zero-based element index.
  107.      * @return the value as a <code>String</code>.
  108.      * @see #isArray
  109.      */
  110.     public abstract String getNthValueString(int index);
  111.  
  112.     /**
  113.      * Sets the value of an array element (for arrays).
  114.      * @param index the zero-based element index.
  115.      * @param pValue <code>String</code> representation of the new value.
  116.      * @see #isArray
  117.      */
  118.     public abstract void setNthValueString(int index, String pValue);
  119.  
  120.     /**
  121.      * Gets the number of array elements this property has (for arrays).
  122.      * @return the size of the array.
  123.      * @see #isArray
  124.      */
  125.     public abstract int getNumValues();
  126.  
  127.     /**
  128.      * Sets the number of array elements a property has to zero (for arrays).
  129.      * @see #isArray
  130.      */
  131.     public abstract void setArrayEmpty();
  132.  
  133.     /**
  134.      * Gets the number of <code>String</code> values this property enumerates (for enumerations).
  135.      * @return the number of elements.
  136.      * @see #isEnumerated
  137.      */
  138.     public abstract int getNumEnum();
  139.  
  140.     /**
  141.      * Gets the value of an enumeration element (for enumerations).
  142.      * @param the zero-based enumeration index.
  143.      * @return the element value.
  144.      * @see #isEnumerated
  145.      */
  146.     public abstract String getEnum(int index);
  147.  
  148.     // Applicable only for enumerated, mapped properties
  149.     public abstract int getEnumKey(int index);
  150.  
  151.     /**
  152.      * Gets the name of the method used to get the value of this property.
  153.      * @return the name of the method used to get the property value.
  154.      * @see #getSetterName
  155.      * @see #getPropertyType
  156.      */
  157.     public abstract String getGetterName();
  158.  
  159.     /**
  160.      * Gets the name of the method used to set the value of this property.
  161.      * @return the name of the method used to set the value of this property.
  162.      * @see #getSetterParameterType
  163.      * @see #getGetterName
  164.      * @see #getPropertyType
  165.      */
  166.     public abstract String getSetterName();
  167.  
  168.     /**
  169.      * Gets the class name of the the setter method's parameter.
  170.      * @return the class name of the parameter in the setter method.
  171.      * @see #getSetterParameterType
  172.      * @see #getPropertyType
  173.      */
  174.     public abstract String getSetterParameterType();
  175.  
  176.     /**
  177.      * Gets the class of this property's value.
  178.      * @return the class of this property's value.
  179.      * @see #getGetterName
  180.      * @see #getSetterName
  181.      */
  182.     public abstract DTClass getPropertyType();
  183.  
  184.     /**
  185.      * Gets the exceptions that setting this property can throw.  The returned value is a comma-delimited
  186.      * <code>String</code> like:
  187.      * "java.lang.NullPointerException,java.lang.NumberFormatException".
  188.      * @return a <code>String</code> of exceptions.
  189.      */
  190.     public abstract String getExceptions();
  191.  
  192.     /**
  193.      * Gets the class name of the eidtor used to view and edit this property.
  194.      * @return the editor's class name.
  195.      */
  196.     public abstract String getPropertyEditorName();
  197.  
  198.     /**
  199.      * This method is intended for use when generating Java code to set the value of the property.
  200.      * It returns a fragment of Java code that can be used to initialize a variable with the current
  201.      * property value.
  202.      * Example results are: "2", "new Color(127,127,34)", "Color.orange", etc.
  203.      * @return a fragment of Java code representing an initializer for the current value.
  204.      */
  205.     public abstract String getJavaInitializationString();
  206.  
  207.     /**
  208.      * If the custom property has a reference to a java object, it will be released.
  209.      */
  210.     public abstract void unloadPropertyObject();
  211.  
  212.     /**
  213.      * Determines whether the value of this property is editable.
  214.      * @return <code>true</code> if the value is editable, <code>false</code> otherwise.
  215.      */
  216.     public abstract boolean isEditable();
  217.  
  218.     /**
  219.      * Determines whether this property is displayed in the Property List.
  220.      * @return <code>true</code> if <b>not</b>, <code>false</code> otherwise.
  221.      */
  222.     public abstract boolean isInvisible();
  223.  
  224.     /**
  225.      * Sets whether this property is displayed in the Property List.
  226.      * @param invisible <code>true</code> if this property should <b>not</b> be displayed in the Property List.
  227.      */
  228.     public abstract void setInvisible(boolean invisible);
  229.  
  230.     /**
  231.      * Determines whether this is a folder type property.
  232.      * @return <code>true</code> if so, <code>false</code> otherwise.
  233.      */
  234.     public abstract boolean isFolder();
  235.  
  236.     /**
  237.      * Determines whether this is an enumerated type property.
  238.      * @return <code>true</code> if so, <code>false</code> otherwise.
  239.      */
  240.     public abstract boolean isEnumerated();
  241.  
  242.     public abstract boolean isMapped();
  243.  
  244.     /**
  245.      * Determines whether this is an array type property.
  246.      * @return <code>true</code> if so, <code>false</code> otherwise.
  247.      */
  248.     public abstract boolean isArray();
  249.  
  250.     /**
  251.      * Determines whether this property can be copied.
  252.      * @return <code>true</code> if so, <code>false</code> otherwise.
  253.      */
  254.     public abstract boolean isCopyable();
  255.  
  256.     public abstract boolean isBound();
  257.     public abstract boolean isConstrained();
  258.     public abstract boolean isCustom();
  259.  
  260.     /**
  261.      * Determines whether editing the value of this property requires a custom editor.
  262.      * @return <code>true</code> if so, <code>false</code> otherwise.
  263.      */
  264.     public abstract boolean isCustomEditor();
  265.  
  266.     public abstract boolean isPaintable();
  267.     public abstract boolean isUserGroup();
  268.  
  269.     /**
  270.      * Determines if this property is currently set to its default value.
  271.      * @return <code>true</code> if so, <code>false</code> otherwise.
  272.      */
  273.     public abstract boolean isDefault();
  274.  
  275.  
  276.     /**
  277.      * Determines whether this is an object reference type property.  If <code>true</code> the value of this
  278.      * property is a reference to a <code>VisualObject</code>.
  279.      * @return <code>true</code> if so, <code>false</code> otherwise.
  280.      * @see getReferencedVisualObjectID
  281.      * @see setReferencedVisualObjectID
  282.      */
  283.     public abstract boolean isObjectReferenceProperty();
  284.  
  285.         /**
  286.          * Indicates an object reference type property currently references the default <code>VisualObject</code>.
  287.          * @see #getReferencedVisualObjectID
  288.          * @see #NO_OBJECT_REFERENCED
  289.          */
  290.         public static final int DEFAULT_OBJECT_REFERENCED = -1;
  291.  
  292.         /**
  293.          * Indicates an object reference type property currently references no object (ie is "<code>null</code>").
  294.          * @see #getReferencedVisualObjectID
  295.          * @see #DEFAULT_OBJECT_REFERENCED
  296.          */
  297.         public static final int NO_OBJECT_REFERENCED = 0;
  298.  
  299.     /**
  300.      * Gets the id of the <code>VisualObject</code> the value of this property refers to.
  301.      * @return the object ID of the <code>VisualObject</code> this property refers to or <code>DEFAULT_OBJECT_REFERENCED</code>
  302.      * or <code>NODEFAULT_OBJECT_REFERENCED</code>.
  303.      * @see #DEFAULT_OBJECT_REFERENCED
  304.      * @see #NO_OBJECT_REFERENCED
  305.      * @see #setReferencedVisualObjectID
  306.      * @see #getReferencedVisualObject
  307.      * @see VisualObject#getObjectID
  308.      */
  309.     public abstract int getReferencedVisualObjectID();
  310.  
  311.     /**
  312.      * Gets the <code>VisualObject</code> the value of this property refers to, or <code>null</code>.
  313.      * @return the <code>VisualObject</code> the value of this property refers to, or <code>null</code>.
  314.      * @see #getReferencedVisualObjectID
  315.      */
  316.     public abstract VisualObject getReferencedVisualObject();
  317.  
  318.     /**
  319.      * Sets the value of this property to a reference to a <code>VisualObject</code>.
  320.      * @param refVisualObjectID the object i of the <code>VisualObject</code> this property refers to or
  321.      * <code>DEFAULT_OBJECT_REFERENCED</code> or <code>NODEFAULT_OBJECT_REFERENCED</code>.
  322.      * @see #DEFAULT_OBJECT_REFERENCED
  323.      * @see #NO_OBJECT_REFERENCED
  324.      * @see #getReferencedVisualObjectID
  325.      * @see #getReferencedVisualObject
  326.      * @see VisualObject#getObjectID
  327.      */
  328.     public abstract void setReferencedVisualObjectID(int refVisualObjectID);
  329.  
  330.  
  331.     /**
  332.      * Determines if one <code>VisualProperty</code> is equivalent to another.
  333.      * @param other the <code>VisualProperty</code> to compare with.
  334.      * @return <code>true</code> if the two <code>VisualProperties</code> refer to the same property in the same
  335.      * <code>VisualObject</code>, <code>false</code> otherwise.
  336.      */
  337.     public abstract boolean equals(VisualProperty other);
  338.  
  339.     /**
  340.      * Determines if this <code>VisualProperty</code> corresponds to a valid property in its <code>VisualObject</code>.
  341.      * A <code>VisualProperty</code> can become invalid if it's <code>VisualObject</code> is removed from
  342.      * its project, or its project is closed, and the corresponding <code>VisualObjectListener</code> message is
  343.      * ignored, for example.
  344.      * @return <code>true</code> if the this <code>VisualProperty</code> is still valid, <code>false</code> otherwise
  345.      * @see #checkValidity
  346.      */
  347.     public abstract boolean isValid();
  348.  
  349.     /**
  350.      * Checks that this <code>VisualProperty</code> corresponds to a valid property in its <code>VisualObject</code>.
  351.      * Note that the implementation of all of <code>VisualProperty</code>'s abstract methods first call
  352.      * checkValidity().  Any method could therefore throw an <code>InvalidVisualPropertyException</code>.
  353.      *
  354.      * @exception com.symantec.itools.vcafe.openapi.InvalidVisualPropertyException
  355.      * when its <code>VisualObject</code> has been removed from its project, or its project has
  356.      * been closed, for example
  357.      * @see #isValid
  358.      */
  359.     public void checkValidity() throws InvalidVisualPropertyException {
  360.         if (!isValid()) throw new InvalidVisualPropertyException();
  361.     }
  362.  
  363.     /**
  364.      * Gets a <code>String</code> that represents this object.
  365.      * @return the <code>String</code>.
  366.      */
  367.     public String toString() {
  368.         if (!isValid()) return "invalid VisualProperty: " + super.toString();
  369.         return "VisualProperty[" + getInternalPropertyName() + "]";
  370.     }
  371. }
  372.