org.gnome.pango

## Class Layout

- Object
- - org.freedesktop.bindings.Pointer
  - - org.freedesktop.bindings.Proxy
    - - org.gnome.glib.Object
      - - org.gnome.pango.Layout

-     public class Layout
      extends Object

  A Layout represents a paragraph of text, together with its attributes.

  Drawing is done with Cairo; you get a Layout by passing the Cairo drawing Context you're currently working in to the constructor. If you're drawing a Widget, you'll be doing so in a `Widget.Draw` signal handler where you'll typically see:

       w.connect(new Widget.Draw() {
           public boolean onDraw(Widget source, Context cr) {
               final Layout layout;

               layout = new Layout(cr);

               // use layout to lay out the text you wish to draw

               cr.showLayout(layout);
           }
       });

  Layout can indeed layout multiple paragraphs of text, but usually you need more control over positioning, so most of the time you have to work a paragraph at a time. You can, however, avoid creating a new Layout each time by calling `setText()` with the new paragraph text.

  A single paragraph at a time is how PangoLayout was designed and intended to be used.

  Since:
    4.0.10
  Author:
    Vreixo Formoso, Andrew Cowie

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `Layout(Context context)` Create a new Layout configured to draw using the given Cairo Context backend.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `Alignment` | `getAlignment()` Get the alignment of the Layout.
    `double` | `getBaseline()` Get the vertical position of the baseline in the first line of this Layout.
    `Context` | `getContext()` Return the Pango Context powering this Layout.
    `Rectangle` | `getExtentsInk()`
    `Rectangle` | `getExtentsLogical()` Get the Rectangle enclosing the entire Layout as it will be rendered.
    `double` | `getIndent()` Get the paragraph indent of this Layout.
    `boolean` | `getJustify()` Gets whether each complete line should be stretched to fill the entire width of the Layout.
    `LayoutLine` | `getLine(int index)` Get the LayoutLine representing an individual line of text as have been laid out by this Layout.
    `int` | `getLineCount()` Get the number of lines that this Layout has been laid out into.
    `LayoutLine` | `getLineReadonly(int index)` Get the LayoutLine representing an individual line of text as has been laid out by this Layout.
    `LayoutLine[]` | `getLines()` Get an array of LayoutLines representing the individual lines of text as have been laid out by this Layout.
    `LayoutLine[]` | `getLinesReadonly()` Get an array of LayoutLines representing the individual lines of text as have been laid out by this Layout.
    `int` | `getPixelHeight()` Get the height, in pixels, of the Layout.
    `int` | `getPixelWidth()` Get the width, in pixels, of the Layout.
    `double` | `getSizeHeight()` Get the height of the Layout.
    `double` | `getSizeWidth()` Get the width of the Layout.
    `double` | `getSpacing()` Get the spacing between lines of a rendered paragraph.
    `void` | `setAlignment(Alignment alignment)` Sets the alignment for the Layout.
    `void` | `setAttributes(AttributeList list)` Sets the sequence of Attributes describing the markup you wish to have in play.
    `void` | `setFontDescription(FontDescription desc)` Sets the default FontDescription for the Layout.
    `void` | `setIndent(double indent)` Sets the width by which to indent the first line of each paragraph.
    `void` | `setJustify(boolean justify)` Sets whether each complete line should be stretched to fill the entire width of the layout.
    `void` | `setMarkup(String markup)` Set the text of this Layout.
    `void` | `setSingleParagraphMode(boolean setting)` Indicate that the Layout is not to do paragraph breaks on encountering LINE_SEPARATOR characters.
    `void` | `setSpacing(double between)` Set the spacing that will occur between lines of a rendered paragraph.
    `void` | `setText(String text)` Sets the text of the Layout.
    `void` | `setWidth(double width)` Set the width of the Layout to be used for word-wrapping purposes.
    `void` | `setWrapMode(WrapMode mode)` Set the line wrapping mode (if set, then lines turn into paragraphs).
    `String` | `toString()`

    - ### Methods inherited from class Object

      `equals, getClass, hashCode, notify, notifyAll, wait, wait, wait`

- - ### Constructor Detail

    - #### Layout

          public Layout(Context context)

      Create a new Layout configured to draw using the given Cairo Context backend.

      This Layout can be used to set up the text to draw and its properties.

      To actually draw the text, you call the `showLayout()` method on the Cairo Context you specified when constructing this Layout.

      Note that if you change the transformation or target Surface for the Context, you must call `updateLayout()` to signal this Layout that changes have taken place.

      Since:
        4.0.10

  - ### Method Detail

    - #### getAlignment

          public Alignment getAlignment()

      Get the alignment of the Layout.
      Since:
        4.0.10

    - #### getBaseline

          public double getBaseline()

      Get the vertical position of the baseline in the first line of this Layout.

      If you're laying out lines individually, you almost certainly want to get the extents of each LayoutLine and then use that Rectangle's `getAscent()` instead.

      Since:
        4.0.10

    - #### getContext

          public Context getContext()

      Return the Pango Context powering this Layout.

      Since you probably constructed this Layout with a Cairo Context, you're going to end up with some messy fully qualified names if you need to use this. You might just want to use the type implicitly:

           layout.getContext().setFontOptions(options);

      so that you can keep the rest of the uses of the bare word `Context` as the Cairo one already imported.

      Note that having made a call like the one shown, you need to either call `contextChanged()` or `setText()` to cause the Layout to take notice.

      Since:
        4.0.10

    - #### getExtentsInk

          public Rectangle getExtentsInk()

    - #### getExtentsLogical

          public Rectangle getExtentsLogical()

      Get the Rectangle enclosing the entire Layout as it will be rendered.
      Since:
        4.0.10

    - #### getIndent

          public double getIndent()

      Get the paragraph indent of this Layout. It'll be `0` unless you called `setIndent()` to change it.
      Since:
        4.0.10

    - #### getJustify

          public boolean getJustify()

      Gets whether each complete line should be stretched to fill the entire width of the Layout.
      Since:
        4.0.10

    - #### getLine

          public LayoutLine getLine(int index)

      Get the LayoutLine representing an individual line of text as have been laid out by this Layout. The `index` number is `0` origin.
      Since:
        4.0.10

    - #### getLineCount

          public int getLineCount()

      Get the number of lines that this Layout has been laid out into. It will always be at least `1` (and indeed will only be `1` unless you have called `setWidth()` and supplied sufficient text that the Layout has wrapped it into a multi-line paragraph).
      Since:
        4.0.10

    - #### getLineReadonly

          public LayoutLine getLineReadonly(int index)

      Get the LayoutLine representing an individual line of text as has been laid out by this Layout. The `index` number ranges from `0` origin to `getLineCount()` `- 1`.

      This method is optimized for the common case where you are not changing the characteristics of the individual glyphs in the line, and should be used in preference to `getLine()`.

      Since:
        4.0.10

    - #### getLines

          public LayoutLine[] getLines()

      Get an array of LayoutLines representing the individual lines of text as have been laid out by this Layout.
      Since:
        4.0.10

    - #### getLinesReadonly

          public LayoutLine[] getLinesReadonly()

      Get an array of LayoutLines representing the individual lines of text as have been laid out by this Layout. This form of `getLines()` uses faster code paths optimized for the usual case that you are not using Pango to modify the text in the lines, but are instead planning to go directly to rendering them.
      Since:
        4.0.10

    - #### getPixelHeight

          public int getPixelHeight()

      Get the height, in pixels, of the Layout. See the corresponding method `getPixelWidth()` for details.
      Since:
        4.0.10

    - #### getPixelWidth

          public int getPixelWidth()

      Get the width, in pixels, of the Layout. This is suitable, together with `getPixelHeight()`, to pass to a Widget's `setSizeRequest()` in order to ensure enough space is available for the text to actually be shown.
      Since:
        4.0.10

    - #### getSizeHeight

          public double getSizeHeight()

      Get the height of the Layout. This is the height of the layout text, taking its format into account (for example, the size of the Font will influence the final size!).
      Since:
        4.0.10

    - #### getSizeWidth

          public double getSizeWidth()

      Get the width of the Layout. This is the width of the layout text, taking its format into account (for example, the size of the Font will influence the final size!).

      Note that this is not necessarily related with the line wrap width you set with `setWidth()` method.

      Since:
        4.0.10

    - #### getSpacing

          public double getSpacing()

      Get the spacing between lines of a rendered paragraph.
      Since:
        4.0.11

    - #### setAlignment

          public void setAlignment(Alignment alignment)

      Sets the alignment for the Layout. This controls how partial lines are positioned within the available horizontal space.

      Note that contrary to what is commonly expressed in the user interface of common tools like word processors, justification is not an alignment type. If you wish to have equally wide lines, see `setJustify()`. Alignment remains important as it controls where indentation is relative to and what to do with the last line of each paragraph.

      Since:
        4.0.10

    - #### setAttributes

          public void setAttributes(AttributeList list)

      Sets the sequence of Attributes describing the markup you wish to have in play. This indices of all the Attributes need to have been set after the text in this Layout was established via `setText()`.

      See `AttributeList` for a detailed example of using this method to indicate formatting.

      Since:
        4.0.10

    - #### setFontDescription

          public void setFontDescription(FontDescription desc)

      Sets the default FontDescription for the Layout.
      Since:
        4.0.10

    - #### setIndent

          public void setIndent(double indent)

      Sets the width by which to indent the first line of each paragraph. A negative value of indent will produce a hanging indentation. That is, the first line will have the full width, and subsequent lines will be indented by the absolute value of indent.

      Note that the indent is relative to the Alignment of the text, if the text is aligned to the right, the indent is computed from there.

      Since:
        4.0.10

    - #### setJustify

          public void setJustify(boolean justify)

      Sets whether each complete line should be stretched to fill the entire width of the layout.

      This stretching is typically done by adding whitespace, but for some scripts (such as Arabic), the justification may be done in more complex ways, like extending the characters.

      Since:
        4.0.10

    - #### setMarkup

          public void setMarkup(String markup)

      Set the text of this Layout. Its format is specified using Pango Markup format.

      If you're just passing in normal straight-forward unformatted text, use `setText()`.

      WARNING:
      Use `Glib.markupEscapeText()` unless you are certain that your input does not contain any characters thatare invalid XML.

      Since:
        4.0.10
      See Also:
        Pango Markup format

    - #### setSingleParagraphMode

          public void setSingleParagraphMode(boolean setting)

      Indicate that the Layout is not to do paragraph breaks on encountering LINE_SEPARATOR characters.

      If this is turned on then when the Layout encounters newlines they will be replaced with an symbol marking the position of the newline. This allows you to create a user interface that edits the newlines explicitly on a single line.

      The default is `false`, obviously.

      Note that word wrapping is not affected by this. This is single paragraph mode, not single line mode.

      Since:
        4.0.11

    - #### setSpacing

          public void setSpacing(double between)

      Set the spacing that will occur between lines of a rendered paragraph.

      Obviously this will only have any effect if you are rendering complete Layouts as 2D shapes via `showLayout()`. If you are working instead with individual LayoutLines then it's up to you how much spacing you pad between lines as you draw them.

      The default is `0`.

      Since:
        4.0.11

    - #### setText

          public void setText(String text)

      Sets the text of the Layout. This is the text that will be drawn.

      If you wish to pass text enhanced with Pango Markup, use `setMarkup()` instead.

      Alternately, you can use this `setText()` method to set the full textual content of the Layout and then build up a set of Attributes describing which formats you wish to be in effect across what ranges. You assemble this information in an AttributeList and then apply it to this Layout by calling `setAttributes()`.

      Since:
        4.0.10

    - #### setWidth

          public void setWidth(double width)

      Set the width of the Layout to be used for word-wrapping purposes.

      This will determine the positioning of the text and how the lines are wrapped. If a text line is greater than the given size, it is split into several lines.

      Parameters:
        `width` - The width in Cairo terms (typically pixels if you're drawing a Widget or image, or points if you're drawing a PDF).
      Since:
        4.0.10

    - #### setWrapMode

          public void setWrapMode(WrapMode mode)

      Set the line wrapping mode (if set, then lines turn into paragraphs). The width must be set with `setWidth()` for this to work.

      The default is `WORD` so you shouldn't need to call this. In any case, wrapping is turned on by setting a width greater than `-1`, not by this method.

      Since:
        4.0.11

    - #### toString

          public String toString()

      Overrides:
        `toString` in class `org.freedesktop.bindings.Pointer`