| class MWsElement : public MWsObjectProvider |
This interface allows Image Sources to be associated with meta-data to define how the Image Source must be presented within a Scene.
For a conceptual overview of Scenes, refer to the MWsScene Interface.
Source rectangular region
Destination rectangular region
Rotation and flipping
Opacity
Relative z-order (ordinal position)
Tags to descriminate the UI from other Elements
Elements can be marked with flags. There are two different consumers of flags: Target Renderers and Render Stage Plug-ins.
Target Renderers are sub-systems which actually do composition and rendering on a particular display device or off-screen buffer. The EElementTransparencySource flag tells the Target Renderer that alpha blending must use the alpha channel in the Surface connected to the Element.
On the other hand, Render Stage Plug-ins need flags to implement specific policies such as "UI always on top". To facilitate this, Elements have a EElementIsIndirectlyRenderedUserInterface or a EElementIsDirectlyRenderedUserInterface optionally set. This flag allows Render Stage Plug-ins to keep the relative z-order of Elements aligned to this policy.
To allow compatible updates to be made to flags, all Render Stage Plug-ins must preserve the flags in Elements which they do not operate upon. Target Renderers may ignore the flags in Elements which they do not operate on.
Intial State
Fully opaque
No rotation, nor flipped
Not part of the Committed Scene
No connected Surface
All flags reset
Local error value set as KErrNone
Source Rectangle and Destination Rectangle is (0,0,0,0) Destination Clipping Rectangle is (0,0,0,0)
Source Rectangle is the extent of the Image Source
Destination Rectangle is set at origin (0,0), whose sized equals the Image Source size truncated the the target screen size.
Destination Clipping Rectangle is (0,0,0,0) to represent the entire area of the target screen.
Sometimes it is desirable to reset a Source, Destination, or Clipping Rectangle so that the actual value used matches the corresponding Source Image or Target Screen size. In such cases rectangle (0,0,0,0) is used to represent this.
Extending this interface
Creating optional extension interfaces with MWsElement::MWsObjectProvider::ResolveObjectInterface()
Defining new TElementFlags flag settings; Render Stage Plug-ins preserve the value of these across the Render Stage Pipeline.
This interface allows Elements to be modified in terms of their own flag settings, and rotation, as well as their relative position with other Elements. Queries return the pending values for such Elements. Any modifications are marked Pending, and affect the Scene according to the rules described by "Rendering" in MWsScene.
Order in which transformations are applied
SetSourceRectangle (Cropping)
SetSourceFlipping (Flipping)
SetSourceRotation (Rotation)
SetDestinationRectangle (Scaling and Positioning)
SetDestinationClippingRectangle (Scaling and Positioning)
SetGlobalAlpha (Blending)
| Public Member Functions | |
|---|---|
| TInt | ConnectSurface(const TSurfaceId &) |
| const TSurfaceId & | ConnectedSurface() |
| MWsElement * | ElementAbove() |
| MWsElement * | ElementBelow() |
| TInt | GetDestinationClippingRect(TRect &) |
| TInt | GetDestinationRectangle(TRect &) |
| void | GetRenderStageFlags(TUint32 &) |
| TInt | GetSourceRectangle(TRect &) |
| void | GetTargetRendererFlags(TUint32 &) |
| void | GlobalAlpha(TInt &) |
| TInt | SetDestinationClippingRect(const TRect &) |
| TInt | SetDestinationRectangle(const TRect &) |
| TInt | SetGlobalAlpha(const TInt) |
| TInt | SetRenderStageFlags(const TUint32 &) |
| TInt | SetSourceFlipping(const TBool) |
| TInt | SetSourceRectangle(const TRect &) |
| TInt | SetSourceRotation(const TElementRotation) |
| TInt | SetTargetRendererFlags(const TUint32 &) |
| TBool | SourceFlipping() |
| TElementRotation | SourceRotation() |
| Inherited Functions | |
|---|---|
| MWsObjectProvider::ObjectInterface() | |
| MWsObjectProvider::ObjectInterface()const | |
| MWsObjectProvider::ResolveObjectInterface(TUint) | |
| Public Member Enumerations | |
|---|---|
| enum | TElementRenderStageFlags { EElementRenderStageNone = 0, EElementIsIndirectlyRenderedUserInterface = (1 << 0), EElementIsDirectlyRenderedUserInterface = (1 << 1), EElementRenderStageReserved = (1 << 2) } |
| enum | TElementRotation { EElementAntiClockwise0 = 0, EElementAntiClockwise90 = 1, EElementAntiClockwise180 = 2, EElementAntiClockwise270 = 3 } |
| enum | TElementTargetRendererFlags { EElementTransparencyNone = 0, EElementTransparencyGlobalAlpha = (1 << 0), EElementTransparencySource = (1 << 1), EElementTargetRendererReserved = (1 << 2) } |
| TInt | ConnectSurface | ( | const TSurfaceId & | aSurface | ) | [pure virtual] |
Connect the given Surface to this Element, or re-Connect a new Surface to this Element which already has a connected Surface. The Element does not need to be in the Scene when this call is made.
The Source Rectangle of the Element is updated to correspond to match the Source Rectangle of the Surface. Thus any prior Source Rectangle setting will be overwritten.
| const TSurfaceId & aSurface | Surface to connect to. If this is the Null Surface, then the Source Rectangle of the Element is set to (0,0,0,0). |
| MWsElement * | ElementAbove | ( | ) | [pure virtual] |
Get the Element which is above this Element in the Pending Scene. If the Element is the top-most element, NULL is returned. If the Element is not in the Scene, NULL is returned.
| MWsElement * | ElementBelow | ( | ) | [pure virtual] |
Get the Element which is below this Element in the Pending Scene. If the Element is the bottom-most element, NULL is returned. If the Element is not in the Scene, NULL is returned.
| TInt | GetDestinationClippingRect | ( | TRect & | aDestClipRect | ) | const [pure virtual] |
Get the clipping area which limits where in the target screen the element may appear.
| TRect & aDestClipRect | The clipping rectangle is updated with the current clipping area used in the target screen. |
| TInt | GetDestinationRectangle | ( | TRect & | aDest | ) | const [pure virtual] |
Get the target area where the Image Source would appear. The default value is at (0,0) sized to the Image Source clipped to the size of the target.
| TRect & aDest | The destination rectangle is updated with the current region used in the target screen. |
| void | GetRenderStageFlags | ( | TUint32 & | aRenderStageFlags | ) | const [pure virtual] |
Get the Render Stage flags associated with this Element.
Flags which are not recognised by an implementation must be kept to allow the interface to be extended in a compatible manner.
| TUint32 & aRenderStageFlags | Variable to receive TElementRenderStageFlags |
| TInt | GetSourceRectangle | ( | TRect & | aSrc | ) | [pure virtual] |
Get the portion of the connected Image Source being used. The default value is the entire extent of the connected Image Source.
| TRect & aSrc | The source rectangle is updated with the current rectangular region being used within the Image Source. |
| void | GetTargetRendererFlags | ( | TUint32 & | aTargetRendererFlags | ) | const [pure virtual] |
Get the Target Renderer flags associated with this Element.
Flags which are not recognised by an implementation must be kept to allow the interface to be extended in a compatible manner.
| TUint32 & aTargetRendererFlags | Variable to receive TElementTargetRendererFlags |
| void | GlobalAlpha | ( | TInt & | aAlpha | ) | const [pure virtual] |
Gets the Global Alpha Transparency value for this Element. Elements are by default fully opaque, represented by opacity 255.
| TInt & aAlpha | Variable which receives the Global Alpha Transparency value. |
| TInt | SetDestinationClippingRect | ( | const TRect & | aDestClipRect | ) | [pure virtual] |
Set clipping area where the Image Source would appear. The default value is the area of the target screen.
| const TRect & aDestClipRect | The clipping rectangle in the target. (0,0,0,0) means the entire size of the Target Screen. |
| TInt | SetDestinationRectangle | ( | const TRect & | aDest | ) | [pure virtual] |
Set the target area in the target screen (or off-screen buffer) where the Image Source should appear. Scaling may result if the source and destination rectangles differ. A platform specific algorithm will be used to interpolate the scaled image.
| const TRect & aDest | The destination rectangle in the target. |
| TInt | SetGlobalAlpha | ( | const TInt | aAlpha | ) | [pure virtual] |
Sets the Global Alpha Transparency value for this Element. Elements are by default fully opaque, represented by opacity 255. On platforms that support it, the Alpha Transparency value can be reduced down to 0 representing fully transparent. The purpose of this is to allow the fading in and fading out of Elements into the Scene.
This setting has no effect unless the flag Target Renderer flag EElementTransparencyGlobalAlpha is set;
Out of range values are clamped silently, and do not cause error conditions.
| const TInt aAlpha | The Alpha Transparency value desired. Values are clamped to be within the range [0, 255] where 0 represents fully transparent, and 255 represents fully opaque. |
| TInt | SetRenderStageFlags | ( | const TUint32 & | aRenderStageFlags | ) | [pure virtual] |
Set the Render Stage flags to be associated with this Element.
Flags which are not recognised by an implementation must be kept to allow the interface to be extended in a compatible manner.
| const TUint32 & aRenderStageFlags | Flags to set for Render Stage Plug-ins; |
| TInt | SetSourceFlipping | ( | const TBool | aFlip | ) | [pure virtual] |
Set the pending flipping setting for the connected Image Source. When flipped, the Image Source appears in the target as inverted about its horizontal centerline. This effect can be combined with rotation effects. By default, the Image Source is not flipped.
| const TBool aFlip | If ETrue, the connected Image is flipped, else it is not flipped. |
| TInt | SetSourceRectangle | ( | const TRect & | aSrc | ) | [pure virtual] |
Set which rectangular portion of the connected image source will be used when displaying this Element.
| const TRect & aSrc | The source rectangle of pixels from the connected Image Source. This rectangle must not include any pixels outside the Image Source. (0,0,0,0) means the entire size of the Image Source. |
| TInt | SetSourceRotation | ( | const TElementRotation | aElementRotation | ) | [pure virtual] |
Set the rotation which describes how the connected Image Source should be rotated to appear in the target.
| const TElementRotation aElementRotation | The amount of rotation in the target. |
| TInt | SetTargetRendererFlags | ( | const TUint32 & | aTargetRendererFlags | ) | [pure virtual] |
Set the Target Renderer flags to be associated with this Element.
Flags which are not recognised by an implementation must be kept to allow the interface to be extended in a compatible manner.
| const TUint32 & aTargetRendererFlags | Flags to set for Target Renderer; |
| TBool | SourceFlipping | ( | ) | const [pure virtual] |
Get the pending flipping setting for the connected Image Source. By default, the image is not flipped.
| TElementRotation | SourceRotation | ( | ) | const [pure virtual] |
Get the pending rotation setting for the connected Image Source. By default, the rotation is EElementAntiClockwise0 and this is returned if there is no connected Image Source.
| EElementRenderStageNone = 0 |
No flag value set for Render Stage Plug-in |
| EElementIsIndirectlyRenderedUserInterface = (1 << 0) |
Indirectly Rendered User Interface, i.e. rendering via MWsGraphicsContext calls originating from client CWindowGc commands |
| EElementIsDirectlyRenderedUserInterface = (1 << 1) |
Directly Render User Interface, i.e. rendering where Window Server does not see the graphics commands, as is the case for Direct Screen Access clients. |
| EElementRenderStageReserved = (1 << 2) |
Reserved values for future Render Stage Plug-in usage |
Amount of rotation of pixel data to apply to the Image Source to obtain the Target Image
| EElementAntiClockwise0 = 0 | |
| EElementAntiClockwise90 = 1 |
No rotation |
| EElementAntiClockwise180 = 2 |
90 Degrees Anti-clockwise in target |
| EElementAntiClockwise270 = 3 |
180 Degrees Anti-clockwise in target |
| EElementTransparencyNone = 0 |
Target renderer must treat the Element as Opaque. |
| EElementTransparencyGlobalAlpha = (1 << 0) |
Target renderer must use the Global Alpha Transparency value from the Element |
| EElementTransparencySource = (1 << 1) |
Target renderer must use the Alpha Transparency Channel from the Element |
| EElementTargetRendererReserved = (1 << 2) |
Reserved flag value; this must not be set. |
Copyright ©2010 Nokia Corporation and/or its subsidiary(-ies).
All rights
reserved. Unless otherwise stated, these materials are provided under the terms of the Eclipse Public License
v1.0.