Package org.eclipse.birt.report.model.api

# Class ImageHandle

java.lang.Object
org.eclipse.birt.report.model.api.DesignElementHandle
org.eclipse.birt.report.model.api.ReportElementHandle
org.eclipse.birt.report.model.api.ReportItemHandleImpl
org.eclipse.birt.report.model.api.ReportItemHandle
org.eclipse.birt.report.model.api.ImageHandle

All Implemented Interfaces:
  `IReportItemMethodContext`, `org.eclipse.birt.report.model.elements.interfaces.IDesignElementModel`, `org.eclipse.birt.report.model.elements.interfaces.IImageItemModel`, `org.eclipse.birt.report.model.elements.interfaces.IInternalReportItemModel`, `org.eclipse.birt.report.model.elements.interfaces.IStyledElementModel`

public class ImageHandle extends ReportItemHandle implements org.eclipse.birt.report.model.elements.interfaces.IImageItemModel
Represents an image report item. The image can come from a number of sources:

- embedded image in the report design
- image file
- image presented by URL
- expression which returns the image contents

The image has the following properties:

- An optional hyperlink for this image.
- An optional help text for the image.
- An optional text message to display in place of the image in a web browser.

The image item can be sized to the image (in which case the height and width attributes are ignored), or the image can be sized or clipped to fit the item. Images are always scaled as percentage proportionately.

See Also:
  - `ImageItem`
  - `DesignChoiceConstants`

## Field Summary

### Fields inherited from class org.eclipse.birt.report.model.api.ReportItemHandleImpl

`DATABINDING_TYPE_DATA, DATABINDING_TYPE_NONE, DATABINDING_TYPE_REPORT_ITEM_REF`

### Fields inherited from class org.eclipse.birt.report.model.api.ReportElementHandle

`element`

### Fields inherited from class org.eclipse.birt.report.model.api.DesignElementHandle

`module`

### Fields inherited from interface org.eclipse.birt.report.model.elements.interfaces.IDesignElementModel

`COMMENTS_PROP, CUSTOM_XML_PROP, DISPLAY_NAME_ID_PROP, DISPLAY_NAME_PROP, EVENT_HANDLER_CLASS_PROP, EXTENDS_PROP, FULL_LABEL, ID_SUFFIX, NAME_PROP, NEW_HANDLER_ON_EACH_EVENT_PROP, NO_SLOT, PROPERTY_MASKS_PROP, REF_TEMPLATE_PARAMETER_PROP, SHORT_LABEL, USER_LABEL, USER_PROPERTIES_PROP, VIEW_ACTION_PROP`

### Fields inherited from interface org.eclipse.birt.report.model.elements.interfaces.IImageItemModel

`ACTION_PROP, ALT_TEXT_KEY_PROP, ALT_TEXT_PROP, FIT_TO_CONTAINER_PROP, HELP_TEXT_ID_PROP, HELP_TEXT_PROP, IMAGE_NAME_PROP, PROPORTIONAL_SCALE_PROP, SCALE_PROP, SIZE_PROP, SOURCE_PROP, TYPE_EXPR_PROP, URI_PROP, VALUE_EXPR_PROP`

### Fields inherited from interface org.eclipse.birt.report.model.elements.interfaces.IInternalReportItemModel

`ACL_EXPRESSION_PROP, ALLOW_EXPORT_PROP, ALTTEXT_KEY_PROP, ALTTEXT_PROP, BOOKMARK_DISPLAY_NAME_PROP, BOOKMARK_PROP, BOUND_DATA_COLUMNS_PROP, CASCADE_ACL_PROP, CUBE_PROP, DATA_BINDING_REF_PROP, DATA_SET_PROP, HEIGHT_PROP, LANGUAGE_PROP, MULTI_VIEWS_PROP, ON_CREATE_METHOD, ON_PAGE_BREAK_METHOD, ON_PREPARE_METHOD, ON_RENDER_METHOD, ORDER_PROP, PARAM_BINDINGS_PROP, PUSH_DOWN_PROP, TAG_TYPE_PROP, THEME_PROP, TOC_PROP, URL_PROP, VISIBILITY_PROP, WIDTH_PROP, X_PROP, Y_PROP, Z_INDEX_PROP`

### Fields inherited from interface org.eclipse.birt.report.model.api.elements.IReportItemMethodContext

`ON_CREATE_CONTEXT, ON_PREPARE_CONTEXT, ON_RENDER_CONTEXT`

### Fields inherited from interface org.eclipse.birt.report.model.elements.interfaces.IStyledElementModel

`STYLE_PROP`

## Constructor Summary

Constructors
Constructor
Description
`ImageHandle(org.eclipse.birt.report.model.core.Module module, org.eclipse.birt.report.model.core.DesignElement element)`
Constructs a image handle with the given design and the element.

## Method Summary

Modifier and Type
Method
Description
`Iterator<ActionHandle>`
`actionsIterator()`
Returns the iterator for action defined on this image item.
`boolean`
`fitToContainer()`
Gets the fit to container property value of this image item.
`ActionHandle`
`getActionHandle()`
Returns a handle to work with the action property, action is a structure that defines a hyperlink.
`String`
`getAltText()`
Deprecated.
`EmbeddedImageHandle`
`getEmbeddedImage()`
Returns the embedded image handle that this image refers, if the image source type is `IMAGE_REF_TYPE_EMBED`.
`String`
`getFile()`
Returns the image URI if the image source type is `IMAGE_REF_TYPE_URL` or `IMAGE_REF_TYPE_FILE`.
`String`
`getHelpText()`
Returns the help text of this image item.
`String`
`getHelpTextKey()`
Returns the resource key of the help text of this image item.
`String`
`getImageName()`
Returns the embedded image name that this image refers, if the image source type is `IMAGE_REF_TYPE_EMBED`.
`double`
`getScale()`
Returns the image scale.
`String`
`getSize()`
Returns the image size.
`String`
`getSource()`
Returns the image source type.
`String`
`getTypeExpression()`
Returns the type expression of the image item if the image source type is `IMAGE_REF_TYPE_EXPR`.
`String`
`getURI()`
Returns the image URI if the image source type is `IMAGE_REF_TYPE_URL` or `IMAGE_REF_TYPE_FILE`.
`String`
`getURL()`
Returns the image URI if the image source type is `IMAGE_REF_TYPE_URL` or `IMAGE_REF_TYPE_FILE`.
`String`
`getValueExpression()`
Returns the value expression of the image if the image source type is `IMAGE_REF_TYPE_EXPR`.
`boolean`
`isProportionalScale()`
Gets the flag which indicates whether the image scales proportionally or not.
`ActionHandle`
`setAction(Action action)`
Set an action on the image.
`void`
`setAltText(String altText)`
Deprecated.
`void`
`setFile(String file)`
Sets the image uri property.
`void`
`setFile(Expression expr)`
Sets the image uri property by an expression.
`void`
`setFitToContainer(boolean fitToContainer)`
Sets the fit to container property value of this image item.
`void`
`setHelpText(String helpText)`
Sets the help text of this image item.
`void`
`setHelpTextKey(String helpTextKey)`
Sets the resource key of help text of this image item.
`void`
`setImageName(String name)`
Sets the embedded image name that this image refers, if the image source type is `IMAGE_REF_TYPE_EMBED`.
`void`
`setProportionalScale(boolean proportionalScale)`
Sets the flag which indicates whether the image scales proportionally or not.
`void`
`setScale(double scale)`
Sets the image scale property.
`void`
`setSize(String size)`
Sets the image size property.
`void`
`setSource(String source)`
Sets the image source type.
`void`
`setTypeExpression(String value)`
Sets the type expression value.
`void`
`setURI(String uri)`
Deprecated.
should use `setFile(String)` or `setURL(String)`.
`void`
`setURL(String url)`
Sets the image uri property.
`void`
`setURL(Expression expr)`
Sets the image uri property by an expression.
`void`
`setValueExpression(String value)`
Sets the value expression value.

### Methods inherited from class org.eclipse.birt.report.model.api.ReportItemHandleImpl

`addColumnBinding, addTOC, addTOC, addView, allowExport, canAddView, canCascadeACL, cascadeACL, columnBindingsIterator, dropView, findColumnBinding, getACLExpression, getAltTextExpression, getAltTextKey, getAvailableBindings, getAvailableCubeBindingReferenceList, getAvailableDataBindingReferenceList, getAvailableDataBindingReferenceList, getAvailableDataSetBindingReferenceList, getBookmark, getBookmarkDisplayName, getColumnBindings, getCube, getCurrentView, getDataBindingReference, getDataBindingReferenceName, getDataBindingType, getDataSet, getHeight, getLanguage, getMethods, getNamedCubeBindingReferenceList, getNamedDataBindingReferenceList, getNamedDataSetBindingReferenceList, getOnCreate, getOnPageBreak, getOnPrepare, getOnRender, getOrder, getProperty, getTagType, getTheme, getTOC, getTocExpression, getViewHost, getViews, getWidth, getX, getY, getZIndex, paramBindingsIterator, pushDown, removedColumnBinding, removedColumnBindings, removedUnusedColumnBindings, setACLExpression, setAllowExport, setAltTextExpression, setAltTextKey, setBookmark, setBookmarkDisplayName, setCascadeACL, setCube, setCurrentView, setDataBindingReference, setDataSet, setHeight, setHeight, setLanguage, setOnCreate, setOnPageBreak, setOnPrepare, setOnRender, setOrder, setPushDown, setTagType, setTheme, setThemeName, setTocExpression, setWidth, setWidth, setX, setX, setY, setY, setZIndex, visibilityRulesIterator`

### Methods inherited from class org.eclipse.birt.report.model.api.ReportElementHandle

`getComments, getCustomXml, getDisplayName, getDisplayNameKey, getElement, getPropertyMask, isValidLayoutForCompoundElement, isValidReferenceForCompoundElement, propertyMaskIterator, setComments, setCustomXml, setDisplayName, setDisplayNameKey, setPropertyMask`

### Methods inherited from class org.eclipse.birt.report.model.api.DesignElementHandle

`add, add, addElement, addElement, addListener, addUserPropertyDefn, cachePropertyHandles, canContain, canContain, canContain, canContain, canDrop, canEdit, canTransformToTemplate, clearAllProperties, clearContents, clearProperty, clientsIterator, copy, copyPropertyTo, createTemplateElement, derivedIterator, doSort, drop, drop, drop, dropAndClear, dropAndClear, dropAndClear, dropUserPropertyDefn, findContentSlot, getBooleanProperty, getChoices, getColorProperty, getContainer, getContainerPropertyHandle, getContainerSlotHandle, getContent, getContentCount, getContents, getDefn, getDesign, getDesignHandle, getDimensionProperty, getDisplayLabel, getDisplayLabel, getDisplayProperty, getEffectiveModule, getElementFactory, getElementProperty, getEventHandlerClass, getExpressionProperty, getExtends, getExternalizedValue, getExternalizedValue, getExternalizedValue, getFactoryElementHandle, getFactoryPropertyHandle, getFloatProperty, getFontProperty, getFullName, getHostViewHandle, getID, getIndex, getIntProperty, getListProperty, getListProperty, getMethods, getModule, getModuleHandle, getName, getNumberProperty, getPrivateStyle, getPropertyBinding, getPropertyBindingExpression, getPropertyBindings, getPropertyDefn, getPropertyHandle, getPropertyIterator, getQualifiedName, getRoot, getSemanticErrors, getSlot, getStringProperty, getStyle, getUserProperties, getUserPropertyDefnHandle, getXPath, hasLocalProperties, hasSemanticError, initializeSlotHandles, isDirectionRTL, isInTemplateParameter, isTemplateParameterValue, isValid, localize, move, move, moveTo, moveTo, moveTo, moveTo, newHandlerOnEachEvent, paste, paste, paste, paste, removeListener, revertToReportItem, revertToTemplate, semanticCheck, setBooleanProperty, setEncryption, setEventHandlerClass, setExpressionProperty, setExtends, setExtendsElement, setExtendsName, setFloatProperty, setIntProperty, setName, setNewHandlerOnEachEvent, setNumberProperty, setProperties, setProperty, setPropertyBinding, setPropertyBinding, setStringProperty, setStyle, setStyleElement, setStyleName, setValid, shift, showError, slotsIterator`

### Methods inherited from class java.lang.Object

`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

## Constructor Details

### ImageHandle

public ImageHandle(org.eclipse.birt.report.model.core.Module module, org.eclipse.birt.report.model.core.DesignElement element)
Constructs a image handle with the given design and the element. The application generally does not create handles directly. Instead, it uses one of the navigation methods available on other element handles.

Parameters:
  `module` - the module
  `element` - the model representation of the element

## Method Details

### getScale

public double getScale()
Returns the image scale. The scale factor for the image given as a percentage.

Returns:
  the scale of this image.

### getSize

public String getSize()
Returns the image size. The size must be the internal name that is one the following options defined in `DesignChoiceConstants`:

- `IMAGE_SIZE_SIZE_TO_IMAGE`
- `IMAGE_SIZE_SCALE_TO_ITEM`
- `IMAGE_SIZE_CLIP`

Returns:
  the internal value of the image size.

### getAltText

@Deprecated public String getAltText()
Deprecated.
Returns the alternate text of this image.

Returns:
  the alternate text of the image item.

### setAltText

@Deprecated public void setAltText(String altText) throws SemanticException
Deprecated.
Sets the the alternate text of this image.

Parameters:
  `altText` - the alternate text
Throws:
  `SemanticException`

### getSource

public String getSource()
Returns the image source type. This is one of the following options defined in `DesignChoiceConstants`:

- `IMAGE_REF_TYPE_NONE`
- `IMAGE_REF_TYPE_URL`
- `IMAGE_REF_TYPE_FILE`
- `IMAGE_REF_TYPE_EXPR`
- `IMAGE_REF_TYPE_EMBED`

Returns:
  the image source type.

### setSource

public void setSource(String source) throws SemanticException
Sets the image source type. This is one of the following options defined in `DesignChoiceConstants`:

- `IMAGE_REF_TYPE_NONE`
- `IMAGE_REF_TYPE_URL`
- `IMAGE_REF_TYPE_FILE`
- `IMAGE_REF_TYPE_EXPR`
- `IMAGE_REF_TYPE_EMBED`

Parameters:
  `source` - the image source type.
Throws:
  `SemanticException` - if the `source` is not one of the above.

### getURI

public String getURI()
Returns the image URI if the image source type is `IMAGE_REF_TYPE_URL` or `IMAGE_REF_TYPE_FILE`.

Returns:
  the image URI if the image source type is `IMAGE_REF_TYPE_URL` or `IMAGE_REF_TYPE_FILE`. Otherwise, return `null`.

### getURL

public String getURL()
Returns the image URI if the image source type is `IMAGE_REF_TYPE_URL` or `IMAGE_REF_TYPE_FILE`.

Overrides:
  `getURL` in class `ReportItemHandleImpl`
Returns:
  the image URI if the image source type is `IMAGE_REF_TYPE_URL` , Otherwise, return `null`.

### getFile

public String getFile()
Returns the image URI if the image source type is `IMAGE_REF_TYPE_URL` or `IMAGE_REF_TYPE_FILE`.

Returns:
  the image URI if the image source type is `IMAGE_REF_TYPE_FILE`. Otherwise, return `null`.

### getTypeExpression

public String getTypeExpression()
Returns the type expression of the image item if the image source type is `IMAGE_REF_TYPE_EXPR`.

Returns:
  the type expression, if the image source type is `IMAGE_REF_TYPE_EXPR`. Otherwise, return `null`.

### getValueExpression

public String getValueExpression()
Returns the value expression of the image if the image source type is `IMAGE_REF_TYPE_EXPR`.

Returns:
  the value expression, if the image source type is `IMAGE_REF_TYPE_EXPR`. Otherwise, return `null`.

### getImageName

public String getImageName()
Returns the embedded image name that this image refers, if the image source type is `IMAGE_REF_TYPE_EMBED`. This is not the same as `DesignElementHandle.getName()`of this image item.

Returns:
  the embedded image name, if the image source type is `IMAGE_REF_TYPE_EMBED`. Otherwise, return `null`.

### getEmbeddedImage

public EmbeddedImageHandle getEmbeddedImage()
Returns the embedded image handle that this image refers, if the image source type is `IMAGE_REF_TYPE_EMBED`.

Returns:
  the embedded image handle, if the image source type is `IMAGE_REF_TYPE_EMBED` and the referred embedded image is found. Otherwise, return `null`.

### setImageName

public void setImageName(String name) throws SemanticException
Sets the embedded image name that this image refers, if the image source type is `IMAGE_REF_TYPE_EMBED`. The reference type is automatically set in this method. This is not the same as `DesignElementHandle.setName(String)`.

Parameters:
  `name` - the embedded image name
Throws:
  `SemanticException` - if the property is locked.

### setURL

public void setURL(String url) throws SemanticException
Sets the image uri property. The source type is `IMAGE_REF_TYPE_URL`, and will automatically set in this method.

Overrides:
  `setURL` in class `ReportItemHandleImpl`
Parameters:
  `url` - the url to be set.
Throws:
  `SemanticException` - if the property is locked.

### setURI

@Deprecated public void setURI(String uri) throws SemanticException
Deprecated.
should use `setFile(String)` or `setURL(String)`.
Sets the image uri property. The source type is `IMAGE_REF_TYPE_URL`, and will automatically set in this method.

Parameters:
  `uri` - the uri to be set.
Throws:
  `SemanticException` - if the property is locked.

### setFile

public void setFile(String file) throws SemanticException
Sets the image uri property. The source type is `IMAGE_REF_TYPE_FILE`, and will automatically set in this method.

Parameters:
  `file` - the file to be set.
Throws:
  `SemanticException` - if the property is locked.

### setScale

public void setScale(double scale) throws SemanticException
Sets the image scale property. The scale factor for the image given as a percentage. The default is 100%.

Parameters:
  `scale` - the scale value to be set.
Throws:
  `SemanticException` - if the property is locked.

### setSize

public void setSize(String size) throws SemanticException
Sets the image size property. The input value is one of the followings defined in `DesignChoiceConstants`:

- `IMAGE_SIZE_SIZE_TO_IMAGE`
- `IMAGE_SIZE_SCALE_TO_ITEM`
- `IMAGE_SIZE_CLIP`

Parameters:
  `size` - the size value to be set.
Throws:
  `SemanticException` - if the input size is not one of the above, or if the property is locked.

### setTypeExpression

public void setTypeExpression(String value) throws SemanticException
Sets the type expression value. The source type is automatically set to `IMAGE_REF_TYPE_EXPR`.

Parameters:
  `value` - the type expression value.
Throws:
  `SemanticException` - if the property is locked.

### setValueExpression

public void setValueExpression(String value) throws SemanticException
Sets the value expression value. The source type is automatically set to `IMAGE_REF_TYPE_EXPR`.

Parameters:
  `value` - the value expression.
Throws:
  `SemanticException` - if the property is locked.

### getActionHandle

public ActionHandle getActionHandle()
Returns a handle to work with the action property, action is a structure that defines a hyperlink.

Returns:
  a handle to the action property, return `null` if the action has not been set on the image.
See Also:
  - `ActionHandle`

### setAction

public ActionHandle setAction(Action action) throws SemanticException
Set an action on the image.

Parameters:
  `action` - new action to be set on the image, it represents a bookmark link, hyper-link, and drill through etc.
Returns:
  a handle to the action property, return `null` if the action has not been set on the image.
Throws:
  `SemanticException` - if member of the action is not valid.

### actionsIterator

public Iterator<ActionHandle> actionsIterator()
Returns the iterator for action defined on this image item.

Returns:
  the iterator for `Action` structure list defined on this image item

### getHelpText

public String getHelpText()
Returns the help text of this image item.

Returns:
  the help text

### setHelpText

public void setHelpText(String helpText) throws SemanticException
Sets the help text of this image item.

Parameters:
  `helpText` - the help text
Throws:
  `SemanticException` - if the property is locked.

### getHelpTextKey

public String getHelpTextKey()
Returns the resource key of the help text of this image item.

Returns:
  the resource key of the help text

### setHelpTextKey

public void setHelpTextKey(String helpTextKey) throws SemanticException
Sets the resource key of help text of this image item.

Parameters:
  `helpTextKey` - the help text
Throws:
  `SemanticException` - if the property is locked.

### fitToContainer

public boolean fitToContainer()
Gets the fit to container property value of this image item.

Returns:
  the fit to container of this image item.

### setFitToContainer

public void setFitToContainer(boolean fitToContainer) throws SemanticException
Sets the fit to container property value of this image item.

Parameters:
  `fitToContainer` - the value of fit to container.
Throws:
  `SemanticException` - if the property is locked.

### setURL

public void setURL(Expression expr) throws SemanticException
Sets the image uri property by an expression. The source type is `IMAGE_REF_TYPE_URL`, and will automatically set in this method.

Parameters:
  `expr` - the expression to be set.
Throws:
  `SemanticException` - if the property is locked.

### setFile

public void setFile(Expression expr) throws SemanticException
Sets the image uri property by an expression. The source type is `IMAGE_REF_TYPE_FILE`, and will automatically set in this method.

Parameters:
  `expr` - the expression to be set.
Throws:
  `SemanticException` - if the property is locked.

### isProportionalScale

public boolean isProportionalScale()
Gets the flag which indicates whether the image scales proportionally or not.

Returns:
  true if the image scale proportionally, othewise false

### setProportionalScale

public void setProportionalScale(boolean proportionalScale) throws SemanticException
Sets the flag which indicates whether the image scales proportionally or not.

Parameters:
  `proportionalScale` - the new flag to set
Throws:
  `SemanticException`