Document Solutions for Imaging
DS.Documents.Imaging Assembly / GrapeCity.Documents.Text Namespace / TextLayout Class / SplitRef Method
Options controlling how text is split.
Recipient for the text that did not fit in the current bounds. If null, a new instance will be created and assigned to this parameter. If non-null, that TextLayout instance will be filled with the text that did not fit. When rendering large blocks of text, this improves performance by avoiding the need to initialize a new instance of a TextLayout for each split.

In This Topic
    SplitRef Method
    In This Topic
    Fits all or the first portion of the current text layout into the current layout bounds. If the whole text did not fit into the bounds, the rest is moved into the TextLayout instance specified by the reference parameter rest. If it is null, a new TextLayout instance is created.
    Syntax
    'Declaration
 
Public Function SplitRef( _
   ByVal splitOptions As TextSplitOptions, _
   ByRef rest As TextLayout _
) As SplitResult
    public SplitResult SplitRef( 
   TextSplitOptions splitOptions,
   ref TextLayout rest
)

    Parameters

    splitOptions
    Options controlling how text is split.
    rest
    Recipient for the text that did not fit in the current bounds. If null, a new instance will be created and assigned to this parameter. If non-null, that TextLayout instance will be filled with the text that did not fit. When rendering large blocks of text, this improves performance by avoiding the need to initialize a new instance of a TextLayout for each split.

    Return Value

    A value indicating the result of splitting the current text layout.
    Remarks
    Because initializing a new instance of the TextLayout class takes a relatively long time, reusing an existing instance can improve performance when rendering large amounts of text. This is why this method exists, and may be preferred over the Split method. The typical use of this method would be: GcPdfDocument doc = new GcPdfDocument(); // ... TextLayout tl = new TextLayout(); // set up the text layout, add text to it... TextSplitOptions to = new TextSplitOptions(); // set up text split options... TextLayout rest = null; // a loop rendering a long text layout: while (true) { var splitResult = tl.SplitRef(to, ref rest); doc.Pages.Add().Graphics.DrawTextLayout(tl, PointF.Empty); if (splitResult != SplitResult.Split) break; var temp = tl; tl = rest; // move on to the next portion of the text rest = temp; // avoid re-initializing a new text layout, by re-using the old one } Note that in this code, the ONLY point of swapping 'rest' and 'tl' is to provide an existing instance of a TextLayout class to the next SplitRef call so that a new instance does not need to be initialized. No actual data from the old text layout is (re)used, so functionally the last three lines can be replaced with 'tl = rest; rest = null;' assignments.
    See Also

    Reference

    TextLayout Class
    TextLayout Members
    Split Method
    SplitAndBalance Method
    SplitAndBalanceRef Method