// Copyright (c) 2008-2009 Nokia Corporation and/or its subsidiary(-ies).
// All rights reserved.
// This component and the accompanying materials are made available
// under the terms of "Eclipse Public License v1.0"
// which accompanies this distribution, and is available
// at the URL "http://www.eclipse.org/legal/epl-v10.html".
//
// Initial Contributors:
// Nokia Corporation - initial contribution.
//
// Contributors:
//
// Description:
// Interface for Render Stage Text Cursors
// 
//

/**
 @publishedPartner
 @prototype
*/

#ifndef WSCURSOR_H
#define WSCURSOR_H

#include <w32std.h>
#include <graphics/wsgraphicdrawerinterface.h>

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

This interface allows delegation of Text Cursor drawing to the Render
Stage.  It must not to be confused with Custom Text Cursor drawing;
@see RWsSession::SetCustomTextCursor

Historically, Text cursors have often been implemented using XOR
drawing, because it is a cheap way to deliver a high-contrast cursor
in certain system architectures where Operating System access to
Graphics Device Memory is possible.

XOR drawing can be problematic for some Render Stages.  This is because
the XOR operation requires a read back followed by a write.  This would
stall a graphics accelerator hardware implementation.

In a render stage setting, the Text Cursor may not be the top-most
window as a transition effect can slide a semi-transparent window over
the top of the Text Cursor window.  This means the cursor cannot be XOR
drawn last after all other windows; the read-back cost cannot be hidden
at the end of drawing each frame.

The Display Render Stage, responsible for interacting with hardware,
can offer XOR drawing in some cases, for example Software Bit GDI,
and not in others, for example OpenVG back-end hardware.

This interface allows a render stage to implement Text Cursors
appropriately given the Display Render Stage which is present.

This interface uses the supplied Text Cursor Color as a hint only.
TextCursor colors are better regarded as constrast level indicators
where KRgbWhite means a high contrast text cursor, and KRgbBlack
means an invisible text cursor.

Suggested strategies:
<ol>
<li>
XOR drawing is available.  Just XOR draw the cursor each time in
the supplied color.  This corresponds to legacy non-Render Stage
behaviour.
</li>
<li>
No XOR drawing is available.  Draw a black box (solid or hollow
as appropriate).  Ensure that the UI Toolkit which provides the
platform's default text entry control has a compatible theme so
that black is an appropriate high-contrast color.
</li>
</ol>

@publishedPartner
@prototype
*/
class MWsTextCursor : public MWsObjectProvider
	{
public:

	struct TTextCursorInfo
		{
		const TRect& iCursorRect;	/** Rectangular area of the cursor in <b>window</b> co-ordinates */
		const TRegion& iRegion; 	/** Clipping region */
		TInt iTextCursorType; 		/** Cursor type; either TTextCursor::ETypeRectangle or TTextCursor::ETypeHollowRectangle */
		MWsWindow* iWindow; 		/** Window owning the cursor */
		TRgb iTextCursorColor;		/** Text Cursor Color used as a hint */

		TTextCursorInfo(const TRect& aCursorRect, const TRegion& aRegion,
				TInt aTextCursorType, MWsWindow* aWindow, TRgb aTextCursorColor)
		: iCursorRect(aCursorRect),
		iRegion(aRegion),
		iTextCursorType(aTextCursorType),
		iWindow(aWindow),
		iTextCursorColor(aTextCursorColor)
			{
			}
		};
public:
	DECLARE_WS_TYPE_ID(KMWsTextCursor)

public:
	/** Draw the Text Cursor in its Flash ON state
	 * 
	 * Draw the text cursor with the supplied attributes.  Note, the Flash OFF
	 * state does not result in a call to this function; instead a window
	 * redraw is done for the area where the cursor would reside.
	 * 
	 * @pre     The supplied Text Cursor type is either TextCursor::ETypeRectangle or
	 * 			TTextCursor::ETypeHollowRectangle
	 * 
	 * @param	aTextCursorInfo  Data structure to describe the attributes of the Text
	 * 			Cursor to Draw
	 */
	virtual void DrawTextCursor(const TTextCursorInfo& aTextCursorInfo) = 0;
	};

#endif // WSCURSOR_H