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".

     7 //

     8 // Initial Contributors:

     9 // Nokia Corporation - initial contribution.

    10 //

    11 // Contributors:

    12 //

    13 // Description:

    14 // Interface for Render Stage Text Cursors

    15 // 

    16 //

    17 

    18 /**

    19  @publishedPartner

    20  @prototype

    21 */

    22 

    23 #ifndef WSCURSOR_H

    24 #define WSCURSOR_H

    25 

    26 #include <w32std.h>

    27 #include <graphics/wsgraphicdrawerinterface.h>

    28 

    29 /** Wserv access to render stage Text Cursor implementation.

    30 

    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

    34 

    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.

    39 

    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.

    43 

    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.

    49 

    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.

    53 

    54 This interface allows a render stage to implement Text Cursors

    55 appropriately given the Display Render Stage which is present.

    56 

    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.

    61 

    62 Suggested strategies:

    63 <ol>

    64 <li>

    65 XOR drawing is available.  Just XOR draw the cursor each time in

    66 the supplied color.  This corresponds to legacy non-Render Stage

    67 behaviour.

    68 </li>

    69 <li>

    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.

    74 </li>

    75 </ol>

    76 

    77 @publishedPartner

    78 @prototype

    79 */

    80 class MWsTextCursor : public MWsObjectProvider

    81 	{

    82 public:

    83 

    84 	struct TTextCursorInfo

    85 		{

    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 */

    91 

    92 		TTextCursorInfo(const TRect& aCursorRect, const TRegion& aRegion,

    93 				TInt aTextCursorType, MWsWindow* aWindow, TRgb aTextCursorColor)

    94 		: iCursorRect(aCursorRect),

    95 		iRegion(aRegion),

    96 		iTextCursorType(aTextCursorType),

    97 		iWindow(aWindow),

    98 		iTextCursorColor(aTextCursorColor)

    99 			{

   100 			}

   101 		};

   102 public:

   103 	DECLARE_WS_TYPE_ID(KMWsTextCursor)

   104 

   105 public:

   106 	/** Draw the Text Cursor in its Flash ON state

   107 	 * 

   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.

   111 	 * 

   112 	 * @pre     The supplied Text Cursor type is either TextCursor::ETypeRectangle or

   113 	 * 			TTextCursor::ETypeHollowRectangle

   114 	 * 

   115 	 * @param	aTextCursorInfo  Data structure to describe the attributes of the Text

   116 	 * 			Cursor to Draw

   117 	 */

   118 	virtual void DrawTextCursor(const TTextCursorInfo& aTextCursorInfo) = 0;

   119 	};

   120 

   121 #endif // WSCURSOR_H