--- a/Symbian3/SDK/Source/GUID-0AD34BA6-D0C5-5AD7-B8E1-F737BB5FC0AC.dita Wed Mar 31 11:11:55 2010 +0100
+++ b/Symbian3/SDK/Source/GUID-0AD34BA6-D0C5-5AD7-B8E1-F737BB5FC0AC.dita Fri Jun 11 12:39:03 2010 +0100
@@ -1,111 +1,111 @@
-<?xml version="1.0" encoding="utf-8"?>
-<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->
-<!-- This component and the accompanying materials are made available under the terms of the License
-"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:
--->
-<!DOCTYPE concept
- PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
-<concept id="GUID-0AD34BA6-D0C5-5AD7-B8E1-F737BB5FC0AC" xml:lang="en"><title>Redraw
-Stores</title><shortdesc>Redraw stores store the sequence of drawing commands representing
-window contents. Whenever possible, the Window Server performs server-initiated
-redraws by repeating the sequence of stored commands, rather than by sending
-redraw requests to the client. This minimises the number of client-server
-transactions and means that redraws are done as soon as the server detects
-that they are needed. This topic explains some of the background to redraw
-stores. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>
-<p> <b>Variant</b>: Both (ScreenPlay and non-ScreenPlay). <b>Target audience</b>:
-Device creators. </p>
-<p>The classes involved with redraw stores are as follows: </p>
-<fig id="GUID-85C23EC3-BADE-5DE1-872D-0D8399209874">
-<title> Redraw stores class diagram </title>
-<image href="GUID-40437D9A-7503-5087-851A-D1269F0AF9A9_d0e201481_href.png" placement="inline"/>
-</fig>
-<p> <xref href="GUID-FF963788-695A-320F-9E81-76E45B0287D1.dita"><apiname>CWsRedrawMsgWindow</apiname></xref> is the class representing a redraw
-store. Draw commands are stored in a number of segments, stored in the nested
-class <xref href="GUID-53F68722-1A1D-30D8-960E-226843AB56E1.dita"><apiname>CRedrawSegment</apiname></xref>. </p>
-<p>Redraw drawing takes place as follows: </p>
-<ol id="GUID-2C26C7D9-1C38-55E1-BF14-A36A9F9F05F3">
-<li id="GUID-2FCE8CBF-6BF3-5033-8BB7-935D0B276F7C"><p>A call to <xref href="GUID-683603DD-F3D3-3193-BEB3-8236C7DE7F79.dita#GUID-683603DD-F3D3-3193-BEB3-8236C7DE7F79/GUID-28202F81-52FE-30F5-8B8C-ABED0915822E"><apiname>RWindow::Invalidate()</apiname></xref> causes
-either the whole window, or a rectangle within it, to be marked as invalid. </p> </li>
-<li id="GUID-EB4CAD7F-1B3C-5D2A-85FD-31D0C7F9503D"><p>Next, a call to <xref href="GUID-683603DD-F3D3-3193-BEB3-8236C7DE7F79.dita#GUID-683603DD-F3D3-3193-BEB3-8236C7DE7F79/GUID-9337538E-7A53-3153-A330-968B5E4F2FF2"><apiname>RWindow::BeginRedraw()</apiname></xref> is
-made, either for the whole window or for a rectangle within it. </p> </li>
-<li id="GUID-88AF657A-8C5E-5CE8-BEF9-F8C1E34F6174"><p>Draw operations take
-place. </p> </li>
-<li id="GUID-58BC4A48-5035-582D-BE17-C15A885F4B5F"><p>Finally there is a call
-to <xref href="GUID-683603DD-F3D3-3193-BEB3-8236C7DE7F79.dita#GUID-683603DD-F3D3-3193-BEB3-8236C7DE7F79/GUID-3DE16607-AD3B-3946-BEB3-88512EAAB9CE"><apiname>RWindow::EndRedraw()</apiname></xref>. </p> </li>
-</ol>
-<p>In this sequence, the draw operations within the <codeph>BeginRedraw()</codeph> and <codeph>EndRedraw()</codeph> brackets
-are interpreted as <i>replacing</i> whatever drawing was previously present
-in the affected rectangle. </p>
-<p>It is important to bracket all drawing within <codeph>BeginRedraw(TRect)</codeph> and <codeph>EndRedraw(TRect)</codeph> calls.
-In ScreenPlay, the Window Server ignores all drawing not within <codeph>BeginRedraw()</codeph> and <codeph>EndRedraw()</codeph> brackets
-and triggers a full-window redraw. In debug builds, there is an option to
-panic clients violating this convention. </p>
-<p>For more information, see <xref href="GUID-8DB1C618-597C-560C-95A2-C0AB2CEBB027.dita">Redraw
-Drawing</xref>. </p>
-<section id="GUID-27FE041D-3DE3-4290-AF6D-38DDB8970008"><title>Redraw segments and non-redraw handling</title> <p>When the
-Window Server receives a batch of redraw drawing, everything between a BeginRedraw/EndRedraw
-bracket is stored in a single <b>redraw segment</b>. The segment is marked
-as <codeph>ESegmentTypePendingRedraw</codeph> while it is being received,
-and <codeph>ESegmentTypeRedraw</codeph> once it is complete. </p> <p>Redraw
-segments have a region to which they apply. For <codeph>ESegmentTypeRedraw</codeph>,
-the region is initially set to be the rectangle passed into the <codeph>BeginRedraw()</codeph> call.
-When a new<codeph>ESegmentTypeRedraw</codeph> is created, its region is subtracted
-from the regions of all existing segments. This reflects the fact that redraw
-drawing <i>replaces</i> existing drawing. If, as a consequence of new redraw
-drawing, the region of an existing segment becomes empty, that segment is
-discarded. Its drawing has been replaced everywhere, so it is no longer needed. </p> <p>What
-happens to drawing that is received between an <codeph>EndRedraw</codeph> and
-the next <codeph>BeginRedraw</codeph> —and which is therefore <b>non-redraw
-drawing</b> —depends on which variant is in use: </p> <ul>
-<li id="GUID-0B29AC2F-AD48-5EAB-B3BE-B8FC296B092A"><p>In ScreenPlay, non-redraw
-drawing is not stored in a segment but instead triggers the Window Server
-to invalidate the entire window. This means that the client application must
-then perform a full window redraw. </p> </li>
-<li id="GUID-B592A6D0-68B7-5A16-B179-9F78C5FCDBB3"><p>In the non-ScreenPlay
-variant, non-redraw drawing is stored in a segment marked as <codeph>ESegmentTypeNonRedraw</codeph>.
-For these segments the region is initially set to be the whole window and
-does not affect the regions of existing segments, because non-redraw drawing
-is drawn over existing drawing. </p> </li>
-</ul> </section>
-<section id="GUID-DB24B91E-6628-4B6E-AE9A-ACAB30AA02C3"><title> Redraw store playback</title> <p>When playback is required,
-the redraw store goes through the redraw segments and replays them if the
-region for the segment intersects the region that is to be redrawn. It follows
-from the way that they are managed that the regions of redraw segments are
-mutually disjoint. This means that in ScreenPlay they can be replayed in any
-order. This is also true in the non-ScreenPlay when there are only redraw
-segments present. </p> <p>In the non-ScreenPlay variant, any non-redraw segments
-are replayed in earliest-first order, because they draw on top of earlier
-drawing. </p> </section>
-<section id="GUID-74EC09C2-BB39-42B2-B765-191A7E17A4D6"><title> Aging of non-redraw segments</title> <p> <b>Variant</b>:
-Non-ScreenPlay only. </p> <p>Non-redraw segments can cause inefficient operation
-of redraw stores. For this reason, in the non-ScreenPlay variant where non-redraw
-segments are still used, the Window Server "ages" them. That is, non-redraw
-segments are considered to have a finite lifetime, after which they are discarded.
-When a non-redraw segment is discarded, the Window Server makes a redraw request
-to the client asking it to provide new draw operations for the invalid region. </p> <p>The
-lifetime for non-redraw segments is set in the <xref href="GUID-1D529BDC-6665-58E2-AB3F-7023D8A84F69.dita">WSINI.INI
-file</xref> using the parameter <codeph>NONREDRAWAGELIMIT</codeph>, followed
-by a duration in microseconds. If this line is not present in the <codeph>WSINI.INI</codeph>,
-a default of one second is used. </p> </section>
-<section id="GUID-8CE71B67-21F3-4D16-9A1A-70A70A24EFD3"><title>Atomic Redraws</title> <p> <b>Variant</b>: Both (ScreenPlay
-and non-ScreenPlay). </p> <p>Another <xref href="GUID-1D529BDC-6665-58E2-AB3F-7023D8A84F69.dita">WSINI.INI
-file</xref> setting that affects redraw storing is <codeph>ATOMICREDRAWS</codeph>.
-If this parameter is present, new draw operations received after a <codeph>BeginRedraw()</codeph> are
-not considered valid until the corresponding <codeph>EndRedraw()</codeph> is
-received. In particular, a new segment does not replace existing segments
-until it is complete. This has the consequence that if redraw store playback
-is required before the <codeph>EndRedraw()</codeph> for a new segment is received,
-draw operations from old segments for that region are used instead. Thus drawing
-within <codeph>Begin/EndRedraw</codeph> brackets can be considered as an atomic
-operation. This eliminates one potential source of flicker. </p> </section>
-</conbody><related-links>
-<link href="GUID-484B51EC-2209-5492-8E9C-9D792AB0DF35.dita"><linktext>Graphics
-and Drawing </linktext></link>
-<link href="GUID-1D529BDC-6665-58E2-AB3F-7023D8A84F69.dita"><linktext>The wsini.ini
-File Reference</linktext></link>
+<?xml version="1.0" encoding="utf-8"?>
+<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->
+<!-- This component and the accompanying materials are made available under the terms of the License
+"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:
+-->
+<!DOCTYPE concept
+ PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
+<concept id="GUID-0AD34BA6-D0C5-5AD7-B8E1-F737BB5FC0AC" xml:lang="en"><title>Redraw
+Stores</title><shortdesc>Redraw stores store the sequence of drawing commands representing
+window contents. Whenever possible, the Window Server performs server-initiated
+redraws by repeating the sequence of stored commands, rather than by sending
+redraw requests to the client. This minimises the number of client-server
+transactions and means that redraws are done as soon as the server detects
+that they are needed. This topic explains some of the background to redraw
+stores. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>
+<p> <b>Variant</b>: Both (ScreenPlay and non-ScreenPlay). <b>Target audience</b>:
+Device creators. </p>
+<p>The classes involved with redraw stores are as follows: </p>
+<fig id="GUID-85C23EC3-BADE-5DE1-872D-0D8399209874">
+<title> Redraw stores class diagram </title>
+<image href="GUID-40437D9A-7503-5087-851A-D1269F0AF9A9_d0e196473_href.png" placement="inline"/>
+</fig>
+<p> <xref href="GUID-FF963788-695A-320F-9E81-76E45B0287D1.dita"><apiname>CWsRedrawMsgWindow</apiname></xref> is the class representing a redraw
+store. Draw commands are stored in a number of segments, stored in the nested
+class <xref href="GUID-53F68722-1A1D-30D8-960E-226843AB56E1.dita"><apiname>CRedrawSegment</apiname></xref>. </p>
+<p>Redraw drawing takes place as follows: </p>
+<ol id="GUID-2C26C7D9-1C38-55E1-BF14-A36A9F9F05F3">
+<li id="GUID-2FCE8CBF-6BF3-5033-8BB7-935D0B276F7C"><p>A call to <xref href="GUID-683603DD-F3D3-3193-BEB3-8236C7DE7F79.dita#GUID-683603DD-F3D3-3193-BEB3-8236C7DE7F79/GUID-28202F81-52FE-30F5-8B8C-ABED0915822E"><apiname>RWindow::Invalidate()</apiname></xref> causes
+either the whole window, or a rectangle within it, to be marked as invalid. </p> </li>
+<li id="GUID-EB4CAD7F-1B3C-5D2A-85FD-31D0C7F9503D"><p>Next, a call to <xref href="GUID-683603DD-F3D3-3193-BEB3-8236C7DE7F79.dita#GUID-683603DD-F3D3-3193-BEB3-8236C7DE7F79/GUID-9337538E-7A53-3153-A330-968B5E4F2FF2"><apiname>RWindow::BeginRedraw()</apiname></xref> is
+made, either for the whole window or for a rectangle within it. </p> </li>
+<li id="GUID-88AF657A-8C5E-5CE8-BEF9-F8C1E34F6174"><p>Draw operations take
+place. </p> </li>
+<li id="GUID-58BC4A48-5035-582D-BE17-C15A885F4B5F"><p>Finally there is a call
+to <xref href="GUID-683603DD-F3D3-3193-BEB3-8236C7DE7F79.dita#GUID-683603DD-F3D3-3193-BEB3-8236C7DE7F79/GUID-3DE16607-AD3B-3946-BEB3-88512EAAB9CE"><apiname>RWindow::EndRedraw()</apiname></xref>. </p> </li>
+</ol>
+<p>In this sequence, the draw operations within the <codeph>BeginRedraw()</codeph> and <codeph>EndRedraw()</codeph> brackets
+are interpreted as <i>replacing</i> whatever drawing was previously present
+in the affected rectangle. </p>
+<p>It is important to bracket all drawing within <codeph>BeginRedraw(TRect)</codeph> and <codeph>EndRedraw(TRect)</codeph> calls.
+In ScreenPlay, the Window Server ignores all drawing not within <codeph>BeginRedraw()</codeph> and <codeph>EndRedraw()</codeph> brackets
+and triggers a full-window redraw. In debug builds, there is an option to
+panic clients violating this convention. </p>
+<p>For more information, see <xref href="GUID-8DB1C618-597C-560C-95A2-C0AB2CEBB027.dita">Redraw
+Drawing</xref>. </p>
+<section id="GUID-27FE041D-3DE3-4290-AF6D-38DDB8970008"><title>Redraw segments and non-redraw handling</title> <p>When the
+Window Server receives a batch of redraw drawing, everything between a BeginRedraw/EndRedraw
+bracket is stored in a single <b>redraw segment</b>. The segment is marked
+as <codeph>ESegmentTypePendingRedraw</codeph> while it is being received,
+and <codeph>ESegmentTypeRedraw</codeph> once it is complete. </p> <p>Redraw
+segments have a region to which they apply. For <codeph>ESegmentTypeRedraw</codeph>,
+the region is initially set to be the rectangle passed into the <codeph>BeginRedraw()</codeph> call.
+When a new<codeph>ESegmentTypeRedraw</codeph> is created, its region is subtracted
+from the regions of all existing segments. This reflects the fact that redraw
+drawing <i>replaces</i> existing drawing. If, as a consequence of new redraw
+drawing, the region of an existing segment becomes empty, that segment is
+discarded. Its drawing has been replaced everywhere, so it is no longer needed. </p> <p>What
+happens to drawing that is received between an <codeph>EndRedraw</codeph> and
+the next <codeph>BeginRedraw</codeph> —and which is therefore <b>non-redraw
+drawing</b> —depends on which variant is in use: </p> <ul>
+<li id="GUID-0B29AC2F-AD48-5EAB-B3BE-B8FC296B092A"><p>In ScreenPlay, non-redraw
+drawing is not stored in a segment but instead triggers the Window Server
+to invalidate the entire window. This means that the client application must
+then perform a full window redraw. </p> </li>
+<li id="GUID-B592A6D0-68B7-5A16-B179-9F78C5FCDBB3"><p>In the non-ScreenPlay
+variant, non-redraw drawing is stored in a segment marked as <codeph>ESegmentTypeNonRedraw</codeph>.
+For these segments the region is initially set to be the whole window and
+does not affect the regions of existing segments, because non-redraw drawing
+is drawn over existing drawing. </p> </li>
+</ul> </section>
+<section id="GUID-DB24B91E-6628-4B6E-AE9A-ACAB30AA02C3"><title> Redraw store playback</title> <p>When playback is required,
+the redraw store goes through the redraw segments and replays them if the
+region for the segment intersects the region that is to be redrawn. It follows
+from the way that they are managed that the regions of redraw segments are
+mutually disjoint. This means that in ScreenPlay they can be replayed in any
+order. This is also true in the non-ScreenPlay when there are only redraw
+segments present. </p> <p>In the non-ScreenPlay variant, any non-redraw segments
+are replayed in earliest-first order, because they draw on top of earlier
+drawing. </p> </section>
+<section id="GUID-74EC09C2-BB39-42B2-B765-191A7E17A4D6"><title> Aging of non-redraw segments</title> <p> <b>Variant</b>:
+Non-ScreenPlay only. </p> <p>Non-redraw segments can cause inefficient operation
+of redraw stores. For this reason, in the non-ScreenPlay variant where non-redraw
+segments are still used, the Window Server "ages" them. That is, non-redraw
+segments are considered to have a finite lifetime, after which they are discarded.
+When a non-redraw segment is discarded, the Window Server makes a redraw request
+to the client asking it to provide new draw operations for the invalid region. </p> <p>The
+lifetime for non-redraw segments is set in the <xref href="GUID-1D529BDC-6665-58E2-AB3F-7023D8A84F69.dita">WSINI.INI
+file</xref> using the parameter <codeph>NONREDRAWAGELIMIT</codeph>, followed
+by a duration in microseconds. If this line is not present in the <codeph>WSINI.INI</codeph>,
+a default of one second is used. </p> </section>
+<section id="GUID-8CE71B67-21F3-4D16-9A1A-70A70A24EFD3"><title>Atomic Redraws</title> <p> <b>Variant</b>: Both (ScreenPlay
+and non-ScreenPlay). </p> <p>Another <xref href="GUID-1D529BDC-6665-58E2-AB3F-7023D8A84F69.dita">WSINI.INI
+file</xref> setting that affects redraw storing is <codeph>ATOMICREDRAWS</codeph>.
+If this parameter is present, new draw operations received after a <codeph>BeginRedraw()</codeph> are
+not considered valid until the corresponding <codeph>EndRedraw()</codeph> is
+received. In particular, a new segment does not replace existing segments
+until it is complete. This has the consequence that if redraw store playback
+is required before the <codeph>EndRedraw()</codeph> for a new segment is received,
+draw operations from old segments for that region are used instead. Thus drawing
+within <codeph>Begin/EndRedraw</codeph> brackets can be considered as an atomic
+operation. This eliminates one potential source of flicker. </p> </section>
+</conbody><related-links>
+<link href="GUID-484B51EC-2209-5492-8E9C-9D792AB0DF35.dita"><linktext>Graphics
+and Drawing </linktext></link>
+<link href="GUID-1D529BDC-6665-58E2-AB3F-7023D8A84F69.dita"><linktext>The wsini.ini
+File Reference</linktext></link>
</related-links></concept>
\ No newline at end of file