| Gtk2Hs | Contents | Index

Graphics.UI.Gtk.Cairo

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

Contents

Global Cairo settings.
Using Graphics.UI.Gtk.Gdk.Pixbuf.Pixbuf functions together with Cairo
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 Graphics.UI.Gtk.Gdk.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
cairoImageSurfaceFromPixbuf :: Pixbuf -> IO Surface
pixbufFromImageSurface :: Surface -> IO Pixbuf
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 Graphics.UI.Gtk.Pango.FontMap that contains a list of available fonts.

- One purpose of creating an explicit Graphics.UI.Gtk.Pango.Font.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 cairoFontMapNew.

cairoFontMapGetResolution :: FontMap -> IO Double

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

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

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 cairoFontMapNew.

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 cairoFontMapNew.

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.
Using Graphics.UI.Gtk.Gdk.Pixbuf.Pixbuf functions together with Cairo
cairoImageSurfaceFromPixbuf :: Pixbuf -> IO Surface

Treat a Graphics.UI.Gtk.Gdk.Pixbuf.Pixbuf as an image 'Graphics..Rendering.Cairo.Surface'.

- The image data is shared between the two objects. Note that everytime you use Graphics.UI.Gtk.Gdk.Pixbuf.Pixbuf functions on the image, it is necessary to tell Cairo that the image data has changed using 'Graphics..Rendering.Cairo.surfaceMarkDirty' since it might cache certain areas of an image.

pixbufFromImageSurface :: Surface -> IO Pixbuf

Treat an image Graphics.Rendering.Cairo.Surface as a Graphics.UI.Gtk.Gdk.Pixbuf.Pixbuf.

- The image data is shared between the two objects. Note that everytime you use Graphics.UI.Gtk.Gdk.Pixbuf.Pixbuf functions on the image, it is necessary to tell Cairo that the image data has changed using Graphics.Rendering.Cairo.surfaceMarkDirty since it might cache certain areas of an image. This function throws an error if the Graphics.Rendering.Cairo.Surface has any other format than Graphics.Rendering.Cairo.FormatARGB32 or Graphics.Rendering.Cairo.FormatRGB32 since Graphics.UI.Gtk.Gdk.Pixbuf.Pixbuf can currently only handle these two formats.
- Requires Cairo 1.2 or higher.

Functions for the `Render` monad.
renderWithDrawable

:: 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

:: 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 Graphics.UI.Gtk.Pango.Layout.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 Graphics.UI.Gtk.Pango.Layout.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`.

Produced by Haddock version 2.4.2