sl@0: // Copyright (c) 2008-2009 Nokia Corporation and/or its subsidiary(-ies). sl@0: // All rights reserved. sl@0: // This component and the accompanying materials are made available sl@0: // under the terms of "Eclipse Public License v1.0" sl@0: // which accompanies this distribution, and is available sl@0: // at the URL "http://www.eclipse.org/legal/epl-v10.html". sl@0: // sl@0: // Initial Contributors: sl@0: // Nokia Corporation - initial contribution. sl@0: // sl@0: // Contributors: sl@0: // sl@0: // Description: sl@0: // Interface for Render Stage Text Cursors sl@0: // sl@0: // sl@0: sl@0: /** sl@0: @publishedPartner sl@0: @prototype sl@0: */ sl@0: sl@0: #ifndef WSCURSOR_H sl@0: #define WSCURSOR_H sl@0: sl@0: #include sl@0: #include sl@0: sl@0: /** Wserv access to render stage Text Cursor implementation. sl@0: sl@0: This interface allows delegation of Text Cursor drawing to the Render sl@0: Stage. It must not to be confused with Custom Text Cursor drawing; sl@0: @see RWsSession::SetCustomTextCursor sl@0: sl@0: Historically, Text cursors have often been implemented using XOR sl@0: drawing, because it is a cheap way to deliver a high-contrast cursor sl@0: in certain system architectures where Operating System access to sl@0: Graphics Device Memory is possible. sl@0: sl@0: XOR drawing can be problematic for some Render Stages. This is because sl@0: the XOR operation requires a read back followed by a write. This would sl@0: stall a graphics accelerator hardware implementation. sl@0: sl@0: In a render stage setting, the Text Cursor may not be the top-most sl@0: window as a transition effect can slide a semi-transparent window over sl@0: the top of the Text Cursor window. This means the cursor cannot be XOR sl@0: drawn last after all other windows; the read-back cost cannot be hidden sl@0: at the end of drawing each frame. sl@0: sl@0: The Display Render Stage, responsible for interacting with hardware, sl@0: can offer XOR drawing in some cases, for example Software Bit GDI, sl@0: and not in others, for example OpenVG back-end hardware. sl@0: sl@0: This interface allows a render stage to implement Text Cursors sl@0: appropriately given the Display Render Stage which is present. sl@0: sl@0: This interface uses the supplied Text Cursor Color as a hint only. sl@0: TextCursor colors are better regarded as constrast level indicators sl@0: where KRgbWhite means a high contrast text cursor, and KRgbBlack sl@0: means an invisible text cursor. sl@0: sl@0: Suggested strategies: sl@0:
    sl@0:
  1. sl@0: XOR drawing is available. Just XOR draw the cursor each time in sl@0: the supplied color. This corresponds to legacy non-Render Stage sl@0: behaviour. sl@0:
    2. sl@0:
  2. sl@0: No XOR drawing is available. Draw a black box (solid or hollow sl@0: as appropriate). Ensure that the UI Toolkit which provides the sl@0: platform's default text entry control has a compatible theme so sl@0: that black is an appropriate high-contrast color. sl@0:
    3. sl@0:
sl@0: sl@0: @publishedPartner sl@0: @prototype sl@0: */ sl@0: class MWsTextCursor : public MWsObjectProvider sl@0: { sl@0: public: sl@0: sl@0: struct TTextCursorInfo sl@0: { sl@0: const TRect& iCursorRect; /** Rectangular area of the cursor in window co-ordinates */ sl@0: const TRegion& iRegion; /** Clipping region */ sl@0: TInt iTextCursorType; /** Cursor type; either TTextCursor::ETypeRectangle or TTextCursor::ETypeHollowRectangle */ sl@0: MWsWindow* iWindow; /** Window owning the cursor */ sl@0: TRgb iTextCursorColor; /** Text Cursor Color used as a hint */ sl@0: sl@0: TTextCursorInfo(const TRect& aCursorRect, const TRegion& aRegion, sl@0: TInt aTextCursorType, MWsWindow* aWindow, TRgb aTextCursorColor) sl@0: : iCursorRect(aCursorRect), sl@0: iRegion(aRegion), sl@0: iTextCursorType(aTextCursorType), sl@0: iWindow(aWindow), sl@0: iTextCursorColor(aTextCursorColor) sl@0: { sl@0: } sl@0: }; sl@0: public: sl@0: DECLARE_WS_TYPE_ID(KMWsTextCursor) sl@0: sl@0: public: sl@0: /** Draw the Text Cursor in its Flash ON state sl@0: * sl@0: * Draw the text cursor with the supplied attributes. Note, the Flash OFF sl@0: * state does not result in a call to this function; instead a window sl@0: * redraw is done for the area where the cursor would reside. sl@0: * sl@0: * @pre The supplied Text Cursor type is either TextCursor::ETypeRectangle or sl@0: * TTextCursor::ETypeHollowRectangle sl@0: * sl@0: * @param aTextCursorInfo Data structure to describe the attributes of the Text sl@0: * Cursor to Draw sl@0: */ sl@0: virtual void DrawTextCursor(const TTextCursorInfo& aTextCursorInfo) = 0; sl@0: }; sl@0: sl@0: #endif // WSCURSOR_H