-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | Binding to the Pango text rendering engine.
--   
--   This package provides a wrapper around the Pango C library that allows
--   high-quality rendering of Unicode text. It can be used either with
--   Cairo to output text in PDF, PS or other documents or with Gtk+ to
--   display text on-screen.
@package pango
@version 0.13.3.1


-- | Enumerations for describing font characteristics.
module Graphics.Rendering.Pango.Enums
type PangoUnit = Double
pangoScale :: Double

-- | Color
--   
--   <ul>
--   <li>Specifies a color with three integer values for red, green and
--   blue. All values range from 0 (least intense) to 65535 (highest
--   intensity).</li>
--   </ul>
data Color
Color :: (Word16) -> (Word16) -> (Word16) -> Color

-- | Rectangle
--   
--   <ul>
--   <li>Specifies x, y, width and height</li>
--   </ul>
data Rectangle
Rectangle :: Int -> Int -> Int -> Int -> Rectangle

-- | Rectangles describing an area in <a>Double</a>s.
--   
--   <ul>
--   <li>Specifies x, y, width and height</li>
--   </ul>
data PangoRectangle
PangoRectangle :: Double -> Double -> Double -> Double -> PangoRectangle

-- | The characteristic measurements of a font.
--   
--   <ul>
--   <li>All values are measured in pixels.</li>
--   <li>In Pango versions before 1.6 only <a>ascent</a>, <a>descent</a>,
--   <a>approximateCharWidth</a> and <a>approximateDigitWidth</a> are
--   available.</li>
--   </ul>
data FontMetrics
FontMetrics :: Double -> Double -> Double -> Double -> Double -> Double -> Double -> Double -> FontMetrics

-- | The ascent is the distance from the baseline to the logical top of a
--   line of text. (The logical top may be above or below the top of the
--   actual drawn ink. It is necessary to lay out the text to figure where
--   the ink will be.)
[ascent] :: FontMetrics -> Double

-- | The descent is the distance from the baseline to the logical bottom of
--   a line of text. (The logical bottom may be above or below the bottom
--   of the actual drawn ink. It is necessary to lay out the text to figure
--   where the ink will be.)
[descent] :: FontMetrics -> Double

-- | The approximate character width. This is merely a representative value
--   useful, for example, for determining the initial size for a window.
--   Actual characters in text will be wider and narrower than this.
[approximateCharWidth] :: FontMetrics -> Double

-- | The approximate digit width. This is merely a representative value
--   useful, for example, for determining the initial size for a window.
--   Actual digits in text can be wider and narrower than this, though this
--   value is generally somewhat more accurate than
--   <a>approximateCharWidth</a>.
[approximateDigitWidth] :: FontMetrics -> Double

-- | The suggested thickness to draw an underline.
[underlineThickness] :: FontMetrics -> Double

-- | The suggested position to draw the underline. The value returned is
--   the distance above the baseline of the top of the underline. Since
--   most fonts have underline positions beneath the baseline, this value
--   is typically negative.
[underlinePosition] :: FontMetrics -> Double

-- | The suggested thickness to draw for the strikethrough.
[strikethroughThickness] :: FontMetrics -> Double

-- | The suggested position to draw the strikethrough. The value returned
--   is the distance above the baseline of the top of the strikethrough.
[strikethroughPosition] :: FontMetrics -> Double

-- | Define attributes for <tt>FontSize</tt>.
data Size
SizePoint :: Double -> Size
SizeUnreadable :: Size
SizeTiny :: Size
SizeSmall :: Size
SizeMedium :: Size
SizeLarge :: Size
SizeHuge :: Size
SizeGiant :: Size
SizeSmaller :: Size
SizeLarger :: Size

-- | The style of a font.
--   
--   <ul>
--   <li><a>StyleOblique</a> is a slanted font like <a>StyleItalic</a>, but
--   in a roman style.</li>
--   </ul>
data FontStyle
StyleNormal :: FontStyle
StyleOblique :: FontStyle
StyleItalic :: FontStyle

-- | Define attributes for <a>Weight</a>.
data Weight
WeightThin :: Weight
WeightUltralight :: Weight
WeightLight :: Weight
WeightSemilight :: Weight
WeightBook :: Weight
WeightNormal :: Weight
WeightMedium :: Weight
WeightSemibold :: Weight
WeightBold :: Weight
WeightUltrabold :: Weight
WeightHeavy :: Weight
WeightUltraheavy :: Weight

-- | The variant of a font.
--   
--   <ul>
--   <li>The <a>VariantSmallCaps</a> is a version of a font where lower
--   case letters are shown as physically smaller upper case letters.</li>
--   </ul>
data Variant
VariantNormal :: Variant
VariantSmallCaps :: Variant

-- | Define how wide characters are.
data Stretch
StretchUltraCondensed :: Stretch
StretchExtraCondensed :: Stretch
StretchCondensed :: Stretch
StretchSemiCondensed :: Stretch
StretchNormal :: Stretch
StretchSemiExpanded :: Stretch
StretchExpanded :: Stretch
StretchExtraExpanded :: Stretch
StretchUltraExpanded :: Stretch

-- | Define attributes for <a>Underline</a>.
--   
--   <ul>
--   <li>The squiggly underline for errors is only available in Gtk 2.4 and
--   higher.</li>
--   </ul>
data Underline
UnderlineNone :: Underline
UnderlineSingle :: Underline
UnderlineDouble :: Underline
UnderlineLow :: Underline
UnderlineError :: Underline

-- | The <a>PangoDirection</a> type represents a direction in the Unicode
--   bidirectional algorithm.
--   
--   <ul>
--   <li>The "weak" values denote a left-to-right or right-to-left
--   direction only if there is no character with a strong direction in a
--   paragraph. An example is a sequence of special, graphical characters
--   which are neutral with respect to their rendering direction. A fresh
--   <a>PangoContext</a> is by default weakly left-to-right.</li>
--   <li>Not every value in this enumeration makes sense for every usage of
--   <a>PangoDirection</a>; for example, the return value of
--   <tt>unicharDirection</tt> and <tt>findBaseDir</tt> cannot be
--   <a>PangoDirectionWeakLtr</a> or <a>PangoDirectionWeakRtl</a>, since
--   every character is either neutral or has a strong direction; on the
--   other hand <a>PangoDirectionNeutral</a> doesn't make sense to pass to
--   <tt>log2visGetEmbeddingLevels</tt>.</li>
--   </ul>
data PangoDirection
PangoDirectionLtr :: PangoDirection
PangoDirectionRtl :: PangoDirection
PangoDirectionWeakLtr :: PangoDirection
PangoDirectionWeakRtl :: PangoDirection
PangoDirectionNeutral :: PangoDirection

-- | Attributes for <a>PangoItem</a>s.
--   
--   <ul>
--   <li>A given attribute is applied from its start position
--   <a>paStart</a> up, but not including the end position,
--   <a>paEnd</a>.</li>
--   </ul>
data PangoAttribute

-- | A hint as to what language this piece of text is written in.
AttrLanguage :: Int -> Int -> Language -> PangoAttribute
[paStart] :: PangoAttribute -> Int
[paEnd] :: PangoAttribute -> Int
[paLang] :: PangoAttribute -> Language

-- | The font family, e.g. <tt>sans serif</tt>.
AttrFamily :: Int -> Int -> DefaultGlibString -> PangoAttribute
[paStart] :: PangoAttribute -> Int
[paEnd] :: PangoAttribute -> Int
[paFamily] :: PangoAttribute -> DefaultGlibString

-- | The slant of the current font.
AttrStyle :: Int -> Int -> FontStyle -> PangoAttribute
[paStart] :: PangoAttribute -> Int
[paEnd] :: PangoAttribute -> Int
[paStyle] :: PangoAttribute -> FontStyle

-- | Weight of font, e.g. <a>WeightBold</a>.
AttrWeight :: Int -> Int -> Weight -> PangoAttribute
[paStart] :: PangoAttribute -> Int
[paEnd] :: PangoAttribute -> Int
[paWeight] :: PangoAttribute -> Weight

-- | <a>VariantSmallCaps</a> will display lower case letters as small upper
--   case letters (if the font supports this).
AttrVariant :: Int -> Int -> Variant -> PangoAttribute
[paStart] :: PangoAttribute -> Int
[paEnd] :: PangoAttribute -> Int
[paVariant] :: PangoAttribute -> Variant

-- | Stretch or condense the width of the letters.
AttrStretch :: Int -> Int -> Stretch -> PangoAttribute
[paStart] :: PangoAttribute -> Int
[paEnd] :: PangoAttribute -> Int
[paStretch] :: PangoAttribute -> Stretch

-- | Specify the size of the font in points.
AttrSize :: Int -> Int -> Double -> PangoAttribute
[paStart] :: PangoAttribute -> Int
[paEnd] :: PangoAttribute -> Int
[paSize] :: PangoAttribute -> Double

-- | Specify the size of the font in device units (pixels).
--   
--   <ul>
--   <li>Available in Pango 1.8.0 and higher.</li>
--   </ul>
AttrAbsSize :: Int -> Int -> Double -> PangoAttribute
[paStart] :: PangoAttribute -> Int
[paEnd] :: PangoAttribute -> Int
[paSize] :: PangoAttribute -> Double

-- | Specify several attributes of a font at once. Note that no deep copy
--   of the description is made when this attributes is passed to or
--   received from functions.
AttrFontDescription :: Int -> Int -> FontDescription -> PangoAttribute
[paStart] :: PangoAttribute -> Int
[paEnd] :: PangoAttribute -> Int
[paFontDescription] :: PangoAttribute -> FontDescription

-- | Specify the foreground color.
AttrForeground :: Int -> Int -> Color -> PangoAttribute
[paStart] :: PangoAttribute -> Int
[paEnd] :: PangoAttribute -> Int
[paColor] :: PangoAttribute -> Color

-- | Specify the background color.
AttrBackground :: Int -> Int -> Color -> PangoAttribute
[paStart] :: PangoAttribute -> Int
[paEnd] :: PangoAttribute -> Int
[paColor] :: PangoAttribute -> Color

-- | Specify the kind of underline, e.g. <a>UnderlineSingle</a>.
AttrUnderline :: Int -> Int -> Underline -> PangoAttribute
[paStart] :: PangoAttribute -> Int
[paEnd] :: PangoAttribute -> Int
[paUnderline] :: PangoAttribute -> Underline

-- | Specify the color of an underline.
--   
--   <ul>
--   <li>Available in Pango 1.8.0 and higher.</li>
--   </ul>
AttrUnderlineColor :: Int -> Int -> Color -> PangoAttribute
[paStart] :: PangoAttribute -> Int
[paEnd] :: PangoAttribute -> Int
[paColor] :: PangoAttribute -> Color

-- | Specify if this piece of text should have a line through it.
AttrStrikethrough :: Int -> Int -> Bool -> PangoAttribute
[paStart] :: PangoAttribute -> Int
[paEnd] :: PangoAttribute -> Int
[paStrikethrough] :: PangoAttribute -> Bool

-- | Specify the color of the strike through line.
--   
--   <ul>
--   <li>Available in Pango 1.8.0 and higher.</li>
--   </ul>
AttrStrikethroughColor :: Int -> Int -> Color -> PangoAttribute
[paStart] :: PangoAttribute -> Int
[paEnd] :: PangoAttribute -> Int
[paColor] :: PangoAttribute -> Color

-- | Displace the text vertically. Positive values move the text upwards.
AttrRise :: Int -> Int -> Double -> PangoAttribute
[paStart] :: PangoAttribute -> Int
[paEnd] :: PangoAttribute -> Int
[paRise] :: PangoAttribute -> Double

-- | Restrict the amount of what is drawn of the marked shapes.
--   
--   <ul>
--   <li>Available in Pango 1.8.0 and higher.</li>
--   </ul>
AttrShape :: Int -> Int -> PangoRectangle -> PangoRectangle -> PangoAttribute
[paStart] :: PangoAttribute -> Int
[paEnd] :: PangoAttribute -> Int
[paInk] :: PangoAttribute -> PangoRectangle
[paLogical] :: PangoAttribute -> PangoRectangle

-- | Scale the font up (values greater than one) or shrink the font.
AttrScale :: Int -> Int -> Double -> PangoAttribute
[paStart] :: PangoAttribute -> Int
[paEnd] :: PangoAttribute -> Int
[paScale] :: PangoAttribute -> Double

-- | Determine if a fall back font should be substituted if no matching
--   font is available.
AttrFallback :: Int -> Int -> Bool -> PangoAttribute
[paStart] :: PangoAttribute -> Int
[paEnd] :: PangoAttribute -> Int
[paFallback] :: PangoAttribute -> Bool

-- | Add extra space between graphemes of the text.
--   
--   <ul>
--   <li>Available in Pango 1.6.0 and higher.</li>
--   </ul>
AttrLetterSpacing :: Int -> Int -> Double -> PangoAttribute
[paStart] :: PangoAttribute -> Int
[paEnd] :: PangoAttribute -> Int
[paLetterSpacing] :: PangoAttribute -> Double

-- | Sets the gravity field of a font description. The gravity field
--   specifies how the glyphs should be rotated. If gravity is
--   <tt>GravityAuto</tt>, this actually unsets the gravity mask on the
--   font description.
--   
--   <ul>
--   <li>This function is seldom useful to the user. Gravity should
--   normally be set on a <a>PangoContext</a>.</li>
--   <li>Available in Pango 1.16.0 and higher.</li>
--   </ul>
AttrGravity :: Int -> Int -> PangoGravity -> PangoAttribute
[paStart] :: PangoAttribute -> Int
[paEnd] :: PangoAttribute -> Int
[paGravity] :: PangoAttribute -> PangoGravity

-- | Set the way horizontal scripts behave in a vertical context.
--   
--   <ul>
--   <li>Available in Pango 1.16.0 and higher.</li>
--   </ul>
AttrGravityHint :: Int -> Int -> PangoGravityHint -> PangoAttribute
[paStart] :: PangoAttribute -> Int
[paEnd] :: PangoAttribute -> Int
[paGravityHint] :: PangoAttribute -> PangoGravityHint

-- | The <a>EllipsizeMode</a> 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.
data EllipsizeMode
EllipsizeNone :: EllipsizeMode
EllipsizeStart :: EllipsizeMode
EllipsizeMiddle :: EllipsizeMode
EllipsizeEnd :: EllipsizeMode

-- | The <a>PangoGravity</a> type represents the orientation of glyphs in a
--   segment of text. The value <tt>GravitySouth</tt>, for instance,
--   indicates that the text stands upright, i.e. that the base of the
--   letter is directed downwards.
--   
--   This is useful when rendering vertical text layouts. In those
--   situations, the layout is rotated using a non-identity
--   <tt>PangoMatrix</tt>, and then glyph orientation is controlled using
--   <a>PangoGravity</a>. Not every value in this enumeration makes sense
--   for every usage of <tt>Gravity</tt>; for example,
--   <a>PangoGravityAuto</a> only can be passed to
--   <tt>pangoContextSetBaseGravity</tt> and can only be returned by
--   <tt>pangoContextGetBaseGravity</tt>.
--   
--   <ul>
--   <li>See also: <a>PangoGravityHint</a></li>
--   <li>Gravity is resolved from the context matrix.</li>
--   <li>Since Pango 1.16</li>
--   </ul>
data PangoGravity
PangoGravitySouth :: PangoGravity
PangoGravityEast :: PangoGravity
PangoGravityNorth :: PangoGravity
PangoGravityWest :: PangoGravity
PangoGravityAuto :: PangoGravity

-- | The <a>PangoGravityHint</a> defines how horizontal scripts should
--   behave in a vertical context.
--   
--   <ul>
--   <li><a>PangoGravityHintNatural</a>: scripts will take their natural
--   gravity based on the base gravity and the script. This is the
--   default.</li>
--   <li><a>PangoGravityHintStrong</a>: always use the base gravity set,
--   regardless of the script.</li>
--   <li><a>PangoGravityHintLine</a>: for scripts not in their natural
--   direction (eg. Latin in East gravity), choose per-script gravity such
--   that every script respects the line progression. This means, Latin and
--   Arabic will take opposite gravities and both flow top-to-bottom for
--   example.</li>
--   </ul>
data PangoGravityHint
PangoGravityHintNatural :: PangoGravityHint
PangoGravityHintStrong :: PangoGravityHint
PangoGravityHintLine :: PangoGravityHint

-- | An RFC-3066 language designator to choose scripts.
data Language

-- | Specifying no particular language.
emptyLanguage :: Language

-- | Take a RFC-3066 format language tag as a string and convert it to a
--   <a>Language</a> type that can be efficiently passed around and
--   compared with other language tags.
--   
--   <ul>
--   <li>This function first canonicalizes the string by converting it to
--   lowercase, mapping '_' to '-', and stripping all characters other than
--   letters and '-'.</li>
--   </ul>
languageFromString :: GlibString string => string -> IO Language
instance GHC.Show.Show Graphics.Rendering.Pango.Enums.FontMetrics
instance GHC.Classes.Eq Graphics.Rendering.Pango.Enums.EllipsizeMode
instance GHC.Enum.Enum Graphics.Rendering.Pango.Enums.EllipsizeMode
instance GHC.Show.Show Graphics.Rendering.Pango.Enums.Size


-- | This module defines <a>PangoContext</a>s, an environment that provides
--   information on available fonts, internationalization and output
--   capabilities of the medium. Given such a context, text can be rendered
--   into strings of glyphs (see <a>Rendering</a>) or, at a more abstract
--   level, using layouts (see <a>Layout</a>).
--   
--   <ul>
--   <li>A <a>PangoContext</a> is a prerequisite for all text rendering
--   functions. A context can be created from scratch or, more
--   conveniently, by using default settings that are already used in the
--   application. When text is rendered through Gdk, use
--   <a>widgetCreatePangoContext</a>, if you use the Cairo rendering
--   engine, a new context can be acquired using
--   <a>cairoCreateContext</a>.</li>
--   <li>The properties of a <a>PangoContext</a> can be changed which, in
--   turn, has an effect on how text is rendered. To reflect such a change
--   in the rendered text, call <a>layoutContextChanged</a>.</li>
--   </ul>
module Graphics.Rendering.Pango.Context
data PangoContext
class GObjectClass o => PangoContextClass o

-- | Retrieve a list of all available font families.
--   
--   <ul>
--   <li>A font family is the name of the font without further attributes
--   like slant, variant or size.</li>
--   </ul>
contextListFamilies :: PangoContext -> IO [FontFamily]

-- | Query the metrics of the given font implied by the font description.
contextGetMetrics :: PangoContext -> FontDescription -> Language -> IO FontMetrics

-- | Set the default <a>FontDescription</a> of this context.
contextSetFontDescription :: PangoContext -> FontDescription -> IO ()

-- | Get the current <a>FontDescription</a> of this context.
contextGetFontDescription :: PangoContext -> IO FontDescription

-- | An RFC-3066 language designator to choose scripts.
data Language

-- | Specifying no particular language.
emptyLanguage :: Language

-- | Take a RFC-3066 format language tag as a string and convert it to a
--   <a>Language</a> type that can be efficiently passed around and
--   compared with other language tags.
--   
--   <ul>
--   <li>This function first canonicalizes the string by converting it to
--   lowercase, mapping '_' to '-', and stripping all characters other than
--   letters and '-'.</li>
--   </ul>
languageFromString :: GlibString string => string -> IO Language

-- | Set the default <a>Language</a> of this context.
contextSetLanguage :: PangoContext -> Language -> IO ()

-- | Get the current <a>Language</a> of this context.
contextGetLanguage :: PangoContext -> IO Language

-- | Set the default text direction of this context.
contextSetTextDir :: PangoContext -> PangoDirection -> IO ()

-- | Get the current text direction of this context.
contextGetTextDir :: PangoContext -> IO PangoDirection

-- | Set the text gravity of this context. If the given value is
--   <a>PangoGravityAuto</a> then the gravity is derived from the current
--   rotation matrix.
contextSetTextGravity :: PangoContext -> PangoGravity -> IO ()

-- | Get the current text gravity of this context.
contextGetTextGravity :: PangoContext -> IO PangoGravity

-- | Set the text gravity hint of this context.
contextSetTextGravityHint :: PangoContext -> PangoGravityHint -> IO ()

-- | Get the current text gravity of this context.
contextGetTextGravityHint :: PangoContext -> IO PangoGravityHint

-- | Gets the transformation matrix that will be applied when rendering
--   with this context.
--   
--   <ul>
--   <li>Since Pango 1.6</li>
--   </ul>
contextGetMatrix :: PangoContext -> IO Matrix

-- | Sets the transformation matrix that will be applied when rendering
--   with this context. Note that any metrics reported by other functions
--   are in user space coordinates before the application of the matrix,
--   not device-space coordinates after the application of the matrix. So,
--   they don't scale with the matrix, though they may change slightly for
--   different matrices, depending on how the text is fit to the pixel
--   grid.
--   
--   <ul>
--   <li>Since Pango 1.6</li>
--   </ul>
contextSetMatrix :: PangoContext -> Matrix -> IO ()


-- | Fonts. The selection of an appropriate font to render text becomes a
--   substantial task in the presence of Unicode where a single font does
--   not cover the whole range of possible characters. Pango provides
--   several concepts to find appropriate fonts and to query information
--   about them:
--   
--   <ul>
--   <li><a>FontDescription</a>: Font descriptions provide a way to query
--   and state requirements on fonts. This data structure has several
--   fields describing different characteristics of a font. Each of these
--   fields can be set of left unspecified.</li>
--   <li><a>FontMap</a> : A font map represents the set of fonts available
--   for a particular rendering system. In particular this map defines the
--   relation between font size and pixel size in terms of the output
--   medium.</li>
--   <li><a>FontFamily</a> : A font family represents a set of fonts that
--   have related faces, that is, their faces share a common design, but
--   differ in slant, weight, width and other aspects.</li>
--   <li><a>FontFace</a>: A face is a specific font where all
--   characteristics are fixed except for the size.</li>
--   <li><a>Font</a>: A font in the underlying rendering system.</li>
--   <li><a>FontMetrics</a>: Information about the font that will be used
--   to render a specific <tt>Context</tt> or <a>PangoItem</a>.</li>
--   </ul>
module Graphics.Rendering.Pango.Font

-- | A possibly partial description of font(s).
data FontDescription

-- | Create a new font description.
--   
--   <ul>
--   <li>All field are unset.</li>
--   </ul>
fontDescriptionNew :: IO FontDescription

-- | Make a deep copy of a font description.
fontDescriptionCopy :: FontDescription -> IO FontDescription

-- | Set the font famliy.
--   
--   <ul>
--   <li>A font family is a name designating the design of the font (e.g.
--   Sans or Times) without the variant.</li>
--   <li>In some contexts a comma separated list of font families can be
--   used.</li>
--   </ul>
fontDescriptionSetFamily :: GlibString string => FontDescription -> string -> IO ()

-- | Get the font family.
--   
--   <ul>
--   <li><a>Nothing</a> is returned if the font family is not set.</li>
--   </ul>
fontDescriptionGetFamily :: GlibString string => FontDescription -> IO (Maybe string)
fontDescriptionSetStyle :: FontDescription -> FontStyle -> IO ()

-- | Get the style field.
fontDescriptionGetStyle :: FontDescription -> IO (Maybe FontStyle)

-- | Set the variant field.
fontDescriptionSetVariant :: FontDescription -> Variant -> IO ()

-- | Get the variant field.
fontDescriptionGetVariant :: FontDescription -> IO (Maybe Variant)

-- | Set the weight field.
fontDescriptionSetWeight :: FontDescription -> Weight -> IO ()

-- | Get the weight field.
fontDescriptionGetWeight :: FontDescription -> IO (Maybe Weight)

-- | Set the stretch field.
fontDescriptionSetStretch :: FontDescription -> Stretch -> IO ()

-- | Get the stretch field.
fontDescriptionGetStretch :: FontDescription -> IO (Maybe Stretch)

-- | Set the size field.
--   
--   <ul>
--   <li>The given size is in points (pts). One point is 1/72 inch.</li>
--   </ul>
fontDescriptionSetSize :: FontDescription -> Double -> IO ()

-- | Get the size field.
fontDescriptionGetSize :: FontDescription -> IO (Maybe Double)

-- | Flags denoting which fields in a font description are set.
data FontMask
PangoFontMaskFamily :: FontMask
PangoFontMaskStyle :: FontMask
PangoFontMaskVariant :: FontMask
PangoFontMaskWeight :: FontMask
PangoFontMaskStretch :: FontMask
PangoFontMaskSize :: FontMask
PangoFontMaskGravity :: FontMask

-- | Reset fields in a font description.
fontDescriptionUnsetFields :: FontDescription -> [FontMask] -> IO ()

-- | Merge two font descriptions.
--   
--   <ul>
--   <li>Copy fields from the second description to the first. If the
--   boolean parameter is set, existing fields in the first description
--   will be replaced.</li>
--   </ul>
fontDescriptionMerge :: FontDescription -> FontDescription -> Bool -> IO ()

-- | Determine which of two descriptions matches a given description
--   better.
--   
--   <ul>
--   <li>Returns <tt>True</tt> if the last description is a better match to
--   the first arguement than the middle one.</li>
--   <li>Approximate matching is done on weight and style. If the other
--   attributes do not match, the function returns <tt>False</tt>.</li>
--   </ul>
fontDescriptionBetterMatch :: FontDescription -> FontDescription -> FontDescription -> Bool

-- | Create a font description from a string.
--   
--   <ul>
--   <li>The given argument must have the form <tt>[FAMILY-LIST]
--   [STYLE-OPTIONS] [SIZE]</tt> where <tt>FAMILY_LIST</tt> is a comma
--   separated list of font families optionally terminated by a comma,
--   <tt>STYLE_OPTIONS</tt> is a whitespace separated list of words where
--   each word describes one of style, variant, weight or stretch.
--   <tt>SIZE</tt> is a decimal number giving the size of the font in
--   points. If any of these fields is absent, the resulting
--   <a>FontDescription</a> will have the corresponing fields unset.</li>
--   </ul>
fontDescriptionFromString :: GlibString string => string -> IO FontDescription

-- | Convert a font description to a string.
--   
--   <ul>
--   <li>Creates a string representation of a font description. See
--   <a>fontDescriptionFromString</a> for the format of the string.</li>
--   </ul>
fontDescriptionToString :: GlibString string => FontDescription -> IO string
data FontMap
class GObjectClass o => FontMapClass o

-- | Ask for the different font families that a particular back-end
--   supports.
--   
--   <ul>
--   <li>The <a>FontMap</a> can be acquired by calling
--   <a>cairoFontMapGetDefault</a>.</li>
--   </ul>
pangoFontMapListFamilies :: FontMap -> IO [FontFamily]
data FontFamily
class GObjectClass o => FontFamilyClass o

-- | Ask if the given family contains monospace fonts.
--   
--   <ul>
--   <li>A monospace font is a font designed for text display where the
--   characters form a regular grid. For Western languages this would mean
--   that the advance width of all characters are the same, but this
--   categorization also includes Asian fonts which include double-width
--   characters: characters that occupy two grid cells.</li>
--   <li>The best way to find out the grid-cell size is to query the
--   members of the according <a>FontMetrics</a> structure.</li>
--   </ul>
pangoFontFamilyIsMonospace :: FontFamily -> Bool

-- | Ask for the faces contained in a particular family.
--   
--   <ul>
--   <li>Asks for all font faces in the given family. The faces in a family
--   share a common design, but differ in slant, weight, width and other
--   aspects. For example, the font family <a>Sans</a> contains several
--   fonts such as Helvetica and Arial.</li>
--   </ul>
pangoFontFamilyListFaces :: FontFamily -> IO [FontFace]
data FontFace
class GObjectClass o => FontFaceClass o

-- | Ask for available sizes of this font face.
--   
--   <ul>
--   <li>List the available sizes for a font. This is only applicable to
--   bitmap fonts since all other fonts can be scaled arbitrarily. For
--   scalable fonts, this function returns <tt>Nothing</tt>. The sizes
--   returned are in ascending order, their unit is points (1/72
--   inch).</li>
--   </ul>
pangoFontFaceListSizes :: FontFace -> IO (Maybe [Double])

-- | Ask for a description of this face.
--   
--   <ul>
--   <li>Returns the family, style, variant, weight and stretch of a
--   <a>FontFace</a>. The size field of the resulting font description will
--   be unset.</li>
--   </ul>
pangoFontFaceDescribe :: FontFace -> IO FontDescription
data Font
class GObjectClass o => FontClass o
instance GHC.Show.Show Graphics.Rendering.Pango.Types.FontFamily
instance GHC.Show.Show Graphics.Rendering.Pango.Types.FontFace


-- | This module defines some helper functions for generating texts with
--   embedded attributes. Note that there is no need to use these
--   functions. In particular, if you set markup in labels that are subject
--   to internationalization, it can be of advantage to write out the
--   markup instead of using the functions in this module.
--   
--   In order to display a string that may contain markup characters, use
--   <a>escapeMarkup</a>.
--   
--   When you write markup directly, you can make use of the following
--   convenience tags:
--   
--   <ul>
--   <li><i><tt>b</tt></i> Bold</li>
--   <li><i><tt>big</tt></i> Makes font relatively larger</li>
--   <li><i><tt>i</tt></i> Italic</li>
--   <li><i><tt>s</tt></i> Strikethrough</li>
--   <li><i><tt>sub</tt></i> Subscript</li>
--   <li><i><tt>sup</tt></i> Superscript</li>
--   <li><i><tt>small</tt></i> Makes font relatively smaller</li>
--   <li><i><tt>tt</tt></i> Monospace font</li>
--   <li><i><tt>u</tt></i> Underline</li>
--   </ul>
module Graphics.Rendering.Pango.Markup

-- | These are all the attributes the <a>markSpan</a> function can express.
data SpanAttribute

-- | Choose a font by textual description.
--   
--   <ul>
--   <li>Takes a string to completely describe the font, example:
--   <tt>FontDescr</tt> "Sans Italic 12"</li>
--   </ul>
FontDescr :: String -> SpanAttribute

-- | Specify the family of font to use.
--   
--   <ul>
--   <li>Example: <tt>FontFamily</tt> "Sans"</li>
--   </ul>
FontFamily :: String -> SpanAttribute

-- | Change the size of the current font.
--   
--   <ul>
--   <li>The constuctor takes the size in points (pt) or a predefined
--   sizes. Setting the absolute size 12.5pt can be achieved by passing
--   <a>FontSize</a> (<tt>SizePoint</tt> 12.5) to <a>markSpan</a>. Next to
--   predefined absolute sizes such as <a>SizeSmall</a> the size can be
--   changed by asking for the next larger or smaller front with
--   <a>SizeLarger</a> and <a>SizeSmaller</a>, respectively.</li>
--   </ul>
FontSize :: Size -> SpanAttribute

-- | Change the slant of the current font.
FontStyle :: FontStyle -> SpanAttribute

-- | Change the thickness of the current font.
--   
--   <ul>
--   <li>The constructor takes one of the six predefined weights. Most
--   likely to be supported: <a>WeightBold</a>.</li>
--   </ul>
FontWeight :: Weight -> SpanAttribute

-- | Choosing an alternative rendering for lower case letters.
--   
--   <ul>
--   <li>The argument <a>VariantSmallCaps</a> will display lower case
--   letters as smaller upper case letters, if this option is
--   available.</li>
--   </ul>
FontVariant :: Variant -> SpanAttribute

-- | Choose a different width.
--   
--   <ul>
--   <li>Takes one of nine font widths, e.g. <a>WidthExpanded</a>.</li>
--   </ul>
FontStretch :: Stretch -> SpanAttribute

-- | Foreground color.
--   
--   <ul>
--   <li>This constructor and <a>FontBackground</a> take both a description
--   of the color to be used for rendering. The name is either a hex code
--   of the form "#RRGGBB" or an X11 color name like "dark olive
--   green".</li>
--   </ul>
FontForeground :: String -> SpanAttribute

-- | Background color.
FontBackground :: String -> SpanAttribute

-- | Specify underlining of text.
FontUnderline :: Underline -> SpanAttribute

-- | Specify a vertical displacement.
--   
--   <ul>
--   <li>Takes the vertical displacement in em (the width of the 'm'
--   character in the current font).</li>
--   </ul>
FontRise :: Double -> SpanAttribute

-- | Give a hint about the language to be displayed.
--   
--   <ul>
--   <li>This hint might help the system rendering a particular piece of
--   text with different fonts that are more suitable for the given
--   language.</li>
--   </ul>
FontLang :: Language -> SpanAttribute

-- | Gravity of text, use for ratation.
FontGravity :: PangoGravity -> SpanAttribute

-- | Intensity of gravity.
FontGravityHint :: PangoGravityHint -> SpanAttribute

-- | Create the most generic span attribute.
markSpan :: [SpanAttribute] -> String -> String

-- | Parse the marked-up text (see <a>Markup</a> format) to create a
--   plain-text string and an attribute list.
--   
--   <ul>
--   <li>The attribute list is a list of lists of attribute. Each list
--   describes the attributes for the same span.</li>
--   <li>If <tt>accelMarker</tt> is not <tt>'\0'</tt> (a zero character),
--   the given character will mark the character following it as an
--   accelerator. For example, <tt>accelMarker</tt> might be an ampersand
--   or underscore. All characters marked as an accelerator will receive a
--   <a>UnderlineLow</a> attribute, and the first character so marked will
--   be returned as <tt>accelChar</tt>. If no accelerator character is
--   found, the <tt>accelMarker</tt> character itself is returned. Two
--   <tt>accelMarker</tt> characters following each other produce a single
--   literal <tt>accelMarker</tt> character.</li>
--   <li>If a parsing error occurs a <a>GError</a> is thrown.</li>
--   </ul>
parseMarkup :: (GlibString markup, GlibString string) => markup -> Char -> IO ([[PangoAttribute]], Char, string)
instance GHC.Show.Show Graphics.Rendering.Pango.Markup.SpanAttribute


-- | Functions to run the rendering pipeline.
--   
--   <ul>
--   <li>This module provides elementary rendering functions. For a simpler
--   interface, consider using <a>PangoLayout</a>s.</li>
--   <li>The Pango rendering pipeline takes a string of Unicode characters,
--   divides them into sequences of letters that have the same
--   characteristics such as font, size, color, etc. Such a sequence is
--   called <a>PangoItem</a>. Each <a>PangoItem</a> is then converted into
--   one <a>GlyphItem</a>, that is an actual sequence of glyphs, where
--   several characters might be turned into legatures or clusters, e.g. an
--   "e" and an accent modifier are turned into a single glyph. These
--   <a>GlyphItem</a>s can then be rendered onto the output device with
--   functions such as <a>cairoShowGlyphString</a>.</li>
--   </ul>
module Graphics.Rendering.Pango.Rendering

-- | A sequence of characters that are rendered with the same settings.
--   
--   <ul>
--   <li>A preprocessing stage done by <tt>itemize</tt> splits the input
--   text into several chunks such that each chunk can be rendered with the
--   same font, direction, slant, etc. Some attributes such as the color,
--   underline or strikethrough do not affect a break into several
--   <a>PangoItem</a>s. See also <a>GlyphItem</a>.</li>
--   </ul>
data PangoItem

-- | Turn a string into a sequence of glyphs.
--   
--   <ul>
--   <li>Partitions the input string into segments with the same text
--   direction and shaping engine. The generated list of items will be in
--   logical order (the start offsets of the items are ascending).</li>
--   </ul>
pangoItemize :: GlibString string => PangoContext -> string -> [PangoAttribute] -> IO [PangoItem]

-- | Retrieve the metrics of the font that was chosen to break the given
--   <a>PangoItem</a>.
pangoItemGetFontMetrics :: PangoItem -> IO FontMetrics

-- | Extract the font used for this <a>PangoItem</a>.
pangoItemGetFont :: PangoItem -> IO Font

-- | Extract the <a>Language</a> used for this <a>PangoItem</a>.
pangoItemGetLanguage :: PangoItem -> IO Language

-- | A sequence of glyphs for a chunk of a string.
--   
--   <ul>
--   <li>A glyph item contains the graphical representation of a
--   <a>PangoItem</a>. Clusters (like <tt>e</tt> and an accent modifier) as
--   well as legatures (such as <tt>ffi</tt> turning into a single letter
--   that omits the dot over the <tt>i</tt>) are usually represented as a
--   single glyph.</li>
--   </ul>
data GlyphItem

-- | Turn a <a>PangoItem</a> into a <a>GlyphItem</a>.
--   
--   <ul>
--   <li>Turns a <a>PangoItem</a>, that is, sequence of characters with the
--   same attributes such as font, size and color, into a <a>GlyphItem</a>
--   which contains the graphical representation of these characters.
--   <a>GlyphItem</a>s can be rendered directly (and several times) onto
--   screens.</li>
--   </ul>
pangoShape :: PangoItem -> IO GlyphItem

-- | Ask for bounding rectangles of this glyph sequence.
--   
--   <ul>
--   <li>Compute the ink and logical extents of a glyph string. The logical
--   size 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 than the logical size.</li>
--   </ul>
glyphItemExtents :: GlyphItem -> IO (PangoRectangle, PangoRectangle)

-- | Ask for bounding rectangles for a sub-range of a glyph sequence.
--   
--   <ul>
--   <li>The returned rectangles are relative to the given sub-range, that
--   is, the result of this function is the same as if
--   <a>glyphItemExtents</a> were called on the sub-string.</li>
--   </ul>
glyphItemExtentsRange :: GlyphItem -> Int -> Int -> IO (PangoRectangle, PangoRectangle)

-- | Get the horizontal position of a character.
--   
--   <ul>
--   <li>Clusters (e.g. "e" with an accent modifier) are divided up into
--   equal portions.</li>
--   </ul>
glyphItemIndexToX :: GlyphItem -> Int -> Bool -> IO Double

-- | Get the character at the given horizontal position.
--   
--   <ul>
--   <li>The position is clipped to the width of this line.</li>
--   <li>The function returns the position in the string that corresponds
--   to the given horizontal location. Furthermore, if the position lies on
--   the first half of the character, <tt>False</tt> is returned.</li>
--   </ul>
glyphItemXToIndex :: GlyphItem -> Double -> IO (Int, Bool)

-- | Retrieve the width of every character in a string.
--   
--   <ul>
--   <li>The boolean parameter determines if the returned array starts with
--   the leftmost glyph (<tt>False</tt>) or with the rightmost glyph
--   (<tt>True</tt>). If <tt>Nothing</tt> is passed in, the direction is
--   taken from the <a>GlyphItem</a>, i.e., the array starts with the
--   leftmost glyph for left-to-rigth text and with the rightmost glyph for
--   right-to-left text. When multiple characters compose a single glyph,
--   the width of this glyph is divided among the characters that compose
--   this cluster.</li>
--   </ul>
glyphItemGetLogicalWidths :: GlyphItem -> Maybe Bool -> IO [Double]

-- | Split a <a>GlyphItem</a> at the given index.
--   
--   <ul>
--   <li>The given <a>GlyphItem</a> is split at the given index. The index
--   must be at least one and not greater or equal to length, i.e. the item
--   must be split into two non-empty segments. The function throws an
--   <a>ArrayException</a> if the index is out of bounds.</li>
--   </ul>
glyphItemSplit :: GlyphItem -> Int -> IO (GlyphItem, GlyphItem)


-- | Functions to run the rendering pipeline.
--   
--   <ul>
--   <li>The <a>PangoLayout</a> object defined in this module contain a
--   rendered paragraph of text. This interface is the easiest way to
--   render text into a <a>DrawWindow</a> using Cairo.</li>
--   </ul>
module Graphics.Rendering.Pango.Layout

-- | Rectangles describing an area in <a>Double</a>s.
--   
--   <ul>
--   <li>Specifies x, y, width and height</li>
--   </ul>
data PangoRectangle
PangoRectangle :: Double -> Double -> Double -> Double -> PangoRectangle

-- | A rendered paragraph.
data PangoLayout

-- | Create an empty <tt>Layout</tt>.
layoutEmpty :: PangoContext -> IO PangoLayout

-- | Create a new layout.
layoutText :: GlibString string => PangoContext -> string -> IO PangoLayout

-- | Create a copy of the <tt>Layout</tt>.
layoutCopy :: PangoLayout -> IO PangoLayout

-- | Retrieves the <a>PangoContext</a> from this layout.
layoutGetContext :: PangoLayout -> IO PangoContext

-- | Signal a <a>PangoContext</a> change.
--   
--   <ul>
--   <li>Forces recomputation of any state in the <a>PangoLayout</a> 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.</li>
--   </ul>
layoutContextChanged :: PangoLayout -> IO ()

-- | Set the string in the layout.
layoutSetText :: GlibString string => PangoLayout -> string -> IO ()

-- | Retrieve the string in the layout.
layoutGetText :: GlibString string => PangoLayout -> IO string

-- | Set the text of the layout, including attributes.
--   
--   The string may include <tt>Markup</tt>. To print markup characters
--   like <tt>'&lt;'</tt>, or <tt>'-'</tt>, apply <a>escapeMarkup</a> to
--   the string first.
--   
--   The function returns the text that is actually shown.
layoutSetMarkup :: (GlibString markup, GlibString string) => PangoLayout -> markup -> IO string

-- | Escape markup characters.
--   
--   <ul>
--   <li>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.</li>
--   </ul>
escapeMarkup :: GlibString string => string -> string

-- | Set the string in the layout.
--   
--   <ul>
--   <li>The string may include <tt>Markup</tt>. 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.</li>
--   <li>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.</li>
--   </ul>
layoutSetMarkupWithAccel :: (GlibString markup, GlibString string) => PangoLayout -> markup -> IO (Char, string)

-- | Set text attributes of the text in the layout.
--   
--   <ul>
--   <li>This function replaces any text attributes that this layout
--   contained, even those that were set by using
--   <a>layoutSetMarkup</a>.</li>
--   </ul>
layoutSetAttributes :: PangoLayout -> [PangoAttribute] -> IO ()

-- | Gets the list of attributes of the layout, if any.
--   
--   <ul>
--   <li>The attribute list is a list of lists of attribute. Each list
--   describes the attributes for the same span.</li>
--   </ul>
layoutGetAttributes :: PangoLayout -> IO [[PangoAttribute]]

-- | Set a specific font description for this layout.
--   
--   <ul>
--   <li>Specifying <tt>Nothing</tt> will unset the current font
--   description, that is, the <a>PangoLayout</a> will use the font
--   description in the current <a>PangoContext</a>.</li>
--   </ul>
layoutSetFontDescription :: PangoLayout -> Maybe FontDescription -> IO ()

-- | Ask for the specifically set font description of this layout.
--   
--   <ul>
--   <li>Returns <tt>Nothing</tt> if this layout uses the font description
--   in the <a>PangoContext</a> it was created in.</li>
--   <li>Only available in Pango 1.8.0 or higher.</li>
--   </ul>
layoutGetFontDescription :: PangoLayout -> IO (Maybe FontDescription)

-- | Set the width of this paragraph.
--   
--   <ul>
--   <li>Sets the width to which the lines of the <a>PangoLayout</a> should
--   be wrapped.</li>
--   <li>Pass in <tt>Nothing</tt> to indicate that no wrapping is to be
--   performed.</li>
--   </ul>
layoutSetWidth :: PangoLayout -> Maybe Double -> IO ()

-- | Gets the width of this paragraph.
--   
--   <ul>
--   <li>Gets the width to which the lines of the <a>PangoLayout</a> should
--   be wrapped.</li>
--   <li>Returns is the current width, or <tt>Nothing</tt> to indicate that
--   no wrapping is performed.</li>
--   </ul>
layoutGetWidth :: PangoLayout -> IO (Maybe Double)

-- | Enumerates how a line can be wrapped.
--   
--   <ul>
--   <li><i><tt>WrapWholeWords</tt></i> Breaks lines only between
--   words.</li>
--   </ul>
--   
--   <ul>
--   <li>This variant does not guarantee that the requested width is not
--   exceeded. A word that is longer than the paragraph width is not
--   split.</li>
--   </ul>
--   
--   <ul>
--   <li><i><tt>WrapAnywhere</tt></i> Break lines anywhere.</li>
--   <li><i><tt>WrapPartialWords</tt></i> Wrap within a word if it is the
--   only one on this line.</li>
--   </ul>
--   
--   <ul>
--   <li>This option acts like <a>WrapWholeWords</a> but will split a word
--   if it is the only one on this line and it exceeds the specified
--   width.</li>
--   </ul>
data LayoutWrapMode
WrapWholeWords :: LayoutWrapMode
WrapAnywhere :: LayoutWrapMode
WrapPartialWords :: LayoutWrapMode

-- | Set how this paragraph is wrapped.
--   
--   <ul>
--   <li>Sets the wrap style; the wrap style only has an effect if a width
--   is set on the layout with <a>layoutSetWidth</a>. To turn off wrapping,
--   call <a>layoutSetWidth</a> with <tt>Nothing</tt>.</li>
--   </ul>
layoutSetWrap :: PangoLayout -> LayoutWrapMode -> IO ()

-- | Get the wrap mode for the layout.
layoutGetWrap :: PangoLayout -> IO LayoutWrapMode

-- | The <a>EllipsizeMode</a> 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.
data EllipsizeMode
EllipsizeNone :: EllipsizeMode
EllipsizeStart :: EllipsizeMode
EllipsizeMiddle :: EllipsizeMode
EllipsizeEnd :: EllipsizeMode

-- | Set how long lines should be abbreviated.
layoutSetEllipsize :: PangoLayout -> EllipsizeMode -> IO ()

-- | Get the ellipsize mode for this layout.
layoutGetEllipsize :: PangoLayout -> IO EllipsizeMode

-- | Set the indentation of this paragraph.
--   
--   <ul>
--   <li>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.</li>
--   </ul>
layoutSetIndent :: PangoLayout -> Double -> IO ()

-- | Gets the indentation of this paragraph.
--   
--   <ul>
--   <li>Gets the amount by which the first line or the rest of the
--   paragraph is indented.</li>
--   </ul>
layoutGetIndent :: PangoLayout -> IO Double

-- | Set the spacing between lines of this paragraph.
layoutSetSpacing :: PangoLayout -> Double -> IO ()

-- | Gets the spacing between the lines.
layoutGetSpacing :: PangoLayout -> IO Double

-- | Set if text should be streched to fit width.
--   
--   <ul>
--   <li>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.</li>
--   <li>Note that as of Pango 1.4, this functionality is not yet
--   implemented.</li>
--   </ul>
layoutSetJustify :: PangoLayout -> Bool -> IO ()

-- | Retrieve the justification flag.
--   
--   <ul>
--   <li>See <a>layoutSetJustify</a>.</li>
--   </ul>
layoutGetJustify :: PangoLayout -> IO Bool

-- | Set if the base text direction should be overridden.
--   
--   <ul>
--   <li>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.</li>
--   <li>When <tt>False</tt>, the choice between left-to-right and
--   right-to-left layout is done by according to the base direction of the
--   layout's <a>PangoContext</a>. (See <a>contextSetTextDir</a>).</li>
--   <li>When the auto-computed direction or a paragraph differs from the
--   base direction of the context, then the interpretation of
--   <a>AlignLeft</a> and <a>AlignRight</a> are swapped.</li>
--   </ul>
layoutSetAutoDir :: PangoLayout -> Bool -> IO ()

-- | Retrieve the auto direction flag.
--   
--   <ul>
--   <li>See <a>layoutSetAutoDir</a>.</li>
--   </ul>
layoutGetAutoDir :: PangoLayout -> IO Bool

-- | Enumerate to which side incomplete lines are flushed.
data LayoutAlignment
AlignLeft :: LayoutAlignment
AlignCenter :: LayoutAlignment
AlignRight :: LayoutAlignment

-- | Set how this paragraph is aligned.
--   
--   <ul>
--   <li>Sets the alignment for the layout (how partial lines are
--   positioned within the horizontal space available.)</li>
--   </ul>
layoutSetAlignment :: PangoLayout -> LayoutAlignment -> IO ()

-- | Get the alignment for the layout.
layoutGetAlignment :: PangoLayout -> IO LayoutAlignment

-- | Specify where the Tab stop appears relative to the text.
--   
--   <ul>
--   <li>Only Tab stops that align text to the left are supported right
--   now.</li>
--   </ul>
data TabAlign

-- | A Tab position.
type TabPosition = (Double, TabAlign)

-- | Set a list of Tab positoins.
layoutSetTabs :: PangoLayout -> [TabPosition] -> IO ()

-- | Reset the original set of Tab positions.
--   
--   <ul>
--   <li>Restore the default which is a Tab stop every eight
--   characters.</li>
--   </ul>
layoutResetTabs :: PangoLayout -> IO ()

-- | Retrieve the list of current Tab positions.
--   
--   <ul>
--   <li>If no Tab position where set, <tt>Nothing</tt> is returned. In
--   this case, Tab positions are implicit at every eight characters.</li>
--   </ul>
layoutGetTabs :: PangoLayout -> IO (Maybe [TabPosition])

-- | Honor newlines or not.
--   
--   <ul>
--   <li>If <tt>honor</tt> is <tt>True</tt>, 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.</li>
--   </ul>
layoutSetSingleParagraphMode :: PangoLayout -> Bool -> IO ()

-- | Retrieve if newlines are honored.
--   
--   <ul>
--   <li>See <a>layoutSetSingleParagraphMode</a>.</li>
--   </ul>
layoutGetSingleParagraphMode :: PangoLayout -> IO Bool

-- | Converts a device unit to a character index.
--   
--   <ul>
--   <li>Converts from <tt>x</tt> and <tt>y</tt> position within a layout
--   to the index of the closest character. If the <tt>y</tt> position is
--   not inside the layout, the closest position is chosen (the position
--   will be clamped inside the layout). If the <tt>x</tt> position is not
--   within the layout, then the start or the end of the line is chosen. If
--   either the <tt>x</tt> or <tt>y</tt> positions were not inside the
--   layout, then the function returns <tt>False</tt>; on an exact hit, it
--   returns <tt>True</tt>.</li>
--   <li>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.</li>
--   </ul>
layoutXYToIndex :: PangoLayout -> Double -> Double -> IO (Bool, Int, Int)

-- | Return the rectangle of the glyph at the given index.
--   
--   <ul>
--   <li>Converts from an index within a <a>PangoLayout</a> to the onscreen
--   position corresponding to the grapheme at that index, which is
--   represented as rectangle. Note that, given a <tt>PangoRectangle x y
--   width height</tt>, <tt>x</tt> is always the leading edge of the
--   grapheme and <tt>x + width</tt> the trailing edge of the grapheme. If
--   the directionality of the grapheme is right-to-left, then
--   <tt>width</tt> will be negative.</li>
--   </ul>
layoutIndexToPos :: PangoLayout -> Int -> IO PangoRectangle

-- | Return a cursor position.
--   
--   <ul>
--   <li>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.</li>
--   </ul>
layoutGetCursorPos :: PangoLayout -> Int -> IO (PangoRectangle, PangoRectangle)

-- | A new cursor position.
--   
--   See <a>layoutMoveCursorVisually</a>.
data CursorPos

-- | The cursor should move to the previous paragraph.
CursorPosPrevPara :: CursorPos

-- | The sum of the indices is the new cursor position.
CursorPos :: Int -> Int -> CursorPos

-- | The cursor should advance to the next paragraph.
CursorPosNextPara :: CursorPos

-- | Move a cursor visually.
--   
--   <ul>
--   <li>Compute a new cursor position from a previous cursor position. A
--   value of <tt>True</tt> 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.</li>
--   <li>The first flag should be <tt>True</tt> if this cursor is the
--   strong cursor. The strong cursor is the cursor of the base direction
--   of the current layout (see <a>layoutSetAutoDir</a>). The weak cursor
--   is that of the opposite direction.</li>
--   <li>The previous cursor position is given by <tt>idx</tt>. 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 <a>CursorPosNextPara</a> if the cursor
--   moved beyond this paragraph, it is <a>CursorPosPrevPara</a> if the
--   cursor moved in front of this paragraph and it is <a>CursorPos</a>
--   <tt>idx</tt> <tt>trail</tt> to denote the new cursor position
--   <tt>idx</tt>. Note that <tt>idx</tt> will always denote an insertion
--   point, that is, <tt>idx</tt> will never point into the middle of a
--   cluster. The <tt>trail</tt> value can contain a positive value if the
--   current cursor position is at the end of the current line. In this
--   case, <tt>idx</tt> points past the last character of this line while
--   <tt>trail</tt> contains the number of characters that are reponsible
--   for the line break such as newlines. The actual cursor position is
--   always <tt>idx+trail</tt> where the visual cursor should be
--   shown.</li>
--   </ul>
layoutMoveCursorVisually :: PangoLayout -> Bool -> Int -> Bool -> IO CursorPos

-- | Computes the logical and ink extents of the <a>PangoLayout</a>.
--   
--   Logical extents are usually what you want for positioning things. Note
--   that both extents may have non-zero x and y. You may want to use those
--   to offset where you render the layout. Not doing that is a very
--   typical bug that shows up as right-to-left layouts not being correctly
--   positioned in a layout with a set width.
--   
--   Layout coordinates begin at the top left corner of the layout.
layoutGetExtents :: PangoLayout -> IO (PangoRectangle, PangoRectangle)

-- | Compute the physical size of the layout.
--   
--   <ul>
--   <li>Computes the ink and the logical size of the <tt>Layout</tt> in
--   device units, that is, pixels for a screen. Identical to
--   <a>layoutGetExtents</a> and converting the <a>Double</a>s in the
--   <a>PangoRectangle</a> to integers.</li>
--   </ul>
layoutGetPixelExtents :: PangoLayout -> IO (Rectangle, Rectangle)

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

-- | Extract a single lines of the layout.
--   
--   <ul>
--   <li>The given index starts from 0. The function throws an
--   <a>ArrayException</a> if the index is out of bounds.</li>
--   <li>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.</li>
--   </ul>
layoutGetLine :: PangoLayout -> Int -> IO LayoutLine

-- | Extract the lines of the layout.
--   
--   <ul>
--   <li>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.</li>
--   </ul>
layoutGetLines :: PangoLayout -> IO [LayoutLine]

-- | An iterator to examine a layout.
data LayoutIter

-- | Create an iterator to examine a layout.
layoutGetIter :: PangoLayout -> IO LayoutIter

-- | Move to the next <a>GlyphItem</a>.
--   
--   <ul>
--   <li>Returns <tt>False</tt> if this was the last item in the
--   layout.</li>
--   </ul>
layoutIterNextItem :: LayoutIter -> IO Bool

-- | Move to the next char.
--   
--   <ul>
--   <li>Returns <tt>False</tt> if this was the last char in the
--   layout.</li>
--   </ul>
layoutIterNextChar :: LayoutIter -> IO Bool

-- | Move to the next cluster.
--   
--   <ul>
--   <li>Returns <tt>False</tt> if this was the last cluster in the
--   layout.</li>
--   </ul>
layoutIterNextCluster :: LayoutIter -> IO Bool

-- | Move to the next line.
--   
--   <ul>
--   <li>Returns <tt>False</tt> if this was the last line in the
--   layout.</li>
--   </ul>
layoutIterNextLine :: LayoutIter -> IO Bool

-- | Check if the iterator is on the last line.
--   
--   <ul>
--   <li>Returns <tt>True</tt> if the iterator is on the last line of this
--   paragraph.</li>
--   </ul>
layoutIterAtLastLine :: LayoutIter -> IO Bool

-- | Get the character index.
--   
--   <ul>
--   <li>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.</li>
--   </ul>
layoutIterGetIndex :: LayoutIter -> IO Int

-- | Query the vertical position within the layout.
--   
--   <ul>
--   <li>Gets the y position of the current line's baseline (origin at top
--   left of the entire layout).</li>
--   </ul>
layoutIterGetBaseline :: LayoutIter -> IO Double

-- | Retrieve the current <a>GlyphItem</a> under the iterator.
--   
--   <ul>
--   <li>Each <a>LayoutLine</a> contains a list of <a>GlyphItem</a>s. This
--   function returns the <a>GlyphItem</a> under the current iterator. If
--   the iterator is positioned past the last charactor of the paragraph,
--   the function returns <tt>Nothing</tt>.</li>
--   </ul>
layoutIterGetItem :: LayoutIter -> IO (Maybe GlyphItem)

-- | Extract the line under the iterator.
layoutIterGetLine :: LayoutIter -> IO (Maybe LayoutLine)

-- | Retrieve a rectangle surrounding a character.
--   
--   <ul>
--   <li>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.</li>
--   </ul>
layoutIterGetCharExtents :: LayoutIter -> IO PangoRectangle

-- | Compute the physical size of the cluster.
--   
--   <ul>
--   <li>Computes the ink and the logical size of the cluster pointed to by
--   <a>LayoutIter</a>.</li>
--   </ul>
layoutIterGetClusterExtents :: LayoutIter -> IO (PangoRectangle, PangoRectangle)

-- | Compute the physical size of the run.
--   
--   <ul>
--   <li>Computes the ink and the logical size of the run pointed to by
--   <a>LayoutIter</a>.</li>
--   </ul>
layoutIterGetRunExtents :: LayoutIter -> IO (PangoRectangle, PangoRectangle)

-- | Retrieve vertical extent of this line.
--   
--   <ul>
--   <li>Divides the vertical space in the <a>PangoLayout</a> 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
--   <a>layoutSetSpacing</a> has been called to set layout spacing. The y
--   positions are in layout coordinates (origin at top left of the entire
--   layout).</li>
--   <li>The first element in the returned tuple is the start, the second
--   is the end of this line.</li>
--   </ul>
layoutIterGetLineYRange :: LayoutIter -> IO (Double, Double)

-- | Compute the physical size of the line.
--   
--   <ul>
--   <li>Computes the ink and the logical size of the line pointed to by
--   <a>LayoutIter</a>. See <a>layoutGetExtents</a>.</li>
--   <li>Extents are in layout coordinates (origin is the top-left corner
--   of the entire <a>PangoLayout</a>). 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 <a>layoutLineGetExtents</a>.</li>
--   </ul>
layoutIterGetLineExtents :: LayoutIter -> IO (PangoRectangle, PangoRectangle)

-- | A single line in a <a>PangoLayout</a>.
data LayoutLine

-- | Compute the physical size of the line.
--   
--   <ul>
--   <li>Computes the ink and the logical size of the <a>LayoutLine</a>.
--   See <a>layoutGetExtents</a>.</li>
--   </ul>
layoutLineGetExtents :: LayoutLine -> IO (PangoRectangle, PangoRectangle)

-- | Compute the physical size of the line.
--   
--   <ul>
--   <li>Computes the ink and the logical size of the <a>LayoutLine</a>.
--   See <a>layoutGetExtents</a>. The returned values are in device units,
--   that is, pixels for the screen and points for printers.</li>
--   </ul>
layoutLineGetPixelExtents :: LayoutLine -> IO (Rectangle, Rectangle)

-- | Request the horizontal position of a character.
layoutLineIndexToX :: LayoutLine -> Int -> Bool -> IO Double

-- | Request the character index of a given horizontal position.
--   
--   <ul>
--   <li>Converts from an x offset to the index of the corresponding
--   character within the text of the layout. If the <tt>x</tt> parameter
--   is outside the line, a triple <tt>(False, index, trailing)</tt> is
--   returned where <tt>index</tt> and <tt>trailing</tt> 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 <tt>x</tt> position to the
--   right of the line results in 0 being returned for <tt>index</tt> and
--   <tt>trailing</tt>. An <tt>x</tt> position to the left of the line
--   results in <tt>index</tt> 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 <tt>True</tt> then <tt>x</tt> was within the
--   layout line and <tt>trailing</tt> indicates where in a cluster the
--   <tt>x</tt> position lay. It is 0 for the trailing edge of the
--   cluster.</li>
--   </ul>
layoutLineXToIndex :: LayoutLine -> Double -> IO (Bool, Int, Int)

-- | Retrieve bounding boxes for a given piece of text contained in this
--   <a>LayoutLine</a>.
--   
--   <ul>
--   <li>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).</li>
--   </ul>
layoutLineGetXRanges :: LayoutLine -> Int -> Int -> IO [(Double, Double)]
instance GHC.Enum.Enum Graphics.Rendering.Pango.Layout.TabAlign
instance GHC.Enum.Enum Graphics.Rendering.Pango.Layout.LayoutAlignment
instance GHC.Enum.Enum Graphics.Rendering.Pango.Layout.LayoutWrapMode


-- | Pango specific functions to for redering with Cairo.
--   
--   Cairo is a graphics library that supports vector graphics and image
--   compositing that can be used with Pango. The functions in this module
--   provide ways of rendering text in Cairo using Pango.
module Graphics.Rendering.Pango.Cairo

-- | Retrieve the default <a>FontMap</a> that contains a list of available
--   fonts.
--   
--   <ul>
--   <li>One purpose of creating an explicit <a>FontMap</a> is to set a
--   different scaling factor between font sizes (in points, pt) and Cairo
--   units (in pixels). The default is 96dpi (dots per inch) which
--   corresponds to an average screen as output medium. A 10pt font will
--   therefore scale to <tt>10pt * (1/72 pt/inch) * (96 pixel/inch) = 13.3
--   pixel</tt>.</li>
--   </ul>
cairoFontMapGetDefault :: IO FontMap

-- | Set the scaling factor between font size and Cairo units.
--   
--   <ul>
--   <li>Value is in dots per inch (dpi). See
--   <a>cairoFontMapGetDefault</a>.</li>
--   </ul>
cairoFontMapSetResolution :: FontMap -> Double -> IO ()

-- | Ask for the scaling factor between font size and Cairo units.
--   
--   <ul>
--   <li>Value is in dots per inch (dpi). See
--   <a>cairoFontMapGetDefault</a>.</li>
--   </ul>
cairoFontMapGetResolution :: FontMap -> IO Double

-- | Create a <a>PangoContext</a>.
--   
--   <ul>
--   <li>If no <a>FontMap</a> is specified, it uses the default
--   <a>FontMap</a> that has a scaling factor of 96 dpi. See
--   <a>cairoFontMapGetDefault</a>.</li>
--   </ul>
cairoCreateContext :: Maybe FontMap -> IO PangoContext

-- | Set the scaling factor of the <a>PangoContext</a>.
--   
--   <ul>
--   <li>Supplying zero or a negative value will result in the resolution
--   value of the underlying <a>FontMap</a> to be used. See also
--   <a>cairoFontMapGetDefault</a>.</li>
--   </ul>
cairoContextSetResolution :: PangoContext -> Double -> IO ()

-- | Ask for the scaling factor of the <a>PangoContext</a>.
--   
--   <ul>
--   <li>A negative value will be returned if no resolution has been set.
--   See <a>cairoContextSetResolution</a>.</li>
--   </ul>
cairoContextGetResolution :: PangoContext -> IO Double

-- | Set Cairo font options.
--   
--   <ul>
--   <li>Apply the given font options to the context. Values set through
--   this functions override those that are set by
--   <a>updateContext</a>.</li>
--   </ul>
cairoContextSetFontOptions :: PangoContext -> FontOptions -> IO ()

-- | Retrieve Cairo font options.
cairoContextGetFontOptions :: PangoContext -> IO FontOptions

-- | Sets the specified <a>Color</a> as the source color of the
--   <a>Render</a> context.
setSourceColor :: Color -> Render ()

-- | Update a <a>PangoContext</a> with respect to changes in a
--   <a>Render</a> environment.
--   
--   <ul>
--   <li>The <a>PangoContext</a> must have been created with
--   <a>cairoCreateContext</a>. Any <a>PangoLayout</a>s that have been
--   previously created with this context have to be update using
--   <a>layoutContextChanged</a>.</li>
--   </ul>
updateContext :: PangoContext -> Render ()

-- | Create a <a>PangoLayout</a> within a <a>Render</a> context.
--   
--   <ul>
--   <li>This is a convenience function that creates a new
--   <a>PangoContext</a> within this <a>Render</a> context and creates a
--   new <a>PangoLayout</a>. If the transformation or target surface of the
--   <a>Render</a> context change, <a>updateLayout</a> has to be called on
--   this layout.</li>
--   </ul>
createLayout :: GlibString string => string -> Render PangoLayout

-- | Propagate changed to the <a>Render</a> context to a
--   <a>PangoLayout</a>.
--   
--   <ul>
--   <li>This is a convenience function that calls <a>updateContext</a> on
--   the (private) <a>PangoContext</a> of the given layout to propagate
--   changes from the <a>Render</a> context to the <a>PangoContext</a> and
--   then calls <a>layoutContextChanged</a> on the layout. This function is
--   necessary for <a>createLayout</a> since a private <a>PangoContext</a>
--   is created that is not visible to the user.</li>
--   </ul>
updateLayout :: PangoLayout -> Render ()

-- | Draw a glyph string.
--   
--   <ul>
--   <li>The origin of the glyphs (the left edge of the baseline) will be
--   drawn at the current point of the cairo context.</li>
--   </ul>
showGlyphString :: GlyphItem -> Render ()

-- | Draw a <a>LayoutLine</a>.
--   
--   <ul>
--   <li>The origin of the glyphs (the left edge of the baseline) will be
--   drawn at the current point of the cairo context.</li>
--   </ul>
showLayoutLine :: LayoutLine -> Render ()

-- | Draw a <a>PangoLayout</a>.
--   
--   <ul>
--   <li>The top-left corner of the <a>PangoLayout</a> will be drawn at the
--   current point of the cairo context.</li>
--   </ul>
showLayout :: PangoLayout -> Render ()

-- | Add the extent of a glyph string to the current path.
--   
--   <ul>
--   <li>The origin of the glyphs (the left edge of the line) will be at
--   the current point of the cairo context.</li>
--   </ul>
glyphStringPath :: GlyphItem -> Render ()

-- | Add the extent of a layout line to the current path.
--   
--   <ul>
--   <li>The origin of the glyphs (the left edge of the line) will be at
--   the current point of the cairo context.</li>
--   </ul>
layoutLinePath :: LayoutLine -> Render ()

-- | Add the layout to the current path.
--   
--   <ul>
--   <li>Adds the top-left corner of the text to the current path.
--   Afterwards, the path position is at the bottom-right corner of the
--   <a>PangoLayout</a>.</li>
--   </ul>
layoutPath :: PangoLayout -> Render ()


-- | Pango is a library for laying out and rendering of text, with an
--   emphasis on internationalization. Pango can be used anywhere that text
--   layout is needed, though most of the work on Pango so far has been
--   done in the context of the GTK+ widget toolkit. Pango forms the core
--   of text and font handling for GTK+-2.x.
--   
--   Pango is designed to be modular; the core Pango layout engine can be
--   used with different font backends. There are three basic backends:
--   
--   <ul>
--   <li>Client side fonts using the FreeType and fontconfig
--   libraries.</li>
--   <li>Native fonts on Microsoft Windows using Uniscribe for complex-text
--   handling.</li>
--   <li>Native fonts on MacOS X using ATSUI for complex-text
--   handling.</li>
--   </ul>
--   
--   The integration of Pango with Cairo &lt;http: high quality text
--   handling and graphics rendering.
--   
--   Dynamically loaded modules then handle text layout for particular
--   combinations of script and font backend. Pango ships with a wide
--   selection of modules, including modules for Hebrew, Arabic, Hangul,
--   Thai, and a number of Indic scripts. Virtually all of the world's
--   major scripts are supported.
--   
--   As well as the low level layout rendering routines, Pango includes
--   <a>PangoLayout</a>, a high level driver for laying out entire blocks
--   of text, and routines to assist in editing internationalized text.
--   
--   Pango depends on 2.x series of the GLib library.
--   
--   This module only re-exports the parts of the Pango library that are
--   relevant for text rendering (as opposed to integration with other
--   libraries).
module Graphics.Rendering.Pango
