Graphics.UI.WXCore.WxcTypes

Basic types and marshalling code for the wxWidgets C library.

Object types

data Object a

An Object a is a pointer to an object of type a. The a parameter is used to encode the inheritance relation. When the type parameter is unit (), it denotes an object of exactly that class, when the parameter is a type variable a, it specifies an object that is at least an instance of that class. For example in wxWidgets, we have the following class hierarchy:

EvtHandler
  |- Window
       |- Frame
       |- Control
           |- Button
           |- Radiobox

In wxHaskell, all the creation functions will return objects of exactly that class and use the () type:

frameCreate :: Window a -> ... -> IO (Frame ())
buttonCreate :: Window a -> ... -> IO (Button ())
...

In contrast, all the this (or self) pointers of methods can take objects of any instance of that class and have a type variable, for example:

windowSetClientSize :: Window a -> Size -> IO ()
controlSetLabel     :: Control a -> String -> IO ()
buttonSetDefault    :: Button a -> IO ()

This means that we can use windowSetClientSize on any window, including buttons and frames, but we can only use controlSetLabel on controls, not including frames.

In wxHaskell, this works since a Frame () is actually a type synonym for Window (CFrame ()) (where CFrame is an abstract data type). We can thus pass a value of type Frame () to anything that expects some Window a. For a button this works too, as it is a synonym for Control (CButton ()) which is in turn a synonym for Window (CControl (CButton ())). Note that we can't pass a frame to something that expects a value of type Control a. Of course, a Window a is actually a type synonym for EvtHandler (CWindow a). If you study the documentation in Graphics.UI.WX.Classes closely, you can discover where this chain ends :-).

Objects are not automatically deleted. Normally you can use a delete function like windowDelete to delete an object. However, almost all objects in the wxWidgets library are automatically deleted by the library. The only objects that should be used with care are resources as bitmaps, fonts and brushes.

Instances

Eq (Object a)

Ord (Object a)

Show (Object a)

Widget (Window a)

objectNull :: Object a

A null object. Use with care.

objectIsNull :: Object a -> Bool

Test for null object.

objectCast :: Object a -> Object b

Cast an object to another type. Use with care.

objectIsManaged :: Object a -> Bool

Is this a managed object?

objectDelete :: WxObject a -> IO ()

Delete a wxObject, works for managed and unmanaged objects.

objectFromPtr :: Ptr a -> Object a

Create an unmanaged object.

managedObjectFromPtr :: Ptr (TWxObject a) -> IO (WxObject a)

Create a managed object that will be deleted using |wxObject_SafeDelete|.

withObjectPtr :: Object a -> (Ptr a -> IO b) -> IO b

Do something with the object pointer.

withObjectRef :: String -> Object a -> (Ptr a -> IO b) -> IO b

Extract the object pointer and raise an exception if NULL. Otherwise continue with the valid pointer.

withObjectResult :: IO (Ptr a) -> IO (Object a)

Return an unmanaged object.

withManagedObjectResult :: IO (Ptr (TWxObject a)) -> IO (WxObject a)

Create a managed object that will be deleted using |wxObject_SafeDelete|.

objectFinalize :: Object a -> IO ()

Finalize a managed object manually. (No effect on unmanaged objects.)

objectNoFinalize :: Object a -> IO ()

Remove the finalizer on a managed object. (No effect on unmanaged objects.)

Type synonyms

type Id = Int

An Id is used to identify objects during event handling.

type Style = Int

A Style is normally used as a flag mask to specify some window style

type EventId = Int

An EventId is identifies specific events.

Basic types

fromBool :: Num a => Bool -> a

Convert a Haskell Bool to its numeric representation

toBool :: (Eq a, Num a) => a -> Bool

Convert a Boolean in numeric representation to a Haskell value

Point

type Point = Point2 Int

data Num a => Point2 a

A point has an x and y coordinate. Coordinates are normally relative to the upper-left corner of their view frame, where a positive x goes to the right and a positive y to the bottom of the view.

Constructors

Point

Fields

pointX :: !a

x component of a point.

pointY :: !a

y component of a point.

Instances

(Eq a, Num a) => Eq (Point2 a)

(Num a, Ord a) => Ord (Point2 a)

(Num a, Read a) => Read (Point2 a)

(Num a, Show a) => Show (Point2 a)

Ix (Point2 Int)

Typeable (* -> *) Point2

point :: Num a => a -> a -> Point2 a

Construct a point.

pt :: Num a => a -> a -> Point2 a

Shorter function to construct a point.

pointFromVec :: Num a => Vector -> Point2 a

pointFromSize :: Num a => Size -> Point2 a

pointZero :: Num a => Point2 a

Point at the origin.

pointNull :: Num a => Point2 a

A null point is not a legal point (x and y are -1) and can be used for some wxWidgets functions to select a default point.

Size

type Size = Size2D Int

data Num a => Size2D a

A Size has a width and height.

Constructors

Size

Fields

sizeW :: !a

the width of a size

sizeH :: !a

the height of a size

Instances

(Eq a, Num a) => Eq (Size2D a)

(Num a, Show a) => Show (Size2D a)

Typeable (* -> *) Size2D

sz :: Num a => a -> a -> Size2D a

Short function to construct a size

sizeFromPoint :: Num a => Point2 a -> Size2D a

sizeFromVec :: Num a => Vector2 a -> Size2D a

sizeZero :: Num a => Size2D a

sizeNull :: Num a => Size2D a

A null size is not a legal size (width and height are -1) and can be used for some wxWidgets functions to select a default size.

Vector

type Vector = Vector2 Int

data Num a => Vector2 a

A vector with an x and y delta.

Constructors

Vector

Fields

vecX :: !a

delta-x component of a vector

vecY :: !a

delta-y component of a vector

Instances

(Eq a, Num a) => Eq (Vector2 a)

(Num a, Read a) => Read (Vector2 a)

(Num a, Show a) => Show (Vector2 a)

Typeable (* -> *) Vector2

vector :: Num a => a -> a -> Vector2 a

Construct a vector.

vec :: Num a => a -> a -> Vector2 a

Short function to construct a vector.

vecFromPoint :: Num a => Point2 a -> Vector2 a

vecFromSize :: Size -> Vector

vecZero :: Num a => Vector2 a

A zero vector

vecNull :: Num a => Vector2 a

A null vector has a delta x and y of -1 and can be used for some wxWidgets functions to select a default vector.

Rectangle

type Rect = Rect2D Int

data Num a => Rect2D a

A rectangle is defined by the left x coordinate, the top y coordinate, the width and the height.

Constructors

Rect

Fields

rectLeft :: !a

rectTop :: !a

rectWidth :: !a

rectHeight :: !a

Instances

(Eq a, Num a) => Eq (Rect2D a)

(Num a, Read a) => Read (Rect2D a)

(Num a, Show a) => Show (Rect2D a)

Typeable (* -> *) Rect2D

rectTopLeft :: Num a => Rect2D a -> Point2 a

rectTopRight :: Num a => Rect2D a -> Point2 a

rectBottomLeft :: Num a => Rect2D a -> Point2 a

rectBottomRight :: Num a => Rect2D a -> Point2 a

rectBottom :: Num a => Rect2D a -> a

rectRight :: Num a => Rect2D a -> a

rect :: Num a => Point2 a -> Size2D a -> Rect2D a

Create a rectangle at a certain (upper-left) point with a certain size.

rectBetween :: (Num a, Ord a) => Point2 a -> Point2 a -> Rect2D a

Construct a (positive) rectangle between two (arbitrary) points.

rectFromSize :: Num a => Size2D a -> Rect2D a

Create a rectangle of a certain size with the upper-left corner at (pt 0 0).

rectZero :: Num a => Rect2D a

An empty rectangle at (0,0).

rectNull :: Num a => Rect2D a

An null rectangle is not a valid rectangle (Rect -1 -1 -1 -1) but can used for some wxWidgets functions to select a default rectangle. (i.e. frameCreate).

rectSize :: Num a => Rect2D a -> Size2D a

Get the size of a rectangle.

rectIsEmpty :: (Num a, Eq a) => Rect2D a -> Bool

Color

newtype Color

An abstract data type to define colors.

Note: Haddock 0.8 and 0.9 doesn't support GeneralizedNewtypeDeriving. So, This class doesn't have IArray class's unboxed array instance now. If you want to use this type with unboxed array, you must write code like this.

{-# LANGUAGE GeneralizedNewtypeDeriving, StandaloneDeriving, MultiParamTypeClasses #-}
import Graphics.UI.WXCore.WxcTypes
...
deriving instance IArray UArray Color

We can't derive MArray class's unboxed array instance this way. This is a bad point of current MArray class definition.

Constructors

Color Word

Instances

Eq Color

Show Color

Typeable * Color

rgb :: Integral a => a -> a -> a -> Color

Create a color from a red/green/blue triple.

colorRGB :: Integral a => a -> a -> a -> Color

Create a color from a red/green/blue triple.

rgba :: Integral a => a -> a -> a -> a -> Color

Create a color from a red/green/blue/alpha quadruple.

colorRGBA :: Integral a => a -> a -> a -> a -> Color

Create a color from a red/green/blue/alpha quadruple.

colorRed :: Num a => Color -> a

Returns a red color component

colorGreen :: Num a => Color -> a

Returns a green color component

colorBlue :: Num a => Color -> a

Returns a blue color component

colorAlpha :: Num a => Color -> a

Returns a alpha channel component

intFromColor :: Color -> Int

Return an Int where the three least significant bytes contain the red, green, and blue component of a color.

colorFromInt :: Int -> Color

Set the color according to an rgb integer. (see rgbIntFromColor).

fromColor :: Num a => Color -> a

Return an Num class's numeric representation where the three least significant the red, green, and blue component of a color.

toColor :: Integral a => a -> Color

Set the color according to Integral class's numeric representation. (see rgbaIntFromColor).

colorOk :: Color -> Bool

Deprecated: Use colorIsOk instead

deprecated: use colorIsOk instead.

colorIsOk :: Color -> Bool

Check of a color is valid (Colour::IsOk)

Marshalling

Basic types

withPointResult :: (Ptr CInt -> Ptr CInt -> IO ()) -> IO (Point2 Int)

withWxPointResult :: IO (Ptr (TWxPoint a)) -> IO (Point2 Int)

toCIntPointX :: Point2 Int -> CInt

toCIntPointY :: Point2 Int -> CInt

fromCPoint :: CInt -> CInt -> Point2 Int

withCPoint :: Point2 Int -> (CInt -> CInt -> IO a) -> IO a

withPointDoubleResult :: (Ptr CDouble -> Ptr CDouble -> IO ()) -> IO (Point2 Double)

toCDoublePointX :: Point2 Double -> CDouble

toCDoublePointY :: Point2 Double -> CDouble

fromCPointDouble :: CDouble -> CDouble -> Point2 Double

withCPointDouble :: Point2 Double -> (CDouble -> CDouble -> IO a) -> IO a

withSizeResult :: (Ptr CInt -> Ptr CInt -> IO ()) -> IO Size

withWxSizeResult :: IO (Ptr (TWxSize a)) -> IO Size

toCIntSizeW :: Size -> CInt

toCIntSizeH :: Size -> CInt

fromCSize :: CInt -> CInt -> Size

withCSize :: Size -> (CInt -> CInt -> IO a) -> IO a

withSizeDoubleResult :: (Ptr CDouble -> Ptr CDouble -> IO ()) -> IO (Size2D Double)

toCDoubleSizeW :: Size2D Double -> CDouble

toCDoubleSizeH :: Size2D Double -> CDouble

fromCSizeDouble :: CDouble -> CDouble -> Size2D Double

withCSizeDouble :: Size2D Double -> (CDouble -> CDouble -> IO a) -> IO a

withVectorResult :: (Ptr CInt -> Ptr CInt -> IO ()) -> IO Vector

withWxVectorResult :: IO (Ptr (TWxPoint a)) -> IO Vector

toCIntVectorX :: Vector -> CInt

toCIntVectorY :: Vector -> CInt

fromCVector :: CInt -> CInt -> Vector

withCVector :: Vector -> (CInt -> CInt -> IO a) -> IO a

withVectorDoubleResult :: (Ptr CDouble -> Ptr CDouble -> IO ()) -> IO (Vector2 Double)

toCDoubleVectorX :: Vector2 Double -> CDouble

toCDoubleVectorY :: Vector2 Double -> CDouble

fromCVectorDouble :: CDouble -> CDouble -> Vector2 Double

withCVectorDouble :: Vector2 Double -> (CDouble -> CDouble -> IO a) -> IO a

withRectResult :: (Ptr CInt -> Ptr CInt -> Ptr CInt -> Ptr CInt -> IO ()) -> IO Rect

withWxRectResult :: IO (Ptr (TWxRect a)) -> IO Rect

withWxRectPtr :: Rect -> (Ptr (TWxRect r) -> IO a) -> IO a

toCIntRectX :: Rect -> CInt

toCIntRectY :: Rect -> CInt

toCIntRectW :: Rect -> CInt

toCIntRectH :: Rect -> CInt

fromCRect :: CInt -> CInt -> CInt -> CInt -> Rect

withCRect :: Rect -> (CInt -> CInt -> CInt -> CInt -> IO a) -> IO a

withRectDoubleResult :: (Ptr CDouble -> Ptr CDouble -> Ptr CDouble -> Ptr CDouble -> IO ()) -> IO (Rect2D Double)

toCDoubleRectX :: Rect2D Double -> CDouble

toCDoubleRectY :: Rect2D Double -> CDouble

toCDoubleRectW :: Rect2D Double -> CDouble

toCDoubleRectH :: Rect2D Double -> CDouble

fromCRectDouble :: CDouble -> CDouble -> CDouble -> CDouble -> Rect2D Double

withCRectDouble :: Rect2D Double -> (CDouble -> CDouble -> CDouble -> CDouble -> IO a) -> IO a

withArray :: Storable a => [a] -> (Ptr a -> IO b) -> IO b

Temporarily store a list of storable values in memory (like with, but for multiple elements).

withArrayString :: [String] -> (CInt -> Ptr CString -> IO a) -> IO a

withArrayWString :: [String] -> (CInt -> Ptr CWString -> IO a) -> IO a

withArrayInt :: [Int] -> (CInt -> Ptr CInt -> IO a) -> IO a

withArrayIntPtr :: [IntPtr] -> (CInt -> Ptr CIntPtr -> IO a) -> IO a

withArrayObject :: [Ptr a] -> (CInt -> Ptr (Ptr a) -> IO b) -> IO b

withArrayIntResult :: (Ptr CInt -> IO CInt) -> IO [Int]

withArrayIntPtrResult :: (Ptr CIntPtr -> IO CInt) -> IO [IntPtr]

withArrayStringResult :: (Ptr (Ptr CChar) -> IO CInt) -> IO [String]

withArrayWStringResult :: (Ptr (Ptr CWchar) -> IO CInt) -> IO [String]

withArrayObjectResult :: (Ptr (Ptr a) -> IO CInt) -> IO [Object a]

colourFromColor :: Color -> IO (Colour ())

colorFromColour :: Colour a -> IO Color

colourCreate :: IO (Ptr (TColour a))

colourSafeDelete :: Ptr (TColour a) -> IO ()

Managed object types

data TreeItem

Identifies tree items. Note: Replaces the TreeItemId object and takes automatically care of allocation issues.

Instances

Eq TreeItem

Read TreeItem

Show TreeItem

treeItemInvalid :: TreeItem

Invalid tree item.

treeItemIsOk :: TreeItem -> Bool

Is a tree item ok? (i.e. not invalid).

treeItemFromInt :: IntPtr -> TreeItem

withRefTreeItemId :: (Ptr (TTreeItemId ()) -> IO ()) -> IO TreeItem

withTreeItemIdPtr :: TreeItem -> (Ptr (TTreeItemId a) -> IO b) -> IO b

withTreeItemIdRef :: String -> TreeItem -> (Ptr (TTreeItemId a) -> IO b) -> IO b

withManagedTreeItemIdResult :: IO (Ptr (TTreeItemId a)) -> IO TreeItem

withStringRef :: String -> String -> (Ptr (TWxString s) -> IO a) -> IO a

withStringPtr :: String -> (Ptr (TWxString s) -> IO a) -> IO a

withManagedStringResult :: IO (Ptr (TWxString a)) -> IO String

withRefColour :: (Ptr (TColour a) -> IO ()) -> IO Color

withColourRef :: String -> Color -> (Ptr (TColour a) -> IO b) -> IO b

withColourPtr :: Color -> (Ptr (TColour a) -> IO b) -> IO b

withManagedColourResult :: IO (Ptr (TColour a)) -> IO Color

withRefBitmap :: (Ptr (TBitmap a) -> IO ()) -> IO (Bitmap a)

withManagedBitmapResult :: IO (Ptr (TBitmap a)) -> IO (Bitmap a)

withRefCursor :: (Ptr (TCursor a) -> IO ()) -> IO (Cursor a)

withManagedCursorResult :: IO (Ptr (TCursor a)) -> IO (Cursor a)

withRefIcon :: (Ptr (TIcon a) -> IO ()) -> IO (Icon a)

withManagedIconResult :: IO (Ptr (TIcon a)) -> IO (Icon a)

withRefPen :: (Ptr (TPen a) -> IO ()) -> IO (Pen a)

withManagedPenResult :: IO (Ptr (TPen a)) -> IO (Pen a)

withRefBrush :: (Ptr (TBrush a) -> IO ()) -> IO (Brush a)

withManagedBrushResult :: IO (Ptr (TBrush a)) -> IO (Brush a)

withRefFont :: (Ptr (TFont a) -> IO ()) -> IO (Font a)

withManagedFontResult :: IO (Ptr (TFont a)) -> IO (Font a)

withRefImage :: (Ptr (TImage a) -> IO ()) -> IO (Image a)

withRefListItem :: (Ptr (TListItem a) -> IO ()) -> IO (ListItem a)

withRefFontData :: (Ptr (TFontData a) -> IO ()) -> IO (FontData a)

withRefPrintData :: (Ptr (TPrintData a) -> IO ()) -> IO (PrintData a)

withRefPageSetupDialogData :: (Ptr (TPageSetupDialogData a) -> IO ()) -> IO (PageSetupDialogData a)

withRefPrintDialogData :: (Ptr (TPrintDialogData a) -> IO ()) -> IO (PrintDialogData a)

withRefDateTime :: (Ptr (TDateTime a) -> IO ()) -> IO (DateTime a)

withManagedDateTimeResult :: IO (Ptr (TDateTime a)) -> IO (DateTime a)

withRefGridCellCoordsArray :: (Ptr (TGridCellCoordsArray a) -> IO ()) -> IO (GridCellCoordsArray a)

withManagedGridCellCoordsArrayResult :: IO (Ptr (TGridCellCoordsArray a)) -> IO (GridCellCoordsArray a)

Primitive types

CString

type CString = Ptr CChar

A C string is a reference to an array of C characters terminated by NUL.

withCString :: String -> (CString -> IO a) -> IO a

Marshal a Haskell string into a NUL terminated C string using temporary storage.

• the Haskell string may not contain any NUL characters
• the memory is freed when the subcomputation terminates (either normally or via an exception), so the pointer to the temporary storage must not be used after this.

withStringResult :: (Ptr CChar -> IO CInt) -> IO String

type CWString = Ptr CWchar

A C wide string is a reference to an array of C wide characters terminated by NUL.

withCWString :: String -> (CWString -> IO a) -> IO a

Marshal a Haskell string into a NUL terminated C wide string using temporary storage.

• the Haskell string may not contain any NUL characters
• the memory is freed when the subcomputation terminates (either normally or via an exception), so the pointer to the temporary storage must not be used after this.

withWStringResult :: (Ptr CWchar -> IO CInt) -> IO String

ByteString

withByteStringResult :: (Ptr CChar -> IO CInt) -> IO ByteString

withLazyByteStringResult :: (Ptr CChar -> IO CInt) -> IO ByteString

CInt

newtype CInt :: *

Haskell type representing the C int type.

Constructors

CInt Int32

Instances

Bounded CInt

Enum CInt

Eq CInt

Integral CInt

Num CInt

Ord CInt

Read CInt

Real CInt

Show CInt

Storable CInt

Bits CInt

FiniteBits CInt

Typeable * CInt

toCInt :: Int -> CInt

fromCInt :: CInt -> Int

withIntResult :: IO CInt -> IO Int

IntPtr

data IntPtr :: *

A signed integral type that can be losslessly converted to and from Ptr. This type is also compatible with the C99 type intptr_t, and can be marshalled to and from that type safely.

Instances

Bounded IntPtr

Enum IntPtr

Eq IntPtr

Integral IntPtr

Num IntPtr

Ord IntPtr

Read IntPtr

Real IntPtr

Show IntPtr

Storable IntPtr

Bits IntPtr

FiniteBits IntPtr

Typeable * IntPtr

CIntPtr

newtype CIntPtr :: *

Constructors

CIntPtr Int64

Instances

Bounded CIntPtr

Enum CIntPtr

Eq CIntPtr

Integral CIntPtr

Num CIntPtr

Ord CIntPtr

Read CIntPtr

Real CIntPtr

Show CIntPtr

Storable CIntPtr

Bits CIntPtr

FiniteBits CIntPtr

Typeable * CIntPtr

toCIntPtr :: IntPtr -> CIntPtr

fromCIntPtr :: CIntPtr -> IntPtr

withIntPtrResult :: IO CIntPtr -> IO IntPtr

Word

data Word :: *

A Word is an unsigned integral type, with the same size as Int.

Instances

Bounded Word

Enum Word

Eq Word

Integral Word

Num Word

Ord Word

Read Word

Real Word

Show Word

Ix Word

Storable Word

Bits Word

FiniteBits Word

Typeable * Word

IArray UArray Word

MArray (STUArray s) Word (ST s)

8 bit Word

data Word8 :: *

8-bit unsigned integer type

Instances

Bounded Word8

Enum Word8

Eq Word8

Integral Word8

Num Word8

Ord Word8

Read Word8

Real Word8

Show Word8

Ix Word8

Storable Word8

Bits Word8

FiniteBits Word8

Typeable * Word8

IArray UArray Word8

MArray (STUArray s) Word8 (ST s)

64 bit Integer

data Int64 :: *

64-bit signed integer type

Instances

Bounded Int64

Enum Int64

Eq Int64

Integral Int64

Num Int64

Ord Int64

Read Int64

Real Int64

Show Int64

Ix Int64

Storable Int64

Bits Int64

FiniteBits Int64

Typeable * Int64

IArray UArray Int64

MArray (STUArray s) Int64 (ST s)

CDouble

newtype CDouble :: *

Haskell type representing the C double type.

Constructors

CDouble Double

Instances

Enum CDouble

Eq CDouble

Floating CDouble

Fractional CDouble

Num CDouble

Ord CDouble

Read CDouble

Real CDouble

RealFloat CDouble

RealFrac CDouble

Show CDouble

Storable CDouble

Typeable * CDouble

toCDouble :: Double -> CDouble

fromCDouble :: CDouble -> Double

withDoubleResult :: IO CDouble -> IO Double

CChar

newtype CChar :: *

Haskell type representing the C char type.

Constructors

CChar Int8

Instances

Bounded CChar

Enum CChar

Eq CChar

Integral CChar

Num CChar

Ord CChar

Read CChar

Real CChar

Show CChar

Storable CChar

Bits CChar

FiniteBits CChar

Typeable * CChar

toCChar :: Char -> CChar

fromCChar :: CChar -> Char

withCharResult :: (Num a, Integral a, Show a) => IO a -> IO Char

newtype CWchar :: *

Haskell type representing the C wchar_t type.

Constructors

CWchar Int32

Instances

Bounded CWchar

Enum CWchar

Eq CWchar

Integral CWchar

Num CWchar

Ord CWchar

Read CWchar

Real CWchar

Show CWchar

Storable CWchar

Bits CWchar

FiniteBits CWchar

Typeable * CWchar

toCWchar :: Num a => Char -> a

CBool

type CBool = CInt

toCBool :: Bool -> CBool

fromCBool :: CBool -> Bool

withBoolResult :: IO CBool -> IO Bool

Pointers

data Ptr a :: * -> *

A value of type Ptr a represents a pointer to an object, or an array of objects, which may be marshalled to or from Haskell values of type a.

The type a will often be an instance of class Storable which provides the marshalling operations. However this is not essential, and you can provide your own operations to access the pointer. For example you might write small foreign functions to get or set the fields of a C struct.

Instances

IArray UArray (Ptr a)

Eq (Ptr a)

Ord (Ptr a)

Show (Ptr a)

Storable (Ptr a)

MArray (STUArray s) (Ptr a) (ST s)

Typeable (* -> *) Ptr

ptrNull :: Ptr a

Null pointer, use with care.

ptrIsNull :: Ptr a -> Bool

Test for null.

ptrCast :: Ptr a -> Ptr b

Cast a pointer type, use with care.

data ForeignPtr a :: * -> *

The type ForeignPtr represents references to objects that are maintained in a foreign language, i.e., that are not part of the data structures usually managed by the Haskell storage manager. The essential difference between ForeignPtrs and vanilla memory references of type Ptr a is that the former may be associated with finalizers. A finalizer is a routine that is invoked when the Haskell storage manager detects that - within the Haskell heap and stack - there are no more references left that are pointing to the ForeignPtr. Typically, the finalizer will, then, invoke routines in the foreign language that free the resources bound by the foreign object.

The ForeignPtr is parameterised in the same way as Ptr. The type argument of ForeignPtr should normally be an instance of class Storable.

Instances

Eq (ForeignPtr a)

Ord (ForeignPtr a)

Show (ForeignPtr a)

Typeable (* -> *) ForeignPtr

data FunPtr a :: * -> *

A value of type FunPtr a is a pointer to a function callable from foreign code. The type a will normally be a foreign type, a function type with zero or more arguments where

• the argument types are marshallable foreign types, i.e. Char, Int, Double, Float, Bool, Int8, Int16, Int32, Int64, Word8, Word16, Word32, Word64, Ptr a, FunPtr a, StablePtr a or a renaming of any of these using newtype.
• the return type is either a marshallable foreign type or has the form IO t where t is a marshallable foreign type or ().

A value of type FunPtr a may be a pointer to a foreign function, either returned by another foreign function or imported with a a static address import like

foreign import ccall "stdlib.h &free"
  p_free :: FunPtr (Ptr a -> IO ())

or a pointer to a Haskell function created using a wrapper stub declared to produce a FunPtr of the correct type. For example:

type Compare = Int -> Int -> Bool
foreign import ccall "wrapper"
  mkCompare :: Compare -> IO (FunPtr Compare)

Calls to wrapper stubs like mkCompare allocate storage, which should be released with freeHaskellFunPtr when no longer required.

To convert FunPtr values to corresponding Haskell functions, one can define a dynamic stub for the specific foreign type, e.g.

type IntFunction = CInt -> IO ()
foreign import ccall "dynamic" 
  mkFun :: FunPtr IntFunction -> IntFunction

Instances

IArray UArray (FunPtr a)

Eq (FunPtr a)

Ord (FunPtr a)

Show (FunPtr a)

Storable (FunPtr a)

MArray (STUArray s) (FunPtr a) (ST s)

Typeable (* -> *) FunPtr

toCFunPtr :: FunPtr a -> Ptr a