Gtk2HsContentsIndex
Graphics.UI.Gtk.Pango.Layout
Portabilityportable (depends on GHC)
Stabilityprovisional
Maintainergtk2hs-users@lists.sourceforge.net
Description

Functions to run the rendering pipeline.

  • The objects in this model contain a rendered paragraph of text. This interface is the easiest way to render text with Cairo or into a DrawWindow.
Synopsis
data PangoRectangle = PangoRectangle Double Double Double Double
data PangoLayout
layoutEmpty :: PangoContext -> IO PangoLayout
layoutText :: PangoContext -> String -> IO PangoLayout
layoutCopy :: PangoLayout -> IO PangoLayout
layoutGetContext :: PangoLayout -> IO PangoContext
layoutContextChanged :: PangoLayout -> IO ()
layoutSetText :: PangoLayout -> String -> IO ()
layoutGetText :: PangoLayout -> IO String
layoutSetMarkup :: PangoLayout -> Markup -> IO String
escapeMarkup :: String -> String
layoutSetMarkupWithAccel :: PangoLayout -> Markup -> IO (Char, String)
layoutSetAttributes :: PangoLayout -> [PangoAttribute] -> IO ()
layoutSetFontDescription :: PangoLayout -> Maybe FontDescription -> IO ()
layoutGetFontDescription :: PangoLayout -> IO (Maybe FontDescription)
layoutSetWidth :: PangoLayout -> Maybe Double -> IO ()
layoutGetWidth :: PangoLayout -> IO (Maybe Double)
data LayoutWrapMode
= WrapWholeWords
| WrapAnywhere
| WrapPartialWords
layoutSetWrap :: PangoLayout -> LayoutWrapMode -> IO ()
layoutGetWrap :: PangoLayout -> IO LayoutWrapMode
data EllipsizeMode
= EllipsizeNone
| EllipsizeStart
| EllipsizeMiddle
| EllipsizeEnd
layoutSetEllipsize :: PangoLayout -> EllipsizeMode -> IO ()
layoutGetEllipsize :: PangoLayout -> IO EllipsizeMode
layoutSetIndent :: PangoLayout -> Double -> IO ()
layoutGetIndent :: PangoLayout -> IO Double
layoutSetSpacing :: PangoLayout -> Double -> IO ()
layoutGetSpacing :: PangoLayout -> IO Double
layoutSetJustify :: PangoLayout -> Bool -> IO ()
layoutGetJustify :: PangoLayout -> IO Bool
layoutSetAutoDir :: PangoLayout -> Bool -> IO ()
layoutGetAutoDir :: PangoLayout -> IO Bool
data LayoutAlignment
= AlignLeft
| AlignCenter
| AlignRight
layoutSetAlignment :: PangoLayout -> LayoutAlignment -> IO ()
layoutGetAlignment :: PangoLayout -> IO LayoutAlignment
data TabAlign
type TabPosition = (Double, TabAlign)
layoutSetTabs :: PangoLayout -> [TabPosition] -> IO ()
layoutResetTabs :: PangoLayout -> IO ()
layoutGetTabs :: PangoLayout -> IO (Maybe [TabPosition])
layoutSetSingleParagraphMode :: PangoLayout -> Bool -> IO ()
layoutGetSingleParagraphMode :: PangoLayout -> IO Bool
layoutXYToIndex :: PangoLayout -> Double -> Double -> IO (Bool, Int, Int)
layoutIndexToPos :: PangoLayout -> Int -> IO PangoRectangle
layoutGetCursorPos :: PangoLayout -> Int -> IO (PangoRectangle, PangoRectangle)
data CursorPos
= CursorPosPrevPara
| CursorPos Int Int
| CursorPosNextPara
layoutMoveCursorVisually :: PangoLayout -> Bool -> Int -> Bool -> IO CursorPos
layoutGetExtents :: PangoLayout -> IO (PangoRectangle, PangoRectangle)
layoutGetPixelExtents :: PangoLayout -> IO (Rectangle, Rectangle)
layoutGetLineCount :: PangoLayout -> IO Int
layoutGetLine :: PangoLayout -> Int -> IO LayoutLine
layoutGetLines :: PangoLayout -> IO [LayoutLine]
data LayoutIter
layoutGetIter :: PangoLayout -> IO LayoutIter
layoutIterNextItem :: LayoutIter -> IO Bool
layoutIterNextChar :: LayoutIter -> IO Bool
layoutIterNextCluster :: LayoutIter -> IO Bool
layoutIterNextLine :: LayoutIter -> IO Bool
layoutIterAtLastLine :: LayoutIter -> IO Bool
layoutIterGetIndex :: LayoutIter -> IO Int
layoutIterGetBaseline :: LayoutIter -> IO Double
layoutIterGetItem :: LayoutIter -> IO (Maybe GlyphItem)
layoutIterGetLine :: LayoutIter -> IO (Maybe LayoutLine)
layoutIterGetCharExtents :: LayoutIter -> IO PangoRectangle
layoutIterGetClusterExtents :: LayoutIter -> IO (PangoRectangle, PangoRectangle)
layoutIterGetRunExtents :: LayoutIter -> IO (PangoRectangle, PangoRectangle)
layoutIterGetLineYRange :: LayoutIter -> IO (Double, Double)
layoutIterGetLineExtents :: LayoutIter -> IO (PangoRectangle, PangoRectangle)
data LayoutLine
layoutLineGetExtents :: LayoutLine -> IO (PangoRectangle, PangoRectangle)
layoutLineGetPixelExtents :: LayoutLine -> IO (Rectangle, Rectangle)
layoutLineIndexToX :: LayoutLine -> Int -> Bool -> IO Double
layoutLineXToIndex :: LayoutLine -> Double -> IO (Bool, Int, Int)
layoutLineGetXRanges :: LayoutLine -> Int -> Int -> IO [(Double, Double)]
Documentation
data PangoRectangle

Rectangles describing an area in Doubles.

  • Specifies x, y, width and height
Constructors
PangoRectangle Double Double Double Double
show/hide Instances
data PangoLayout
A rendered paragraph.
layoutEmpty :: PangoContext -> IO PangoLayout
Create an empty Layout.
layoutText :: PangoContext -> String -> IO PangoLayout
Create a new layout.
layoutCopy :: PangoLayout -> IO PangoLayout
Create a copy of the Layout.
layoutGetContext :: PangoLayout -> IO PangoContext
Retrieves the PangoContext from this layout.
layoutContextChanged :: PangoLayout -> IO ()

Signal a PangoContext change.

  • Forces recomputation of any state in the PangoLayout that might depend on the layout's context. This function should be called if you make changes to the context subsequent to creating the layout.
layoutSetText :: PangoLayout -> String -> IO ()
Set the string in the layout.
layoutGetText :: PangoLayout -> IO String
Retrieve the string in the layout.
layoutSetMarkup :: PangoLayout -> Markup -> IO String

Set the text of the layout, including attributes.

The string may include Markup. To print markup characters like '<', or '-', apply escapeMarkup to the string first.

The function returns the text that is actually shown.

escapeMarkup :: String -> String

Escape markup characters.

  • Used to display characters that normally denote markup. Note that this function is strict in that it forces all characters in the input string as soon as a single output character is requested.
layoutSetMarkupWithAccel :: PangoLayout -> Markup -> IO (Char, String)

Set the string in the layout.

  • The string may include Markup. Furthermore, any underscore character indicates that the next character will be marked as accelerator (i.e. underlined). A literal underscore character can be produced by placing it twice in the string.
  • The character which follows the underscore is returned so it can be used to add the actual keyboard shortcut. The second element is the string after parsing.
layoutSetAttributes :: PangoLayout -> [PangoAttribute] -> IO ()

Set text attributes of the text in the layout.

  • This function replaces any text attributes that this layout contained, even those that were set by using layoutSetMarkup.
layoutSetFontDescription :: PangoLayout -> Maybe FontDescription -> IO ()

Set a specific font description for this layout.

  • Specifying Nothing will unset the current font description, that is, the PangoLayout will use the font description in the current PangoContext.
layoutGetFontDescription :: PangoLayout -> IO (Maybe FontDescription)

Ask for the specifically set font description of this layout.

  • Returns Nothing if this layout uses the font description in the PangoContext it was created in.
  • Only available in Pango 1.8.0 or higher.
layoutSetWidth :: PangoLayout -> Maybe Double -> IO ()

Set the width of this paragraph.

  • Sets the width to which the lines of the PangoLayout should be wrapped.
  • Pass in Nothing to indicate that no wrapping is to be performed.
layoutGetWidth :: PangoLayout -> IO (Maybe Double)

Gets the width of this paragraph.

  • Gets the width to which the lines of the PangoLayout should be wrapped.
  • Returns is the current width, or Nothing to indicate that no wrapping is performed.
data LayoutWrapMode

Enumerates how a line can be wrapped.

WrapWholeWords
Breaks lines only between words.
  • This variant does not guarantee that the requested width is not exceeded. A word that is longer than the paragraph width is not split.
WrapAnywhere
Break lines anywhere.
WrapPartialWords
Wrap within a word if it is the only one on this line.
  • This option acts like WrapWholeWords but will split a word if it is the only one on this line and it exceeds the specified width.
Constructors
WrapWholeWords
WrapAnywhere
WrapPartialWords
show/hide Instances
layoutSetWrap :: PangoLayout -> LayoutWrapMode -> IO ()

Set how this paragraph is wrapped.

  • Sets the wrap style; the wrap style only has an effect if a width is set on the layout with layoutSetWidth. To turn off wrapping, call layoutSetWidth with Nothing.
layoutGetWrap :: PangoLayout -> IO LayoutWrapMode
Get the wrap mode for the layout.
data EllipsizeMode
The EllipsizeMode type describes what sort of (if any) ellipsization should be applied to a line of text. In the ellipsization process characters are removed from the text in order to make it fit to a given width and replaced with an ellipsis.
Constructors
EllipsizeNone
EllipsizeStart
EllipsizeMiddle
EllipsizeEnd
show/hide Instances
layoutSetEllipsize :: PangoLayout -> EllipsizeMode -> IO ()
Set how long lines should be abbreviated.
layoutGetEllipsize :: PangoLayout -> IO EllipsizeMode
Get the ellipsize mode for this layout.
layoutSetIndent :: PangoLayout -> Double -> IO ()

Set the indentation of this paragraph.

  • Sets the amount by which the first line should be indented. A negative value will produce a hanging indent, that is, all subsequent lines will be indented while the first line has full width.
layoutGetIndent :: PangoLayout -> IO Double

Gets the indentation of this paragraph.

  • Gets the amount by which the first line or the rest of the paragraph is indented.
layoutSetSpacing :: PangoLayout -> Double -> IO ()
Set the spacing between lines of this paragraph.
layoutGetSpacing :: PangoLayout -> IO Double
Gets the spacing between the lines.
layoutSetJustify :: PangoLayout -> Bool -> IO ()

Set if text should be streched to fit width.

  • Sets whether or not 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 is done by extending the characters.
  • Note that as of Pango 1.4, this functionality is not yet implemented.
layoutGetJustify :: PangoLayout -> IO Bool

Retrieve the justification flag.

layoutSetAutoDir :: PangoLayout -> Bool -> IO ()

Set if the base text direction should be overridden.

  • Sets whether to calculate the bidirectional base direction for the layout according to the contents of the layout; when this flag is on (the default), then paragraphs in layout that begin with strong right-to-left characters (Arabic and Hebrew principally), will have right-to-left layout, paragraphs with letters from other scripts will have left-to-right layout. Paragraphs with only neutral characters get their direction from the surrounding paragraphs.
  • When False, the choice between left-to-right and right-to-left layout is done by according to the base direction of the layout's PangoContext. (See contextSetTextDir).
  • When the auto-computed direction or a paragraph differs from the base direction of the context, then the interpretation of AlignLeft and AlignRight are swapped.
layoutGetAutoDir :: PangoLayout -> IO Bool

Retrieve the auto direction flag.

data LayoutAlignment
Enumerate to which side incomplete lines are flushed.
Constructors
AlignLeft
AlignCenter
AlignRight
show/hide Instances
layoutSetAlignment :: PangoLayout -> LayoutAlignment -> IO ()

Set how this paragraph is aligned.

  • Sets the alignment for the layout (how partial lines are positioned within the horizontal space available.)
layoutGetAlignment :: PangoLayout -> IO LayoutAlignment
Get the alignment for the layout.
data TabAlign

Specify where the Tab stop appears relative to the text.

  • Only Tab stops that align text to the left are supported right now.
show/hide Instances
type TabPosition = (Double, TabAlign)
A Tab position.
layoutSetTabs :: PangoLayout -> [TabPosition] -> IO ()
Set a list of Tab positoins.
layoutResetTabs :: PangoLayout -> IO ()

Reset the original set of Tab positions.

  • Restore the default which is a Tab stop every eight characters.
layoutGetTabs :: PangoLayout -> IO (Maybe [TabPosition])

Retrieve the list of current Tab positions.

  • If no Tab position where set, Nothing is returned. In this case, Tab positions are implicit at every eight characters.
layoutSetSingleParagraphMode :: PangoLayout -> Bool -> IO ()

Honor newlines or not.

  • If honor is True, do not treat newlines and similar characters as paragraph separators; instead, keep all text in a single paragraph, and display a glyph for paragraph separator characters. Used when you want to allow editing of newlines on a single text line.
layoutGetSingleParagraphMode :: PangoLayout -> IO Bool

Retrieve if newlines are honored.

layoutXYToIndex
:: PangoLayout
-> Doublethe x position
-> Doublethe y position
-> IO (Bool, Int, Int)

Converts a device unit to a character index.

  • Converts from x and y position within a layout to the index of the closest character. If the y position is not inside the layout, the closest position is chosen (the position will be clamped inside the layout). If the x position is not within the layout, then the start or the end of the line is chosen. If either the x or y positions were not inside the layout, then the function returns False; on an exact hit, it returns True.
  • The function returns the flag for the exact hit and the index into the string. The third value is zero if the character corresponds to one grapheme. If the grapheme is the result of a cluster, this value may be greater than one, indicating where in the grapheme the position lies. Zero represents the trailing edge on the grapheme.
layoutIndexToPos :: PangoLayout -> Int -> IO PangoRectangle

Return the rectangle of the glyph at the given index.

  • Converts from an index within a PangoLayout to the onscreen position corresponding to the grapheme at that index, which is represented as rectangle. Note that, given a PangoRectangle x y width height, x is always the leading edge of the grapheme and x + width the trailing edge of the grapheme. If the directionality of the grapheme is right-to-left, then width will be negative.
layoutGetCursorPos :: PangoLayout -> Int -> IO (PangoRectangle, PangoRectangle)

Return a cursor position.

  • Given an index within a layout, determines the positions that of the strong and weak cursors if the insertion point is at that index. The position of each cursor is stored as a zero-width rectangle. The strong cursor location is the location where characters of the directionality equal to the base direction of the layout are inserted. The weak cursor location is the location where characters of the directionality opposite to the base direction of the layout are inserted. The first element of the typle is the strong position, the second the weak.
data CursorPos

A new cursor position.

See layoutMoveCursorVisually.

Constructors
CursorPosPrevParaThe cursor should move to the previous paragraph.
CursorPos Int IntThe sum of the indices is the new cursor position.
CursorPosNextParaThe cursor should advance to the next paragraph.
layoutMoveCursorVisually
:: PangoLayout
-> BoolTrue to create a strong cursor.
-> IntThe previous position.
-> BoolTrue if the cursor should move right.
-> IO CursorPos

Move a cursor visually.

  • Compute a new cursor position from a previous cursor position. A value of True for the direction will move it to the right, independant of the underlying direction. Hence the cursor position might jump if left-to-right text is mixed with right-to-left text.
  • The first flag should be True if this cursor is the strong cursor. The strong cursor is the cursor of the base direction of the current layout (see layoutSetAutoDir). The weak cursor is that of the opposite direction.
  • The previous cursor position is given by idx. If this text at this position is a cluster, the cursor will only move to the end or beginning of the cluster as opposed to past the next character. The return value is either CursorPosNextPara if the cursor moved beyond this paragraph, it is CursorPosPrevPara if the cursor moved in front of this paragraph and it is CursorPos idx trail to denote the new cursor position idx. Note that idx will always denote an insertion point, that is, idx will never point into the middle of a cluster. The trail value can contain a positive value if the current cursor position is at the end of the current line. In this case, idx points past the last character of this line while trail contains the number of characters that are reponsible for the line break such as newlines. The actual cursor position is always idx+trail where the visual cursor should be shown.
layoutGetExtents :: PangoLayout -> IO (PangoRectangle, PangoRectangle)

Compute the physical size of the layout.

  • Computes the ink and the logical size of the Layout. The logical extend is used for positioning, the ink size is the smallest bounding box that includes all character pixels. The ink size can be smaller or larger that the logical layout.
layoutGetPixelExtents :: PangoLayout -> IO (Rectangle, Rectangle)

Compute the physical size of the layout.

layoutGetLineCount :: PangoLayout -> IO Int
Ask for the number of lines in this layout.
layoutGetLine :: PangoLayout -> Int -> IO LayoutLine

Extract a single lines of the layout.

  • The given index starts from 0. The function throws an ArrayException if the index is out of bounds.
  • The lines of each layout are regenerated if any attribute changes. Thus the returned list does not reflect the current state of lines after a change has been made.
layoutGetLines :: PangoLayout -> IO [LayoutLine]

Extract the lines of the layout.

  • The lines of each layout are regenerated if any attribute changes. Thus the returned list does not reflect the current state of lines after a change has been made.
data LayoutIter
An iterator to examine a layout.
layoutGetIter :: PangoLayout -> IO LayoutIter
Create an iterator to examine a layout.
layoutIterNextItem :: LayoutIter -> IO Bool

Move to the next GlyphItem.

  • Returns False if this was the last item in the layout.
layoutIterNextChar :: LayoutIter -> IO Bool

Move to the next char.

  • Returns False if this was the last char in the layout.
layoutIterNextCluster :: LayoutIter -> IO Bool

Move to the next cluster.

  • Returns False if this was the last cluster in the layout.
layoutIterNextLine :: LayoutIter -> IO Bool

Move to the next line.

  • Returns False if this was the last line in the layout.
layoutIterAtLastLine :: LayoutIter -> IO Bool

Check if the iterator is on the last line.

  • Returns True if the iterator is on the last line of this paragraph.
layoutIterGetIndex :: LayoutIter -> IO Int

Get the character index.

  • Note that iterating forward by char moves in visual order, not logical order, so indexes may not be sequential. Also, the index may be equal to the length of the text in the layout.
layoutIterGetBaseline :: LayoutIter -> IO Double

Query the vertical position within the layout.

  • Gets the y position of the current line's baseline (origin at top left of the entire layout).
layoutIterGetItem :: LayoutIter -> IO (Maybe GlyphItem)

Retrieve the current GlyphItem under the iterator.

  • Each LayoutLine contains a list of GlyphItems. This function returns the GlyphItem under the current iterator. If the iterator is positioned past the last charactor of the paragraph, the function returns Nothing.
layoutIterGetLine :: LayoutIter -> IO (Maybe LayoutLine)
Extract the line under the iterator.
layoutIterGetCharExtents :: LayoutIter -> IO PangoRectangle

Retrieve a rectangle surrounding a character.

  • Get the extents of the current character (origin is the top left of the entire layout). Only logical extents can sensibly be obtained for characters; ink extents make sense only down to the level of clusters.
layoutIterGetClusterExtents :: LayoutIter -> IO (PangoRectangle, PangoRectangle)

Compute the physical size of the cluster.

  • Computes the ink and the logical size of the cluster pointed to by LayoutIter.
layoutIterGetRunExtents :: LayoutIter -> IO (PangoRectangle, PangoRectangle)

Compute the physical size of the run.

  • Computes the ink and the logical size of the run pointed to by LayoutIter.
layoutIterGetLineYRange :: LayoutIter -> IO (Double, Double)

Retrieve vertical extent of this line.

  • Divides the vertical space in the PangoLayout being iterated over between the lines in the layout, and returns the space belonging to the current line. A line's range includes the line's logical extents, plus half of the spacing above and below the line, if layoutSetSpacing has been called to set layout spacing. The y positions are in layout coordinates (origin at top left of the entire layout).
  • The first element in the returned tuple is the start, the second is the end of this line.
layoutIterGetLineExtents :: LayoutIter -> IO (PangoRectangle, PangoRectangle)

Compute the physical size of the line.

  • Computes the ink and the logical size of the line pointed to by LayoutIter. See layoutGetExtents.
  • Extents are in layout coordinates (origin is the top-left corner of the entire PangoLayout). Thus the extents returned by this function will be the same width/height but not at the same x/y as the extents returned from layoutLineGetExtents.
data LayoutLine
A single line in a PangoLayout.
layoutLineGetExtents :: LayoutLine -> IO (PangoRectangle, PangoRectangle)

Compute the physical size of the line.

layoutLineGetPixelExtents :: LayoutLine -> IO (Rectangle, Rectangle)

Compute the physical size of the line.

  • Computes the ink and the logical size of the LayoutLine. See layoutGetExtents. The returned values are in device units, that is, pixels for the screen and points for printers.
layoutLineIndexToX
:: LayoutLine
-> Intthe index into the string
-> Boolreturn the beginning (False) or the end of the character
-> IO Double
Request the horizontal position of a character.
layoutLineXToIndex
:: LayoutLine
-> DoubleThe x position.
-> IO (Bool, Int, Int)

Request the character index of a given horizontal position.

  • Converts from an x offset to the index of the corresponding character within the text of the layout. If the x parameter is outside the line, a triple (False, index, trailing) is returned where index and trailing will point to the very first or very last position in the line. This notion of first and last position is based on the direction of the paragraph; for example, if the direction is right-to-left, then an x position to the right of the line results in 0 being returned for index and trailing. An x position to the left of the line results in index pointing to the (logical) last grapheme in the line and trailing pointing to the number of characters in that grapheme. The reverse is true for a left-to-right line. If the boolean flag in the result is True then x was within the layout line and trailing indicates where in a cluster the x position lay. It is 0 for the trailing edge of the cluster.
layoutLineGetXRanges
:: LayoutLineThe line of interest.
-> IntThe index of the start character (counting from 0). If this value is less than the start index for the line, then the first range will extend all the way to the leading edge of the layout. Otherwise it will start at the leading edge of the first character.
-> IntThe index after the last character. If this value is greater than the end index for the line, then the last range will extend all the way to the trailing edge of the layout. Otherwise, it will end at the trailing edge of the last character.
-> IO [(Double, Double)]

Retrieve bounding boxes for a given piece of text contained in this LayoutLine.

  • The result is a list to accommodate for mixed left-to-right and right-to-left text. Even if the text is not mixed, several ranges might be returned that are adjacent. The ranges are always sorted from left to right. The values are with respect to the left edge of the entire layout, not with respect to the line (which might be indented or not left aligned).
Produced by Haddock version 0.8