trunk/src/bind/java/org/w3c/dom/css/CSSPrimitiveValue.java

   1 /*
   2  * Copyright (c) 2000 World Wide Web Consortium,
   3  * (Massachusetts Institute of Technology, Institut National de
   4  * Recherche en Informatique et en Automatique, Keio University). All
   5  * Rights Reserved. This program is distributed under the W3C's Software
   6  * Intellectual Property License. This program is distributed in the
   7  * hope that it will be useful, but WITHOUT ANY WARRANTY; without even
   8  * the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
   9  * PURPOSE.
  10  * See W3C License http://www.w3.org/Consortium/Legal/ for more details.
  11  */
  12
  13 package org.w3c.dom.css;
  14
  15 import org.w3c.dom.DOMException;
  16
  17 /**
  18  *  The <code>CSSPrimitiveValue</code> interface represents a single CSS value
  19  * . This interface may be used to determine the value of a specific style
  20  * property currently set in a block or to set a specific style property
  21  * explicitly within the block. An instance of this interface might be
  22  * obtained from the <code>getPropertyCSSValue</code> method of the
  23  * <code>CSSStyleDeclaration</code> interface. A
  24  * <code>CSSPrimitiveValue</code> object only occurs in a context of a CSS
  25  * property.
  26  * <p> Conversions are allowed between absolute values (from millimeters to
  27  * centimeters, from degrees to radians, and so on) but not between relative
  28  * values. (For example, a pixel value cannot be converted to a centimeter
  29  * value.) Percentage values can't be converted since they are relative to
  30  * the parent value (or another property value). There is one exception for
  31  * color percentage values: since a color percentage value is relative to
  32  * the range 0-255, a color percentage value can be converted to a number;
  33  * (see also the <code>RGBColor</code> interface).
  34  * <p>See also the <a href='http://www.w3.org/TR/2000/REC-DOM-Level-2-Style-20001113'>Document Object Model (DOM) Level 2 Style Specification</a>.
  35  * @since DOM Level 2
  36  */
  37 public interface CSSPrimitiveValue extends CSSValue {
  38     // UnitTypes
  39     /**
  40      * The value is not a recognized CSS2 value. The value can only be
  41      * obtained by using the <code>cssText</code> attribute.
  42      */
  43     public static final short CSS_UNKNOWN               = 0;
  44     /**
  45      * The value is a simple number. The value can be obtained by using the
  46      * <code>getFloatValue</code> method.
  47      */
  48     public static final short CSS_NUMBER                = 1;
  49     /**
  50      * The value is a percentage. The value can be obtained by using the
  51      * <code>getFloatValue</code> method.
  52      */
  53     public static final short CSS_PERCENTAGE            = 2;
  54     /**
  55      * The value is a length (ems). The value can be obtained by using the
  56      * <code>getFloatValue</code> method.
  57      */
  58     public static final short CSS_EMS                   = 3;
  59     /**
  60      * The value is a length (exs). The value can be obtained by using the
  61      * <code>getFloatValue</code> method.
  62      */
  63     public static final short CSS_EXS                   = 4;
  64     /**
  65      * The value is a length (px). The value can be obtained by using the
  66      * <code>getFloatValue</code> method.
  67      */
  68     public static final short CSS_PX                    = 5;
  69     /**
  70      * The value is a length (cm). The value can be obtained by using the
  71      * <code>getFloatValue</code> method.
  72      */
  73     public static final short CSS_CM                    = 6;
  74     /**
  75      * The value is a length (mm). The value can be obtained by using the
  76      * <code>getFloatValue</code> method.
  77      */
  78     public static final short CSS_MM                    = 7;
  79     /**
  80      * The value is a length (in). The value can be obtained by using the
  81      * <code>getFloatValue</code> method.
  82      */
  83     public static final short CSS_IN                    = 8;
  84     /**
  85      * The value is a length (pt). The value can be obtained by using the
  86      * <code>getFloatValue</code> method.
  87      */
  88     public static final short CSS_PT                    = 9;
  89     /**
  90      * The value is a length (pc). The value can be obtained by using the
  91      * <code>getFloatValue</code> method.
  92      */
  93     public static final short CSS_PC                    = 10;
  94     /**
  95      * The value is an angle (deg). The value can be obtained by using the
  96      * <code>getFloatValue</code> method.
  97      */
  98     public static final short CSS_DEG                   = 11;
  99     /**
 100      * The value is an angle (rad). The value can be obtained by using the
 101      * <code>getFloatValue</code> method.
 102      */
 103     public static final short CSS_RAD                   = 12;
 104     /**
 105      * The value is an angle (grad). The value can be obtained by using the
 106      * <code>getFloatValue</code> method.
 107      */
 108     public static final short CSS_GRAD                  = 13;
 109     /**
 110      * The value is a time (ms). The value can be obtained by using the
 111      * <code>getFloatValue</code> method.
 112      */
 113     public static final short CSS_MS                    = 14;
 114     /**
 115      * The value is a time (s). The value can be obtained by using the
 116      * <code>getFloatValue</code> method.
 117      */
 118     public static final short CSS_S                     = 15;
 119     /**
 120      * The value is a frequency (Hz). The value can be obtained by using the
 121      * <code>getFloatValue</code> method.
 122      */
 123     public static final short CSS_HZ                    = 16;
 124     /**
 125      * The value is a frequency (kHz). The value can be obtained by using the
 126      * <code>getFloatValue</code> method.
 127      */
 128     public static final short CSS_KHZ                   = 17;
 129     /**
 130      * The value is a number with an unknown dimension. The value can be
 131      * obtained by using the <code>getFloatValue</code> method.
 132      */
 133     public static final short CSS_DIMENSION             = 18;
 134     /**
 135      * The value is a STRING. The value can be obtained by using the
 136      * <code>getStringValue</code> method.
 137      */
 138     public static final short CSS_STRING                = 19;
 139     /**
 140      * The value is a URI. The value can be obtained by using the
 141      * <code>getStringValue</code> method.
 142      */
 143     public static final short CSS_URI                   = 20;
 144     /**
 145      * The value is an identifier. The value can be obtained by using the
 146      * <code>getStringValue</code> method.
 147      */
 148     public static final short CSS_IDENT                 = 21;
 149     /**
 150      * The value is a attribute function. The value can be obtained by using
 151      * the <code>getStringValue</code> method.
 152      */
 153     public static final short CSS_ATTR                  = 22;
 154     /**
 155      * The value is a counter or counters function. The value can be obtained
 156      * by using the <code>getCounterValue</code> method.
 157      */
 158     public static final short CSS_COUNTER               = 23;
 159     /**
 160      * The value is a rect function. The value can be obtained by using the
 161      * <code>getRectValue</code> method.
 162      */
 163     public static final short CSS_RECT                  = 24;
 164     /**
 165      * The value is a RGB color. The value can be obtained by using the
 166      * <code>getRGBColorValue</code> method.
 167      */
 168     public static final short CSS_RGBCOLOR              = 25;
 169
 170     /**
 171      * The type of the value as defined by the constants specified above.
 172      */
 173     public short getPrimitiveType();
 174
 175     /**
 176      *  A method to set the float value with a specified unit. If the property
 177      * attached with this value can not accept the specified unit or the
 178      * float value, the value will be unchanged and a
 179      * <code>DOMException</code> will be raised.
 180      * @param unitType A unit code as defined above. The unit code can only
 181      *   be a float unit type (i.e. <code>CSS_NUMBER</code>,
 182      *   <code>CSS_PERCENTAGE</code>, <code>CSS_EMS</code>,
 183      *   <code>CSS_EXS</code>, <code>CSS_PX</code>, <code>CSS_CM</code>,
 184      *   <code>CSS_MM</code>, <code>CSS_IN</code>, <code>CSS_PT</code>,
 185      *   <code>CSS_PC</code>, <code>CSS_DEG</code>, <code>CSS_RAD</code>,
 186      *   <code>CSS_GRAD</code>, <code>CSS_MS</code>, <code>CSS_S</code>,
 187      *   <code>CSS_HZ</code>, <code>CSS_KHZ</code>,
 188      *   <code>CSS_DIMENSION</code>).
 189      * @param floatValue The new float value.
 190      * @exception DOMException
 191      *    INVALID_ACCESS_ERR: Raised if the attached property doesn't support
 192      *   the float value or the unit type.
 193      *   <br>NO_MODIFICATION_ALLOWED_ERR: Raised if this property is readonly.
 194      */
 195     public void setFloatValue(short unitType,
 196                               float floatValue)
 197                               throws DOMException;
 198
 199     /**
 200      *  This method is used to get a float value in a specified unit. If this
 201      * CSS value doesn't contain a float value or can't be converted into
 202      * the specified unit, a <code>DOMException</code> is raised.
 203      * @param unitType A unit code to get the float value. The unit code can
 204      *   only be a float unit type (i.e. <code>CSS_NUMBER</code>,
 205      *   <code>CSS_PERCENTAGE</code>, <code>CSS_EMS</code>,
 206      *   <code>CSS_EXS</code>, <code>CSS_PX</code>, <code>CSS_CM</code>,
 207      *   <code>CSS_MM</code>, <code>CSS_IN</code>, <code>CSS_PT</code>,
 208      *   <code>CSS_PC</code>, <code>CSS_DEG</code>, <code>CSS_RAD</code>,
 209      *   <code>CSS_GRAD</code>, <code>CSS_MS</code>, <code>CSS_S</code>,
 210      *   <code>CSS_HZ</code>, <code>CSS_KHZ</code>,
 211      *   <code>CSS_DIMENSION</code>).
 212      * @return  The float value in the specified unit.
 213      * @exception DOMException
 214      *    INVALID_ACCESS_ERR: Raised if the CSS value doesn't contain a float
 215      *   value or if the float value can't be converted into the specified
 216      *   unit.
 217      */
 218     public float getFloatValue(short unitType)
 219                                throws DOMException;
 220
 221     /**
 222      *  A method to set the string value with the specified unit. If the
 223      * property attached to this value can't accept the specified unit or
 224      * the string value, the value will be unchanged and a
 225      * <code>DOMException</code> will be raised.
 226      * @param stringType A string code as defined above. The string code can
 227      *   only be a string unit type (i.e. <code>CSS_STRING</code>,
 228      *   <code>CSS_URI</code>, <code>CSS_IDENT</code>, and
 229      *   <code>CSS_ATTR</code>).
 230      * @param stringValue The new string value.
 231      * @exception DOMException
 232      *    INVALID_ACCESS_ERR: Raised if the CSS value doesn't contain a string
 233      *   value or if the string value can't be converted into the specified
 234      *   unit.
 235      *   <br>NO_MODIFICATION_ALLOWED_ERR: Raised if this property is readonly.
 236      */
 237     public void setStringValue(short stringType,
 238                                String stringValue)
 239                                throws DOMException;
 240
 241     /**
 242      *  This method is used to get the string value. If the CSS value doesn't
 243      * contain a string value, a <code>DOMException</code> is raised.  Some
 244      * properties (like 'font-family' or 'voice-family') convert a
 245      * whitespace separated list of idents to a string.
 246      * @return  The string value in the current unit. The current
 247      *   <code>primitiveType</code> can only be a string unit type (i.e.
 248      *   <code>CSS_STRING</code>, <code>CSS_URI</code>,
 249      *   <code>CSS_IDENT</code> and <code>CSS_ATTR</code>).
 250      * @exception DOMException
 251      *    INVALID_ACCESS_ERR: Raised if the CSS value doesn't contain a string
 252      *   value.
 253      */
 254     public String getStringValue()
 255                                  throws DOMException;
 256
 257     /**
 258      *  This method is used to get the Counter value. If this CSS value
 259      * doesn't contain a counter value, a <code>DOMException</code> is
 260      * raised. Modification to the corresponding style property can be
 261      * achieved using the <code>Counter</code> interface.
 262      * @return The Counter value.
 263      * @exception DOMException
 264      *    INVALID_ACCESS_ERR: Raised if the CSS value doesn't contain a
 265      *   Counter value (e.g. this is not <code>CSS_COUNTER</code>).
 266      */
 267     public Counter getCounterValue()
 268                                    throws DOMException;
 269
 270     /**
 271      *  This method is used to get the Rect value. If this CSS value doesn't
 272      * contain a rect value, a <code>DOMException</code> is raised.
 273      * Modification to the corresponding style property can be achieved
 274      * using the <code>Rect</code> interface.
 275      * @return The Rect value.
 276      * @exception DOMException
 277      *    INVALID_ACCESS_ERR: Raised if the CSS value doesn't contain a Rect
 278      *   value. (e.g. this is not <code>CSS_RECT</code>).
 279      */
 280     public Rect getRectValue()
 281                              throws DOMException;
 282
 283     /**
 284      *  This method is used to get the RGB color. If this CSS value doesn't
 285      * contain a RGB color value, a <code>DOMException</code> is raised.
 286      * Modification to the corresponding style property can be achieved
 287      * using the <code>RGBColor</code> interface.
 288      * @return the RGB color value.
 289      * @exception DOMException
 290      *    INVALID_ACCESS_ERR: Raised if the attached property can't return a
 291      *   RGB color value (e.g. this is not <code>CSS_RGBCOLOR</code>).
 292      */
 293     public RGBColor getRGBColorValue()
 294                                      throws DOMException;
 295
 296 }