← Back to branch summary

~ubuntu-branches/ubuntu/trusty/monodevelop/trusty-proposed

« back to all changes in this revision

Viewing changes to external/monomac/docs/en/MonoMac.Foundation/NSMutableAttributedString.xml

  • Committer: Package Import Robot
  • Author(s): Jo Shields
  • Date: 2013-05-12 09:46:03 UTC
  • mto: This revision was merged to the branch mainline in revision 29.
  • Revision ID: package-import@ubuntu.com-20130512094603-mad323bzcxvmcam0
Tags: upstream-4.0.5+dfsg
Import upstream version 4.0.5+dfsg

Show diffs side-by-side

added added

removed removed

Lines of Context:
external/monomac/docs/en/MonoMac.Foundation/NSMutableAttributedString.xml
15
15
    </Attribute>
16
16
  </Attributes>
17
17
  <Docs>
18
 
    <summary>To be added.</summary>
19
 
    <remarks>To be added.</remarks>
 
18
    <summary>Mutable strings that can be annotated with a set of attributes.</summary>
 
19
    <remarks>
 
20
      <para>
 
21
 
 
22
        The NSMutableAttributedString holds a mutable string that can
 
23
        has a series of overlapping attributes applied to ranges of
 
24
        the string.
 
25
 
 
26
      </para>
 
27
      <para>
 
28
        <img href="NSMutableAttributedString.png" />&gt;
 
29
      </para>
 
30
      <para>
 
31
 
 
32
        Unlike the <see cref="T:MonoMac.Foundation.NSAttributedString" /> both the
 
33
        contents of the string as well as the attributes applied to it
 
34
        can be changed after the string has been constructed.
 
35
 
 
36
      </para>
 
37
      <para> 
 
38
        These types typically are used to attach information to
 
39
        elements of the string that dictate the font and colors to use
 
40
        as well as rendering attributes like kerning or how to render
 
41
        ligatures on a specific run of code.
 
42
      </para>
 
43
      <para> These classes do not dictate the meaning or behavior of
 
44
        the attributes on a string, they merely keep track of the
 
45
        attributes.  The actual meaning of these attributes is
 
46
        interpreted by the consumer of these objects.   
 
47
      </para>
 
48
      <para> If you are performing multiple changes to an
 
49
        NSMutableAttributedString, you can optimize the performance by
 
50
        surrounding your changes with calls to <see cref="M:MonoMac.Foundation.BeginEditing()" /> and <see cref="M:MonoMac.Foundation.EndEditing()" />.  This will
 
51
        prevent the internal data structures to be updated on every
 
52
        change and delay the internal changes until the <see cref="M:MonoMac.Foundation.EndEditing()" /> method is called.
 
53
        </para>
 
54
    </remarks>
20
55
  </Docs>
21
56
  <Members>
22
57
    <Member MemberName=".ctor">
30
65
        <Attribute>
31
66
          <AttributeName>MonoMac.Foundation.Export("init")</AttributeName>
32
67
        </Attribute>
 
68
        <Attribute>
 
69
          <AttributeName>System.ComponentModel.EditorBrowsable(System.ComponentModel.EditorBrowsableState.Advanced)</AttributeName>
 
70
        </Attribute>
33
71
      </Attributes>
34
72
      <Parameters />
35
73
      <Docs>
54
92
        <Parameter Name="other" Type="MonoMac.Foundation.NSAttributedString" />
55
93
      </Parameters>
56
94
      <Docs>
57
 
        <param name="other">To be added.</param>
58
 
        <summary>To be added.</summary>
59
 
        <remarks>To be added.</remarks>
 
95
        <param name="other">The source attributed string.</param>
 
96
        <summary>Creates a NSMutableAttributedString from a NSAttributedString.</summary>
 
97
        <remarks>
 
98
        </remarks>
60
99
      </Docs>
61
100
    </Member>
62
101
    <Member MemberName=".ctor">
70
109
        <Attribute>
71
110
          <AttributeName>MonoMac.Foundation.Export("initWithCoder:")</AttributeName>
72
111
        </Attribute>
 
112
        <Attribute>
 
113
          <AttributeName>System.ComponentModel.EditorBrowsable(System.ComponentModel.EditorBrowsableState.Advanced)</AttributeName>
 
114
        </Attribute>
73
115
      </Attributes>
74
116
      <Parameters>
75
117
        <Parameter Name="coder" Type="MonoMac.Foundation.NSCoder" />
87
129
      <AssemblyInfo>
88
130
        <AssemblyVersion>0.0.0.0</AssemblyVersion>
89
131
      </AssemblyInfo>
 
132
      <Attributes>
 
133
        <Attribute>
 
134
          <AttributeName>System.ComponentModel.EditorBrowsable(System.ComponentModel.EditorBrowsableState.Advanced)</AttributeName>
 
135
        </Attribute>
 
136
      </Attributes>
90
137
      <Parameters>
91
138
        <Parameter Name="t" Type="MonoMac.Foundation.NSObjectFlag" />
92
139
      </Parameters>
93
140
      <Docs>
94
141
        <param name="t">Unused sentinel value, pass NSObjectFlag.Empty.</param>
95
 
        <summary>Constructor to call on derived classes to skip initialization and merely allocate the object.</summary>
 
142
        <summary>Constructor to call on derived classes when the derived class has an [Export] constructor.</summary>
96
143
        <remarks>
97
 
          <para>This constructor should be called by derived classes when they completely construct the object in managed code and merely want the runtime to allocate and initialize the NSObject.   This is required to implement the two-step initialization process that Objective-C uses, the first step is to perform the object allocation, the second step is to initialize the object.   When you invoke the constructor that takes the NSObjectFlag.Empty you taking advatnage of a direct path that goes all the way up to NSObject to merely allocate the object's memory and bind the Objective-C and C# objects together.    The actual initialization of the object is up to you.</para>
98
 
          <para>This constructor is typically used by the binding generator to allocate the object, but prevent the actual initialization to take place.   Once the allocation has taken place, the constructor has to initialize the object.   With constructors generated by the binding generator this means that it manually invokes one of the "init" methods to initialize the object.</para>
99
 
          <para>It is your responsability to completely initialize the object if you chain up using the NSObjectFlag.Empty path.</para>
100
 
          <para>In general, if your constructors invokes the NSObjectFlag.Empty base implementation, then it should be calling an Objective-C init method.   If this is not the case, you should instead chain to the proper constructor in your class. </para>
101
 
          <para>The argument value is ignored and merely ensures that the only code that is executed is the construction phase is the basic NSObject allocation and runtime type registration.  Typically the chaining would look like this:</para>
 
144
          <para>This constructor should be called by derived classes when they are initialized using an [Export] attribute. The argument value is ignore, typically the chaining would look like this:</para>
102
145
          <example>
103
146
            <code lang="C#">
104
 
//
105
 
// The NSObjectFlag merely allocates the object and registers the
106
 
// C# class with the Objective-C runtime if necessary, but no actual
107
 
// initXxx method is invoked, that is done later in the constructor
108
 
//
109
 
// This is taken from MonoMac's source code:
110
 
//
111
 
[Export ("initWithFrame:")]
112
 
public UIView (System.Drawing.RectangleF frame) : base (NSObjectFlag.Empty)
113
 
{
114
 
// Invoke the init method now.
115
 
        var initWithFrame = new Selector ("initWithFrame:").Handle;
116
 
        if (IsDirectBinding)
117
 
                Handle = MonoMac.ObjCRuntime.Messaging.IntPtr_objc_msgSend_RectangleF (this.Handle, initWithFrame, frame);
118
 
        else
119
 
                Handle = MonoMac.ObjCRuntime.Messaging.IntPtr_objc_msgSendSuper_RectangleF (this.SuperHandle, initWithFrame, frame);
120
 
}
 
147
public class MyClass : BaseClass {
 
148
    [Export ("initWithFoo:")]
 
149
    public MyClass (string foo) : base (NSObjectFlag.Empty)
 
150
    {
 
151
        ...
 
152
    }
121
153
</code>
122
154
          </example>
123
155
        </remarks>
130
162
      <AssemblyInfo>
131
163
        <AssemblyVersion>0.0.0.0</AssemblyVersion>
132
164
      </AssemblyInfo>
 
165
      <Attributes>
 
166
        <Attribute>
 
167
          <AttributeName>System.ComponentModel.EditorBrowsable(System.ComponentModel.EditorBrowsableState.Advanced)</AttributeName>
 
168
        </Attribute>
 
169
      </Attributes>
133
170
      <Parameters>
134
171
        <Parameter Name="handle" Type="System.IntPtr" />
135
172
      </Parameters>
157
194
        <Parameter Name="str" Type="System.String" />
158
195
      </Parameters>
159
196
      <Docs>
160
 
        <param name="str">To be added.</param>
161
 
        <summary>To be added.</summary>
162
 
        <remarks>To be added.</remarks>
 
197
        <param name="str">C# String</param>
 
198
        <summary>Creates an NSMutableAttributedString from a C# string, with no attributes attached to it.</summary>
 
199
        <remarks>
 
200
        </remarks>
163
201
      </Docs>
164
202
    </Member>
165
203
    <Member MemberName=".ctor">
174
212
        <Parameter Name="attributes" Type="MonoMac.CoreText.CTStringAttributes" />
175
213
      </Parameters>
176
214
      <Docs>
177
 
        <param name="str">To be added.</param>
178
 
        <param name="attributes">To be added.</param>
179
 
        <summary>To be added.</summary>
180
 
        <remarks>To be added.</remarks>
 
215
        <param name="str">C# string.</param>
 
216
        <param name="attributes">CoreText attributes to be applied to the string.</param>
 
217
        <summary>Creates an NSMutableAttributedString from a C# string and applies the specified CoreText attributes to the entire string.</summary>
 
218
        <remarks>
 
219
        </remarks>
181
220
      </Docs>
182
221
    </Member>
183
222
    <Member MemberName=".ctor">
197
236
        <Parameter Name="attributes" Type="MonoMac.Foundation.NSDictionary" />
198
237
      </Parameters>
199
238
      <Docs>
200
 
        <param name="str">To be added.</param>
201
 
        <param name="attributes">To be added.</param>
202
 
        <summary>To be added.</summary>
 
239
        <param name="str">C# string.</param>
 
240
        <param name="attributes">User-defined attributes as key/value pair dictionary.</param>
 
241
        <summary>Creates an NSMutableAttributedString from a C# string and applies the attributes contained in the NSDictionary to the entire string.</summary>
203
242
        <remarks>To be added.</remarks>
204
243
      </Docs>
205
244
    </Member>
224
263
        <Parameter Name="range" Type="MonoMac.Foundation.NSRange" />
225
264
      </Parameters>
226
265
      <Docs>
227
 
        <param name="attributeName">To be added.</param>
228
 
        <param name="value">To be added.</param>
229
 
        <param name="range">To be added.</param>
230
 
        <summary>To be added.</summary>
231
 
        <remarks>To be added.</remarks>
 
266
        <param name="attributeName">Attribute name (for example, "color")</param>
 
267
        <param name="value">Attribute value (for example "blue").</param>
 
268
        <param name="range">Range to which the attribute will be applied.</param>
 
269
        <summary>Adds an attribute and its value to the specified range of characters in the string.</summary>
 
270
        <remarks>
 
271
        </remarks>
232
272
      </Docs>
233
273
    </Member>
234
274
    <Member MemberName="AddAttributes">
246
286
        <Parameter Name="range" Type="MonoMac.Foundation.NSRange" />
247
287
      </Parameters>
248
288
      <Docs>
249
 
        <param name="attrs">To be added.</param>
250
 
        <param name="range">To be added.</param>
251
 
        <summary>To be added.</summary>
252
 
        <remarks>To be added.</remarks>
 
289
        <param name="attrs">The CoreText attributes to add.</param>
 
290
        <param name="range">Range to which the attribute will be applied.</param>
 
291
        <summary>Adds an attribute and its value to the specified range of characters in the string.</summary>
 
292
        <remarks>
 
293
        </remarks>
253
294
      </Docs>
254
295
    </Member>
255
296
    <Member MemberName="AddAttributes">
272
313
        <Parameter Name="range" Type="MonoMac.Foundation.NSRange" />
273
314
      </Parameters>
274
315
      <Docs>
275
 
        <param name="attrs">To be added.</param>
276
 
        <param name="range">To be added.</param>
277
 
        <summary>To be added.</summary>
278
 
        <remarks>To be added.</remarks>
 
316
        <param name="attrs">User-defined attributes as key/value pair dictionary.</param>
 
317
        <param name="range">Range to which the attribute will be applied.</param>
 
318
        <summary>Adds the specified attributes in the dictionary to the specified range of characters in the string.</summary>
 
319
        <remarks>
 
320
        </remarks>
279
321
      </Docs>
280
322
    </Member>
281
323
    <Member MemberName="Append">
297
339
        <Parameter Name="attrString" Type="MonoMac.Foundation.NSAttributedString" />
298
340
      </Parameters>
299
341
      <Docs>
300
 
        <param name="attrString">To be added.</param>
 
342
        <param name="attrString">The attributed string to append.</param>
 
343
        <summary>Appends an attributed string to this string.</summary>
 
344
        <remarks>
 
345
        </remarks>
 
346
      </Docs>
 
347
    </Member>
 
348
    <Member MemberName="Append">
 
349
      <MemberSignature Language="C#" Value="public void Append (MonoMac.Foundation.NSAttributedString first, object[] rest);" />
 
350
      <MemberSignature Language="ILAsm" Value=".method public hidebysig instance void Append(class MonoMac.Foundation.NSAttributedString first, object[] rest) cil managed" />
 
351
      <MemberType>Method</MemberType>
 
352
      <AssemblyInfo>
 
353
        <AssemblyVersion>0.0.0.0</AssemblyVersion>
 
354
      </AssemblyInfo>
 
355
      <ReturnValue>
 
356
        <ReturnType>System.Void</ReturnType>
 
357
      </ReturnValue>
 
358
      <Parameters>
 
359
        <Parameter Name="first" Type="MonoMac.Foundation.NSAttributedString" />
 
360
        <Parameter Name="rest" Type="System.Object[]">
 
361
          <Attributes>
 
362
            <Attribute>
 
363
              <AttributeName>System.ParamArray</AttributeName>
 
364
            </Attribute>
 
365
          </Attributes>
 
366
        </Parameter>
 
367
      </Parameters>
 
368
      <Docs>
 
369
        <param name="first">To be added.</param>
 
370
        <param name="rest">To be added.</param>
301
371
        <summary>To be added.</summary>
302
372
        <remarks>To be added.</remarks>
303
373
      </Docs>
319
389
      </ReturnValue>
320
390
      <Parameters />
321
391
      <Docs>
322
 
        <summary>To be added.</summary>
323
 
        <remarks>To be added.</remarks>
 
392
        <summary>Marks the beginning of changes.</summary>
 
393
        <remarks>
 
394
          You can invoke this method before you make a series of changes to a NSMutableAttributedString to inform the class that you will be making more than one change and that it does not need to compute any expensive internal data structures on each end.   The internal data structures will all be updated when you call the <see cref="M:MonoMac.Foundation.EndEditing()" /></remarks>
324
395
      </Docs>
325
396
    </Member>
326
397
    <Member MemberName="ClassHandle">
358
429
        <Parameter Name="range" Type="MonoMac.Foundation.NSRange" />
359
430
      </Parameters>
360
431
      <Docs>
361
 
        <param name="range">To be added.</param>
362
 
        <summary>To be added.</summary>
363
 
        <remarks>To be added.</remarks>
 
432
        <param name="range">Range to delete.</param>
 
433
        <summary>Removes the characters in the specified range.</summary>
 
434
        <remarks>
 
435
        </remarks>
364
436
      </Docs>
365
437
    </Member>
366
438
    <Member MemberName="EndEditing">
380
452
      </ReturnValue>
381
453
      <Parameters />
382
454
      <Docs>
383
 
        <summary>To be added.</summary>
384
 
        <remarks>To be added.</remarks>
 
455
        <summary>Marks the end of changes.</summary>
 
456
        <remarks>You should invoke this method after you have made a series of changes to a NSMutableAttributedString to inform the class that you are done making changes and it can perform its internal book keeping.   This is called after you called <see cref="M:MonoMac.Foundation.BeginEditing()" />.</remarks>
385
457
      </Docs>
386
458
    </Member>
387
459
    <Member MemberName="Insert">
404
476
        <Parameter Name="location" Type="System.Int32" />
405
477
      </Parameters>
406
478
      <Docs>
407
 
        <param name="attrString">To be added.</param>
408
 
        <param name="location">To be added.</param>
409
 
        <summary>To be added.</summary>
410
 
        <remarks>To be added.</remarks>
 
479
        <param name="attrString">Attributed string to insert.</param>
 
480
        <param name="location">Location where the string will be inserted.</param>
 
481
        <summary>Inserts an attributed string into the current string.</summary>
 
482
        <remarks>Any attributes that spanned the insertion point will be expanded, so they will continue to cover both the original text as well as the new text.</remarks>
411
483
      </Docs>
412
484
    </Member>
413
485
    <Member MemberName="RemoveAttribute">
430
502
        <Parameter Name="range" Type="MonoMac.Foundation.NSRange" />
431
503
      </Parameters>
432
504
      <Docs>
433
 
        <param name="name">To be added.</param>
434
 
        <param name="range">To be added.</param>
435
 
        <summary>To be added.</summary>
436
 
        <remarks>To be added.</remarks>
 
505
        <param name="name">Name of the attribute to remove.</param>
 
506
        <param name="range">Range where the attribute will be removed.</param>
 
507
        <summary>Removes the specified attribute from the range of characters</summary>
 
508
        <remarks>
 
509
        </remarks>
437
510
      </Docs>
438
511
    </Member>
439
512
    <Member MemberName="Replace">
456
529
        <Parameter Name="value" Type="MonoMac.Foundation.NSAttributedString" />
457
530
      </Parameters>
458
531
      <Docs>
459
 
        <param name="range">To be added.</param>
460
 
        <param name="value">To be added.</param>
461
 
        <summary>To be added.</summary>
462
 
        <remarks>To be added.</remarks>
 
532
        <param name="range">Range of characters that will be replaced.</param>
 
533
        <param name="value">Strings that will be inserted to replace the range of characters.</param>
 
534
        <summary>Replaces the specified range of characters with an attributed string.</summary>
 
535
        <remarks>
 
536
        </remarks>
463
537
      </Docs>
464
538
    </Member>
465
539
    <Member MemberName="Replace">
482
556
        <Parameter Name="newValue" Type="System.String" />
483
557
      </Parameters>
484
558
      <Docs>
485
 
        <param name="range">To be added.</param>
486
 
        <param name="newValue">To be added.</param>
487
 
        <summary>To be added.</summary>
488
 
        <remarks>To be added.</remarks>
 
559
        <param name="range">Range of characters that will be replaced.</param>
 
560
        <param name="newValue">Strings that will be inserted to replace the range of characters.</param>
 
561
        <summary>Replaces the specified range of characters with an attributed string.</summary>
 
562
        <remarks>
 
563
        </remarks>
489
564
      </Docs>
490
565
    </Member>
491
566
    <Member MemberName="SetAttributes">
503
578
        <Parameter Name="range" Type="MonoMac.Foundation.NSRange" />
504
579
      </Parameters>
505
580
      <Docs>
506
 
        <param name="attrs">To be added.</param>
507
 
        <param name="range">To be added.</param>
508
 
        <summary>To be added.</summary>
509
 
        <remarks>To be added.</remarks>
 
581
        <param name="attrs">CoreText attributes to be set on the string.</param>
 
582
        <param name="range">Range to which the attribute will be applied.</param>
 
583
        <summary>Sets the attributes for the specified ranges.  Any previous attributes in that range are replaces with the new values.</summary>
 
584
        <remarks>
 
585
        </remarks>
510
586
      </Docs>
511
587
    </Member>
512
588
    <Member MemberName="SetAttributes">
529
605
        <Parameter Name="range" Type="MonoMac.Foundation.NSRange" />
530
606
      </Parameters>
531
607
      <Docs>
532
 
        <param name="attrs">To be added.</param>
533
 
        <param name="range">To be added.</param>
534
 
        <summary>To be added.</summary>
535
 
        <remarks>To be added.</remarks>
 
608
        <param name="attrs">Dictionary of attributes to be set on the string.</param>
 
609
        <param name="range">Range to which the attribute will be applied.</param>
 
610
        <summary>Sets the attributes for the specified ranges.  Any previous attributes in that range are replaces with the new values.</summary>
 
611
        <remarks>
 
612
        </remarks>
536
613
      </Docs>
537
614
    </Member>
538
615
    <Member MemberName="SetString">
554
631
        <Parameter Name="attrString" Type="MonoMac.Foundation.NSAttributedString" />
555
632
      </Parameters>
556
633
      <Docs>
557
 
        <param name="attrString">To be added.</param>
558
 
        <summary>To be added.</summary>
559
 
        <remarks>To be added.</remarks>
 
634
        <param name="attrString">The new attributed string to set the contents to</param>
 
635
        <summary>Sets the contents of this NSMutableAttributedString to the value specified.</summary>
 
636
        <remarks>
 
637
        </remarks>
560
638
      </Docs>
561
639
    </Member>
562
640
  </Members>