PageRenderTime 19ms CodeModel.GetById 7ms app.highlight 5ms RepoModel.GetById 1ms app.codeStats 0ms

/AvalonEdit/Documentation/Coordinate Systems.aml

http://github.com/icsharpcode/ILSpy
Unknown | 175 lines | 168 code | 7 blank | 0 comment | 0 complexity | f925988cae424149b0c1dfebdaf25c9c MD5 | raw file
  1<?xml version="1.0" encoding="utf-8"?>
  2<topic id="5b1854b4-884c-4713-b921-b28e96a1b43e" revisionNumber="1">
  3  <developerConceptualDocument xmlns="http://ddue.schemas.microsoft.com/authoring/2003/5" xmlns:xlink="http://www.w3.org/1999/xlink">
  4    <!--
  5  <summary>
  6    <para>Optional summary abstract</para>
  7  </summary>
  8  -->
  9    <introduction>
 10      <!-- Uncomment this to generate an outline of the section and sub-section
 11         titles.  Specify a numeric value as the inner text to limit it to
 12         a specific number of sub-topics when creating the outline.  Specify
 13         zero (0) to limit it to top-level sections only.  -->
 14      <!-- <autoOutline /> -->
 15      <para>The text editor makes use of several different coordinate systems.
 16		Here's an explanation of them.</para>
 17    </introduction>
 18    <!-- Add one or more top-level section elements.  These are collapsible.
 19       If using <autoOutline /> tag, add an address attribute to identify
 20       it so that it can be jumped to with a hyperlink. -->
 21    <section>
 22      <title>Offset</title>
 23      <content>
 24        <para>In AvalonEdit, an index into the document is called an <newTerm>offset</newTerm>.</para>
 25        <para>
 26			Offsets usually represent the position between two characters.
 27			The first offset at the start of the document is 0;
 28			the offset after the first char in the document is 1.
 29			The last valid offset is <codeInline>document.TextLength</codeInline>,
 30			representing the end of the document.
 31			This is exactly the same as the <codeInline>index</codeInline> parameter
 32			used by methods in the .NET String or StringBuilder classes.
 33        </para>
 34      </content>
 35    </section>
 36    <section>
 37      <title>TextLocation</title>
 38      <content>
 39        <para>The
 40        <codeEntityReference qualifyHint="true">T:ICSharpCode.AvalonEdit.Document.TextLocation</codeEntityReference>
 41        struct represents a Line/Column pair. Line and column are counted from 1.</para>
 42        <para>The document provides the methods
 43				<codeEntityReference qualifyHint="true">M:ICSharpCode.AvalonEdit.Document.TextDocument.GetLocation(System.Int32)</codeEntityReference>
 44				and
 45				<codeEntityReference qualifyHint="true">M:ICSharpCode.AvalonEdit.Document.TextDocument.GetOffset(ICSharpCode.AvalonEdit.Document.TextLocation)</codeEntityReference>
 46			to convert between offsets and <codeInline>TextLocation</codeInline>s.</para>
 47      </content>
 48    </section>
 49    <section>
 50      <title>TextAnchor</title>
 51      <content>
 52      	<para>If you are working with the text editor, you will likely run into the problem
 53      	that you need to store an offset, but want it to adjust automatically whenever
 54      	text is inserted prior to that offset. </para>
 55      	<para>Sure, you could listen to the TextDocument.Changed event and call
 56      	GetNewOffset on the DocumentChangeEventArgs to translate the offset,
 57      	but that gets tedious; especially when your object is short-lived and you
 58      	have to deal with deregistering the event handler at the correct point of time.</para>
 59        <para>A text anchor object stores an Offset, but automatically
 60			updates the offset when text is inserted/removed before the offset.
 61		</para>
 62        <para>
 63			A much simpler solution is to use the
 64			<codeEntityReference qualifyHint="true">T:ICSharpCode.AvalonEdit.Document.TextAnchor</codeEntityReference>
 65			class.
 66			Please take a look at the documentation for that class for more details.
 67		</para>
 68      </content>
 69    </section>
 70    <section>
 71      <title>RelativeTextOffset</title>
 72      <content>
 73        <para>An offset in the document, but relative to the start offset of a <codeEntityReference>T:ICSharpCode.AvalonEdit.Rendering.VisualLine</codeEntityReference>.</para>
 74        <para>Relative text offsets are used to store document offsets in visual lines.</para>
 75        <para>You can convert between relative text offsets and document offsets
 76			by adding/subtracting
 77			<codeEntityReference qualifyHint="true">P:ICSharpCode.AvalonEdit.Rendering.VisualLine.FirstDocumentLine</codeEntityReference>.<codeEntityReference>P:ICSharpCode.AvalonEdit.Document.DocumentLine.Offset</codeEntityReference>.
 78			</para>
 79      </content>
 80    </section>
 81    <section>
 82      <title>VisualColumn</title>
 83      <content>
 84        <para>An integer value that specifies a position inside a VisualLine.</para>
 85        <para>
 86			Not only text has a length in the visual line, but also other VisualLineElements.
 87			VisualColumn is counting from 0 for each visual line.
 88			</para>
 89        <para>For example, tab markers take 2 visual columns (the marker and the tab space),
 90			newline markers take 1 visual column; folding markers take just 1 visual column
 91			even though they are longer in the document text.</para>
 92        <para>Use the
 93			<codeEntityReference qualifyHint="true">M:ICSharpCode.AvalonEdit.Rendering.VisualLine.GetVisualColumn(System.Int32)</codeEntityReference>
 94			and 
 95			<codeEntityReference qualifyHint="true">M:ICSharpCode.AvalonEdit.Rendering.VisualLine.GetRelativeOffset(System.Int32)</codeEntityReference>
 96			methods to convert between
 97			visual columns and relative text offsets.</para>
 98        <alert class="note">
 99          <para>Do not confuse VisualColumn with text columns.
100				VisualColumn starts at 0, text column at 1. Text may have different length
101				in the two coordinate systems (e.g. tab markers, foldings).</para>
102        </alert>
103      </content>
104    </section>
105    <section>
106      <title>TextViewPosition</title>
107      <content>
108        <para>A Line,Column,VisualColumn triple.</para>
109        <para>The <codeEntityReference qualifyHint="true">T:ICSharpCode.AvalonEdit.TextViewPosition</codeEntityReference>
110        	struct can be implicitly converted
111			to <codeEntityReference qualifyHint="false">T:ICSharpCode.AvalonEdit.Document.TextLocation</codeEntityReference>,
112			but has the additional VisualColumn information
113			that is necessary to accurately hold the caret position when
114			VisualLineElements with DocumentLength 0 are in use.</para>
115      </content>
116    </section>
117    <section>
118      <title>VisualTop</title>
119      <content>
120        <para>A double value that specifies the distance from the top of
121			the document to the top of a line measured in device-independent pixels.</para>
122        <para>VisualTop is equivalent to the Y component of a VisualPosition.</para>
123      </content>
124    </section>
125    <section>
126      <title>VisualPosition</title>
127      <content>
128        <para>A Point value (double X,Y) that specifies the position of an
129			element from the top left document corner measured in device-independent pixels.</para>
130        <para>To convert a VisualPosition to or from a (mouse) position inside
131			the TextView, simply subtract or add
132			<codeEntityReference qualifyHint="true">P:ICSharpCode.AvalonEdit.Rendering.TextView.ScrollOffset</codeEntityReference>
133			to it.
134			</para>
135      </content>
136    </section>
137    <relatedTopics>
138      <!-- One or more of the following:
139         - A local link
140         - An external link
141         - A code entity reference
142
143    <link xlink:href="Other Topic's ID"/>
144    <link xlink:href="Other Topic's ID">Link inner text</link>
145
146    <externalLink>
147        <linkText>Link text</linkText>
148        <linkAlternateText>Optional alternate link text</linkAlternateText>
149        <linkUri>URI</linkUri>
150    </externalLink>
151
152    <codeEntityReference>API member ID</codeEntityReference>
153
154    Examples:
155
156    <link xlink:href="00e97994-e9e6-46e0-b420-5be86b2f8270" />
157    <link xlink:href="00e97994-e9e6-46e0-b420-5be86b2f8278">Some other topic</link>
158
159    <externalLink>
160        <linkText>SHFB on CodePlex</linkText>
161        <linkAlternateText>Go to CodePlex</linkAlternateText>
162        <linkUri>http://www.codeplex.com/SHFB</linkUri>
163    </externalLink>
164
165    <codeEntityReference>T:TestDoc.TestClass</codeEntityReference>
166    <codeEntityReference>P:TestDoc.TestClass.SomeProperty</codeEntityReference>
167    <codeEntityReference>M:TestDoc.TestClass.#ctor</codeEntityReference>
168    <codeEntityReference>M:TestDoc.TestClass.#ctor(System.String,System.Int32)</codeEntityReference>
169    <codeEntityReference>M:TestDoc.TestClass.ToString</codeEntityReference>
170    <codeEntityReference>M:TestDoc.TestClass.FirstMethod</codeEntityReference>
171    <codeEntityReference>M:TestDoc.TestClass.SecondMethod(System.Int32,System.String)</codeEntityReference>
172    -->
173    </relatedTopics>
174  </developerConceptualDocument>
175</topic>