Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## org.eclipse.birt.report.model.api
Class DimensionHandle

    java.lang.Object
      org.eclipse.birt.report.model.api.ElementDetailHandle
          org.eclipse.birt.report.model.api.ValueHandle
              org.eclipse.birt.report.model.api.ComplexValueHandle
                  org.eclipse.birt.report.model.api.DimensionHandle

    public class DimensionHandle

extends ComplexValueHandle

Simplifies working with dimension properties. A dimension property consists of a measure and a dimension. This handle helps assemble and disassemble dimension property values. The dimension property itself can be either a top-level element property, or the member of a property structure.

Note that this handle cannot translate a dimension property into a physical dimension. BIRT uses the CSS dimension system and requires a CSS User Agent (UA) to compute the physical layout of a report given a report design. These calculations often require context (to compute relative dimensions) and knowledge of item contents to compute the sizes of items that expand to fit their content.

This handle works with individual dimensions, the application-provided UA uses these properties (and information about the overall report design) to produce physical, absolute dimensions.

The application generally does not create dimension handles directly. It uses the method in `DesignElementHandle` to get a dimension handle. For example:

     DesignElementHandle elementHandle = element.handle( );

     DimensionHandle dimensionHandle = elementHandle
                    .getDimensionProperty( Style.FONT_SIZE_PROP );

The value of the dimension can be a standard format such as 1pt, 100% etc. This kind of value represents a standard dimension, or it can be a CSS (predefined) value such as XX-SMALL, X-SMALL. The CSS values are defined in `DesignChoiceConstants`.

See Also:
  `DesignChoiceConstants`

Field Summary

Fields inherited from class org.eclipse.birt.report.model.api.ComplexValueHandle
`memberRef, propDefn`

Fields inherited from class org.eclipse.birt.report.model.api.ElementDetailHandle
`elementHandle`

Constructor Summary
`DimensionHandle(DesignElementHandle element, org.eclipse.birt.report.model.metadata.ElementPropertyDefn thePropDefn)` Constructs a dimension handle for a element property.
`DimensionHandle(DesignElementHandle element, org.eclipse.birt.report.model.core.MemberRef memberRef)` Constructs a dimension handle for a member of a structure.

Method Summary
`DimensionValue` | `getAbsoluteValue()` Returns the absolute dimension value with the following units.
`IChoice[]` | `getAllowedUnits()` Returns an array of allowed units.
`java.lang.String` | `getDefaultUnit()` Gets the default unit of the property.
`double` | `getMeasure()` Returns the numeric measure part of the dimension.
`java.lang.String` | `getUnits()` Returns the code for the units portion of the dimension.
`boolean` | `isKeyword()` Determines if the dimension is given by a standard format or by a pre-defined constant.
`void` | `setAbsolute(double value)` Sets the value of a dimension in default units.

Methods inherited from class org.eclipse.birt.report.model.api.ComplexValueHandle
`getDefn, getDisplayValue, getPropertyDefn, getReference, getStringValue, getValue, isSet, setStringValue, setValue`

Methods inherited from class org.eclipse.birt.report.model.api.ElementDetailHandle
`getDesign, getElement, getElementHandle, getModule`

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Constructor Detail

### DimensionHandle

    public DimensionHandle(DesignElementHandle element,
                           org.eclipse.birt.report.model.core.MemberRef memberRef)

  Constructs a dimension handle for a member of a structure. This member must be a dimension type.

  Parameters:
    `element` - the design element handle
    `memberRef` - the memberRef for the member property

### DimensionHandle

    public DimensionHandle(DesignElementHandle element,
                           org.eclipse.birt.report.model.metadata.ElementPropertyDefn thePropDefn)

  Constructs a dimension handle for a element property. This property must be a dimension type.

  Parameters:
    `element` - handle to the element that defined the property.
    `thePropDefn` - definition of the dimension property.

Method Detail

### isKeyword

    public boolean isKeyword()

  Determines if the dimension is given by a standard format or by a pre-defined constant.

  Returns:
    `true` if the dimension is given by an pre-defined constant `false` if the dimension is given by a standard dimension.

### getMeasure

    public double getMeasure()

  Returns the numeric measure part of the dimension. For example, if the dimension value is "2.3cm", the measure is 2.3.

  Returns:
    the numeric measure of the dimension, return `0.0` if the dimension from an choice.

### getAllowedUnits

    public IChoice[] getAllowedUnits()

  Returns an array of allowed units. The set of allowed units depends on context, not all properties allow all units.

  Returns:
    an array of allowed unit suffixes. Each suffix is a string.

### getUnits

    public java.lang.String getUnits()

  Returns the code for the units portion of the dimension. For example, if the dimension value is "2.3cm", then the unit is "cm".

  Returns:
    the units portion of the dimension. Return `DimensionValue.DEFAULT_UNIT` if the dimension is a predefined constant.

### setAbsolute

    public void setAbsolute(double value)
                     throws SemanticException

  Sets the value of a dimension in default units. The default unit may be defined by the property in BIRT or the application unit defined in the design session.

  Parameters:
    `value` - the new value in application units.
  Throws:
    `SemanticException` - if the property is locked

### getAbsoluteValue

    public DimensionValue getAbsoluteValue()

  Returns the absolute dimension value with the following units.
  - UNITS_IN
  - UNITS_CM
  - UNITS_MM
  - UNITS_PT
  - UNITS_PC
  - UNITS_PX
  This method tries to get the absolute value for absolute font size constants with `IAbsoluteFontSizeValueProvider`. Only the value of CSS property of the element which is not style is handled here. `null` is returned if this dimension is not CSS style property.

  CSS 2.1 specification has the following statements:

  Child elements do not inherit the relative values specified for their parent; they inherit the computed values.

  Example(s):

  In the following rules, the computed 'text-indent' value of "h1" elements will be 36px, not 45px, if "h1" is a child of the "body" element.

  body { font-size: 12px; text-indent: 3em; /* i.e., 36px}}

  h1 { font-size: 15px }

  So when computing the value of text-indent, with this method, the value of font-size is retrieved from body, instead of h1.

  Returns:
    the absolute dimension value.

### getDefaultUnit

    public java.lang.String getDefaultUnit()

  Gets the default unit of the property.

  Returns:
    the default unit

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright © 2008 Actuate Corp. All rights reserved.