/AvalonEdit/Documentation/Coordinate Systems.aml
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>