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 GroupElementHandle

    java.lang.Object
      org.eclipse.birt.report.model.api.GroupElementHandle

Direct Known Subclasses:
  EmptyGroupElementHandle, SimpleGroupElementHandle

    public abstract class GroupElementHandle

extends java.lang.Object

This class provides services to deal with a group of elements. It is mostly useful for some multiple-selection cases, elements of the same type(or share the same base type) can be handled as a whole. User can perform some operations on the collection of elements.

For our ease-of-use purpose, we support multiple selections across type. Given a collection of elements, user can ask for their common properties(including user property definitions). Also, return a list of values that are identical for all items. Finally, return an indication of whether all elements are of the same type.

This class also supports a collection of elements contains some objects that are not a `DesignElementHandle` or its subclass. For this case, `getCommonProperties` always returns an empty list.

For BIRT UI usage, the attributes view will go blank if the providing elements are not of the same type, the property sheet will show the common properties(including user property definitions).

This handle is mutable, it can be kept. The query results changed as the given elements themselves changed.

Note that the Model special handling of the case where all elements are the same type: in this case, by definition, all BIRT-defined properties are the same. (User-defined properties may differ.)

Constructor Summary
`GroupElementHandle()` Default constructor.

Method Summary
`protected abstract boolean` | `allExtendedElements()` Checks if all elements have extends parents or virtual parents.
`abstract void` | `clearLocalProperties()` Clears values of all common properties(except the extends property) for the given collection of elements.
`void` | `clearProperty(java.lang.String propName)` Clears the value of a property on the given collection of elements if the property is a common property shared by each element.
`abstract java.util.List` | `getCommonProperties()` Returns the common properties shared by the given group of elements(including user properties).
`java.lang.String` | `getDisplayProperty(java.lang.String propName)` If the given property is a common property, value will be returned as a display value if all values within the group of elements are equal.
`abstract java.util.List` | `getElements()` Returns the list that contains the group of design elements.
`java.lang.String` | `getLocalStringProperty(java.lang.String propName)` If the given property is a common property, value will be returned as a string if all values within the group of elements are equal and one of them has a local value.
`abstract org.eclipse.birt.report.model.core.Module` | `getModule()` Returns the module.
`abstract ModuleHandle` | `getModuleHandle()` Returns the handle of module.
`abstract GroupPropertyHandle` | `getPropertyHandle(java.lang.String propName)` If property is shared by the group of elements, return the corresponding `GroupPropertyHandle`, otherwise, return `null`.
`java.lang.String` | `getStringProperty(java.lang.String propName)` If the given property is a common property, value will be returned as a string if all values within the group of elements are equal.
`boolean` | `hasLocalPropertiesForExtendedElements()` This method returnt `true` in following condition:
`abstract boolean` | `isExtendedElements()` Returns `true` if each of the given collection of element extends has a parent.
`protected abstract boolean` | `isInGroup(DesignElementHandle element)` Checks whether the `element` is a member of `GroupElementHandle`.
`protected abstract boolean` | `isPropertyReadOnly(java.lang.String propName)` Checks whether a property is read-only in the property sheet.
`protected abstract boolean` | `isPropertyVisible(java.lang.String propName)` Checks whether a property is visible in the property sheet.
`abstract boolean` | `isSameType()` Indicates that if the given elements are of the same definition.
`java.util.Iterator` | `propertyIterator()` Returns an iterator over the common properties.
`void` | `setProperty(java.lang.String propName, java.lang.Object value)` Set the value of a property on the given collection of elements.
`void` | `setStringProperty(java.lang.String propName, java.lang.String value)` Set the value of a property to a string .
`boolean` | `shareSameValue(java.lang.String propName)` Indicates whether the group of element share the same value for this property.
`abstract java.util.Iterator` | `visiblePropertyIterator()` Returns an iterator over the common properties that are visible.

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

Constructor Detail

### GroupElementHandle

    public GroupElementHandle()

  Default constructor.

Method Detail

### getElements

    public abstract java.util.List getElements()

  Returns the list that contains the group of design elements. Contents of it is `DesignElementHandle`

  Returns:
    the list that contains the group of design elements.

### getModule

    public abstract org.eclipse.birt.report.model.core.Module getModule()

  Returns the module.

  Returns:
    the module

### getModuleHandle

    public abstract ModuleHandle getModuleHandle()

  Returns the handle of module.

  Returns:
    the handle of module

### isSameType

    public abstract boolean isSameType()

  Indicates that if the given elements are of the same definition. Elements are considered of same type if their element definitions are identical.

  If elements have different definitions. Even the same element type, the return value is `false`. For example, if the list contains an `OdaDataSource` and a `OdaDataSource`, this method returns `false`.

  Returns:
    `true` if the given elements are of the same type; return `false` if elements are of different element types, or the given list is empty, or the list contains any object that is not an instance of `DesignElementHandle`.

### getCommonProperties

    public abstract java.util.List getCommonProperties()

  Returns the common properties shared by the given group of elements(including user properties). Contents of the list is element property definitions. If elements do not share any common property, return an empty list.

  Returns:
    the common properties shared by the given group of elements. If elements do not share any common property, or the given list is empty, or the list contains any item that is not an instance of `DesignElementHandle`, return an empty list.

### propertyIterator

    public final java.util.Iterator propertyIterator()

  Returns an iterator over the common properties. Contents of the iterator are handles to the common properties, type of them is `GroupPropertyHandle`. Note: remove is not support for the iterator.

  Returns:
    an iterator over the common properties. Contents of the iterator are handles to the common properties, type of them is `GroupPropertyHandle`

### visiblePropertyIterator

    public abstract java.util.Iterator visiblePropertyIterator()

  Returns an iterator over the common properties that are visible. Contents of the iterator are handles to the common properties, type of them is `GroupPropertyHandle`. Note: remove is not support for the iterator.

  Returns:
    an iterator over the common properties. Contents of the iterator are handles to the common properties, type of them is `GroupPropertyHandle`

### isPropertyVisible

    protected abstract boolean isPropertyVisible(java.lang.String propName)

  Checks whether a property is visible in the property sheet. The visible property is visible in all `elements`.

  Parameters:
    `propName` - the property name
  Returns:
    `true` if it is visible. Otherwise `false`.

### clearLocalProperties

    public abstract void clearLocalProperties()
                                       throws SemanticException

  Clears values of all common properties(except the extends property) for the given collection of elements. Clearing a property removes any value set for the property on this element. After this, the element will now inherit the property from its parent element, style, or from the default value for the property.

  Throws:
    `SemanticException` - if the property is not defined on this element

### isExtendedElements

    public abstract boolean isExtendedElements()

  Returns `true` if each of the given collection of element extends has a parent. Returns `false` otherwise. If the collection has no elements, also return `false`

  Returns:
    `true` if each of the given collection of element extends has a parent. Returns `false` otherwise. If the collection has no elements, also return `false`

### hasLocalPropertiesForExtendedElements

    public final boolean hasLocalPropertiesForExtendedElements()

  This method returnt `true` in following condition:

  1. The multi selected elements are same type.

  2. And the multi selected elements have extends.

  3. If any of the given elements has local properties.

  Returns:
    `true` if the conditions is met.

### allExtendedElements

    protected abstract boolean allExtendedElements()

  Checks if all elements have extends parents or virtual parents.

  Returns:
    `true` If all elements have extend parents or virtual parents. Otherwise `false`;

### isPropertyReadOnly

    protected abstract boolean isPropertyReadOnly(java.lang.String propName)

  Checks whether a property is read-only in the property sheet. The visible property is read-only in all `elements`.

  Parameters:
    `propName` - the property name
  Returns:
    `true` if it is read-only. Otherwise `false`.

### getPropertyHandle

    public abstract GroupPropertyHandle getPropertyHandle(java.lang.String propName)

  If property is shared by the group of elements, return the corresponding `GroupPropertyHandle`, otherwise, return `null`.

  Parameters:
    `propName` - name of the property needs to be handled.
  Returns:
    If the property is a common property among the elements, return the corresponding `GroupPropertyHandle`; Otherwise return `null`.

### getStringProperty

    public final java.lang.String getStringProperty(java.lang.String propName)

  If the given property is a common property, value will be returned as a string if all values within the group of elements are equal. If the property is not a common property, return `null`.

  Parameters:
    `propName` - name of the property.
  Returns:
    the value as a string if the property is a common property and all the elements have the same value. Return null if the property is not a common property or elements have different values for this property.
  See Also:
    `GroupPropertyHandle.getStringValue()`

### getDisplayProperty

    public final java.lang.String getDisplayProperty(java.lang.String propName)

  If the given property is a common property, value will be returned as a display value if all values within the group of elements are equal. If the property is not a common property, return `null`.

  Parameters:
    `propName` - name of the property.
  Returns:
    the value as a display value if the property is a common property and all the elements have the same value. Return null if the property is not a common property or elements have different values for this property.
  See Also:
    `GroupPropertyHandle#getDisplayProperty()`

### getLocalStringProperty

    public final java.lang.String getLocalStringProperty(java.lang.String propName)

  If the given property is a common property, value will be returned as a string if all values within the group of elements are equal and one of them has a local value. If the property is not a common property or none of them has a local value, return `null`.

  Parameters:
    `propName` - name of the property.
  Returns:
    the value as a string if the property is a common property, all the elements have the same value and one of them has a local value. Return null if the property is not a common property or elements have different values for this property or none of them has a local value.
  See Also:
    `GroupPropertyHandle.getLocalStringValue()`

### shareSameValue

    public final boolean shareSameValue(java.lang.String propName)

  Indicates whether the group of element share the same value for this property.

  If all element has a `null` value for this property, it is considered that they share the same value.

  Parameters:
    `propName` - name of the property.
  Returns:
    `true` if the group of element share the same value. Return `false` if the property is not a common property or elements have different values for this property.

### setProperty

    public final void setProperty(java.lang.String propName,
                                  java.lang.Object value)
                           throws SemanticException

  Set the value of a property on the given collection of elements. If the property provided is not a common property then this method simply return; Otherwise, the value will be set on the group of elements.

  Parameters:
    `propName` - name of the property.
    `value` - value needs to set.
  Throws:
    `SemanticException` - if the value is invalid for the property, or the property is undefined on the elements.
  See Also:
    `GroupPropertyHandle.setValue(Object)`

### clearProperty

    public final void clearProperty(java.lang.String propName)
                             throws SemanticException

  Clears the value of a property on the given collection of elements if the property is a common property shared by each element. Clearing a property removes any value set for the property on this element. After this, the element will now inherit the property from its parent element, style, or from the default value for the property.

  If the property provided is not a common property then this method simply return, else, the value will be cleared on the group of elements.

  Parameters:
    `propName` - the name of the property to clear.
  Throws:
    `SemanticException` - if the property is not defined on this element

### setStringProperty

    public final void setStringProperty(java.lang.String propName,
                                        java.lang.String value)
                                 throws SemanticException

  Set the value of a property to a string . If the property provided is not a common property then this method simply return; Else, the string value will be set on the group of element.

  Parameters:
    `propName` - name of the property.
    `value` - value needs to set.
  Throws:
    `SemanticException` - if the value is invalid for the property, or the property is undefined on the elements.

### isInGroup

    protected abstract boolean isInGroup(DesignElementHandle element)

  Checks whether the `element` is a member of `GroupElementHandle`.

  Parameters:
    `element` - the element to check
  Returns:
    `true` if the element is in the list, otherwise `false`.

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.