1 // Copyright (c) 2008-2009 Nokia Corporation and/or its subsidiary(-ies).
2 // All rights reserved.
3 // This component and the accompanying materials are made available
4 // under the terms of "Eclipse Public License v1.0"
5 // which accompanies this distribution, and is available
6 // at the URL "http://www.eclipse.org/legal/epl-v10.html".
8 // Initial Contributors:
9 // Nokia Corporation - initial contribution.
14 // Interface for Render Stage Text Cursors
27 #include <graphics/wsgraphicdrawerinterface.h>
29 /** Wserv access to render stage Text Cursor implementation.
31 This interface allows delegation of Text Cursor drawing to the Render
32 Stage. It must not to be confused with Custom Text Cursor drawing;
33 @see RWsSession::SetCustomTextCursor
35 Historically, Text cursors have often been implemented using XOR
36 drawing, because it is a cheap way to deliver a high-contrast cursor
37 in certain system architectures where Operating System access to
38 Graphics Device Memory is possible.
40 XOR drawing can be problematic for some Render Stages. This is because
41 the XOR operation requires a read back followed by a write. This would
42 stall a graphics accelerator hardware implementation.
44 In a render stage setting, the Text Cursor may not be the top-most
45 window as a transition effect can slide a semi-transparent window over
46 the top of the Text Cursor window. This means the cursor cannot be XOR
47 drawn last after all other windows; the read-back cost cannot be hidden
48 at the end of drawing each frame.
50 The Display Render Stage, responsible for interacting with hardware,
51 can offer XOR drawing in some cases, for example Software Bit GDI,
52 and not in others, for example OpenVG back-end hardware.
54 This interface allows a render stage to implement Text Cursors
55 appropriately given the Display Render Stage which is present.
57 This interface uses the supplied Text Cursor Color as a hint only.
58 TextCursor colors are better regarded as constrast level indicators
59 where KRgbWhite means a high contrast text cursor, and KRgbBlack
60 means an invisible text cursor.
65 XOR drawing is available. Just XOR draw the cursor each time in
66 the supplied color. This corresponds to legacy non-Render Stage
70 No XOR drawing is available. Draw a black box (solid or hollow
71 as appropriate). Ensure that the UI Toolkit which provides the
72 platform's default text entry control has a compatible theme so
73 that black is an appropriate high-contrast color.
80 class MWsTextCursor : public MWsObjectProvider
84 struct TTextCursorInfo
86 const TRect& iCursorRect; /** Rectangular area of the cursor in <b>window</b> co-ordinates */
87 const TRegion& iRegion; /** Clipping region */
88 TInt iTextCursorType; /** Cursor type; either TTextCursor::ETypeRectangle or TTextCursor::ETypeHollowRectangle */
89 MWsWindow* iWindow; /** Window owning the cursor */
90 TRgb iTextCursorColor; /** Text Cursor Color used as a hint */
92 TTextCursorInfo(const TRect& aCursorRect, const TRegion& aRegion,
93 TInt aTextCursorType, MWsWindow* aWindow, TRgb aTextCursorColor)
94 : iCursorRect(aCursorRect),
96 iTextCursorType(aTextCursorType),
98 iTextCursorColor(aTextCursorColor)
103 DECLARE_WS_TYPE_ID(KMWsTextCursor)
106 /** Draw the Text Cursor in its Flash ON state
108 * Draw the text cursor with the supplied attributes. Note, the Flash OFF
109 * state does not result in a call to this function; instead a window
110 * redraw is done for the area where the cursor would reside.
112 * @pre The supplied Text Cursor type is either TextCursor::ETypeRectangle or
113 * TTextCursor::ETypeHollowRectangle
115 * @param aTextCursorInfo Data structure to describe the attributes of the Text
118 virtual void DrawTextCursor(const TTextCursorInfo& aTextCursorInfo) = 0;