[]
DEMOS DOCS API PRICING
FREE TRIAL
(Showing Draft Content)

GrapeCity.Documents.Text.TextLayout.SplitRef

SplitRef Method

SplitRef(TextSplitOptions, ref TextLayout)

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.

Declaration
public SplitResult SplitRef(TextSplitOptions splitOptions, ref TextLayout rest)
Public Function SplitRef(splitOptions As TextSplitOptions, ByRef rest As TextLayout) As SplitResult
Parameters
Type Name Description
TextSplitOptions splitOptions

Options controlling how text is split.
TextLayout 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.
Returns
Type Description
SplitResult

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(TextSplitOptions, out TextLayout) 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