gtk-0.12.3.1: Binding to the Gtk+ graphical user interface library.

Portability | portable (depends on GHC)
Stability | provisional
Maintainer | gtk2hs-users@lists.sourceforge.net
Safe Haskell | None

Graphics.UI.Gtk.Cairo

Contents

- Global Cairo settings.
- Functions for the `Render` monad.

Description

Gtk specific functions to for redering with Cairo.

Cairo is a graphics library that supports vector graphics and image compositing that can be used with Gdk. The Cairo API is an addition to Gdk/Gtk (rather than a replacement). Cairo rendering can be performed on any `Drawable` by calling `renderWithDrawable`. The functions in this module provide ways of drawing Gtk specific elements, such as `Pixbuf`s or text laid out with Pango.

All functions in this module are only available in Gtk 2.8 or higher.

Synopsis

- cairoFontMapGetDefault :: IO FontMap
- cairoFontMapSetResolution :: FontMap -> Double -> IO ()
- cairoFontMapGetResolution :: FontMap -> IO Double
- cairoCreateContext :: Maybe FontMap -> IO PangoContext
- cairoContextSetResolution :: PangoContext -> Double -> IO ()
- cairoContextGetResolution :: PangoContext -> IO Double
- cairoContextSetFontOptions :: PangoContext -> FontOptions -> IO ()
- cairoContextGetFontOptions :: PangoContext -> IO FontOptions
- renderWithDrawable :: DrawableClass drawable => drawable -> Render a -> IO a
- setSourceColor :: Color -> Render ()
- setSourcePixbuf :: Pixbuf -> Double -> Double -> Render ()
- region :: Region -> Render ()
- updateContext :: PangoContext -> Render ()
- createLayout :: String -> Render PangoLayout
- updateLayout :: PangoLayout -> Render ()
- showGlyphString :: GlyphItem -> Render ()
- showLayoutLine :: LayoutLine -> Render ()
- showLayout :: PangoLayout -> Render ()
- glyphStringPath :: GlyphItem -> Render ()
- layoutLinePath :: LayoutLine -> Render ()
- layoutPath :: PangoLayout -> Render ()

# Global Cairo settings.

cairoFontMapGetDefault :: IO FontMap

Retrieve the default `FontMap` that contains a list of available fonts.

- One purpose of creating an explicit `FontMap` 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 `10pt * (1/72 pt/inch) * (96 pixel/inch) = 13.3 pixel`.

cairoFontMapSetResolution :: FontMap -> Double -> IO ()

Set the scaling factor between font size and Cairo units.

- Value is in dots per inch (dpi). See `cairoFontMapGetDefault`.

cairoFontMapGetResolution :: FontMap -> IO Double

Ask for the scaling factor between font size and Cairo units.

- Value is in dots per inch (dpi). See `cairoFontMapGetDefault`.

cairoCreateContext :: Maybe FontMap -> IO PangoContext

Create a `PangoContext`.

- If no `FontMap` is specified, it uses the default `FontMap` that has a scaling factor of 96 dpi. See `cairoFontMapGetDefault`.

cairoContextSetResolution :: PangoContext -> Double -> IO ()

Set the scaling factor of the `PangoContext`.

- Supplying zero or a negative value will result in the resolution value of the underlying `FontMap` to be used. See also `cairoFontMapGetDefault`.

cairoContextGetResolution :: PangoContext -> IO Double

Ask for the scaling factor of the `PangoContext`.

- A negative value will be returned if no resolution has been set. See `cairoContextSetResolution`.

cairoContextSetFontOptions :: PangoContext -> FontOptions -> IO ()

Set Cairo font options.

- Apply the given font options to the context. Values set through this functions override those that are set by `updateContext`.

cairoContextGetFontOptions :: PangoContext -> IO FontOptions

Retrieve Cairo font options.

# Functions for the `Render` monad.

renderWithDrawable

Arguments

:: DrawableClass drawable |
=> drawable | `drawable` - a `Drawable`
-> Render a | A newly created Cairo context.
-> IO a |

Creates a Cairo context for drawing to a `Drawable`.

setSourceColor :: Color -> Render ()

Sets the specified `Color` as the source color of the `Render` context.

setSourcePixbuf

Arguments

:: Pixbuf |
-> Double | x
-> Double | y
-> Render () |

Sets the given pixbuf as the source pattern for the Cairo context. The pattern has an extend mode of `ExtendNone` and is aligned so that the origin of pixbuf is `(x, y)`.

region :: Region -> Render ()

Adds the given region to the current path of the `Render` context.

updateContext :: PangoContext -> Render ()

Update a `PangoContext` with respect to changes in a `Render` environment.

- The `PangoContext` must have been created with `cairoCreateContext`. Any `PangoLayout`s that have been previously created with this context have to be update using `layoutContextChanged`.

createLayout :: String -> Render PangoLayout

Create a `PangoLayout` within a `Render` context.

- This is a convenience function that creates a new `PangoContext` within this `Render` context and creates a new `PangoLayout`. If the transformation or target surface of the `Render` context change, `updateLayout` has to be called on this layout.

updateLayout :: PangoLayout -> Render ()

Propagate changed to the `Render` context to a `PangoLayout`.

- This is a convenience function that calls `updateContext` on the (private) `PangoContext` of the given layout to propagate changes from the `Render` context to the `PangoContext` and then calls `layoutContextChanged` on the layout. This function is necessary for `createLayout` since a private `PangoContext` is created that is not visible to the user.

showGlyphString :: GlyphItem -> Render ()

Draw a glyph string.

- The origin of the glyphs (the left edge of the baseline) will be drawn at the current point of the cairo context.

showLayoutLine :: LayoutLine -> Render ()

Draw a `LayoutLine`.

- The origin of the glyphs (the left edge of the baseline) will be drawn at the current point of the cairo context.

showLayout :: PangoLayout -> Render ()

Draw a `PangoLayout`.

- The top-left corner of the `PangoLayout` will be drawn at the current point of the cairo context.

glyphStringPath :: GlyphItem -> Render ()

Add the extent of a glyph string to the current path.

- The origin of the glyphs (the left edge of the line) will be at the current point of the cairo context.

layoutLinePath :: LayoutLine -> Render ()

Add the extent of a layout line to the current path.

- The origin of the glyphs (the left edge of the line) will be at the current point of the cairo context.

layoutPath :: PangoLayout -> Render ()

Add the layout to the current path.

- Adds the top-left corner of the text to the current path. Afterwards, the path position is at the bottom-right corner of the `PangoLayout`.