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.ExposeEvent handler where you'll typically see:

 w.connect(new Widget.ExposeEvent() {
     public boolean onExposeEvent(Widget source, EventExpose event) {
         final Context cr;
         final Layout layout;
 
         cr = new Context(source.getWindow());
         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

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

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

Overview  Package   Class		java-gnome
PREV CLASS   NEXT CLASS	FRAMES    NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD	DETAIL: FIELD | CONSTR | METHOD