System.Glib.GObject

glib-0.13.4.1: Binding to the GLIB library for Gtk2Hs.

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

System.Glib.GObject

Contents

- Types
- Low level binding functions
  - GType queries
  - Callback support
  - User-Defined Attributes

Description

The base object type for all glib objects

Synopsis

- newtype GObject = GObject (ForeignPtr GObject)
- class GObjectClass o where
- mkGObject :: (ForeignPtr GObject -> GObject, FinalizerPtr a)
- unGObject :: GObject -> ForeignPtr GObject
- toGObject :: GObjectClass o => o -> GObject
- unsafeCastGObject :: GObjectClass o => GObject -> o
- castToGObject :: GObjectClass obj => obj -> obj
- objectUnref :: FinalizerPtr a
- objectNew :: GType -> [(String, GValue)] -> IO (Ptr GObject)
- objectRef :: GObjectClass obj => Ptr obj -> IO ()
- objectRefSink :: GObjectClass obj => Ptr obj -> IO ()
- makeNewGObject :: GObjectClass obj => (ForeignPtr obj -> obj, FinalizerPtr obj) -> IO (Ptr obj) -> IO obj
- constructNewGObject :: GObjectClass obj => (ForeignPtr obj -> obj, FinalizerPtr obj) -> IO (Ptr obj) -> IO obj
- wrapNewGObject :: GObjectClass obj => (ForeignPtr obj -> obj, FinalizerPtr obj) -> IO (Ptr obj) -> IO obj
- gTypeGObject :: GType
- isA :: GObjectClass o => o -> GType -> Bool
- type DestroyNotify = FunPtr (Ptr () -> IO ())
- destroyFunPtr :: DestroyNotify
- destroyStablePtr :: DestroyNotify
- type Quark = CUInt
- quarkFromString :: GlibString string => string -> IO Quark
- objectCreateAttribute :: GObjectClass o => IO (Attr o (Maybe a))
- objectSetAttribute :: GObjectClass o => Quark -> o -> Maybe a -> IO ()
- objectGetAttributeUnsafe :: GObjectClass o => Quark -> o -> IO (Maybe a)

# Types

newtype GObject #

Constructors

GObject (ForeignPtr GObject) |

Instances

Eq GObject # |
Methods (==) :: GObject -> GObject -> Bool # (/=) :: GObject -> GObject -> Bool #
GObjectClass GObject # |
Methods toGObject :: GObject -> GObject # unsafeCastGObject :: GObject -> GObject #

class GObjectClass o where #

Minimal complete definition

toGObject, unsafeCastGObject

Methods

toGObject :: o -> GObject #

Safe upcast.

unsafeCastGObject :: GObject -> o #

Unchecked downcast.

Instances

GObjectClass GObject # |
Methods toGObject :: GObject -> GObject # unsafeCastGObject :: GObject -> GObject #

mkGObject :: (ForeignPtr GObject -> GObject, FinalizerPtr a) #

unGObject :: GObject -> ForeignPtr GObject #

toGObject :: GObjectClass o => o -> GObject #

Safe upcast.

unsafeCastGObject :: GObjectClass o => GObject -> o #

Unchecked downcast.

castToGObject :: GObjectClass obj => obj -> obj #

objectUnref :: FinalizerPtr a #

Decrease the reference counter of an object

# Low level binding functions

All these functions are internal and are only interesting to people writing bindings to GObject-style C libraries.

objectNew :: GType -> [(String, GValue)] -> IO (Ptr GObject) #

Construct a new object (should rairly be used directly)

objectRef :: GObjectClass obj => Ptr obj -> IO () #

Increase the reference counter of an object

objectRefSink :: GObjectClass obj => Ptr obj -> IO () #

Reference and sink an object.

makeNewGObject #

Arguments

:: GObjectClass obj |
=> (ForeignPtr obj -> obj, FinalizerPtr obj) | constructor for the Haskell object and finalizer C function
-> IO (Ptr obj) | action which yields a pointer to the C object
-> IO obj |

This function wraps any object that does not derive from Object. It should be used whenever a function returns a pointer to an existing `GObject` (as opposed to a function that constructs a new object).

- The first argument is the contructor of the specific object.

constructNewGObject :: GObjectClass obj => (ForeignPtr obj -> obj, FinalizerPtr obj) -> IO (Ptr obj) -> IO obj #

This function wraps any newly created objects that derives from GInitiallyUnowned also known as objects with "floating-references". The object will be refSink (for glib versions >= 2.10). On non-floating objects, this function behaves exactly the same as "makeNewGObject".

wrapNewGObject :: GObjectClass obj => (ForeignPtr obj -> obj, FinalizerPtr obj) -> IO (Ptr obj) -> IO obj #

This function wraps any newly created object that does not derived from GInitiallyUnowned (that is a GObject with no floating reference). Since newly created `GObject`s have a reference count of one, they don't need ref'ing.

## GType queries

gTypeGObject :: GType #

The type constant to check if an instance is of `GObject` type.

isA :: GObjectClass o => o -> GType -> Bool #

Determine if this is an instance of a particular GTK type

## Callback support

type DestroyNotify = FunPtr (Ptr () -> IO ()) #

destroyFunPtr :: DestroyNotify #

Many methods in classes derived from GObject take a callback function and a destructor function which is called to free that callback function when it is no longer required. This constants is an address of a functions in C land that will free a function pointer.

destroyStablePtr :: DestroyNotify #

The address of a function freeing a `StablePtr`. See `destroyFunPtr`.

## User-Defined Attributes

type Quark = CUInt #

quarkFromString :: GlibString string => string -> IO Quark #

Create a unique id based on the given string.

objectCreateAttribute :: GObjectClass o => IO (Attr o (Maybe a)) #

Add an attribute to this object.

- The function returns a new attribute that can be set or retrieved from any `GObject`. The attribute is wrapped in a `Maybe` type to reflect the circumstance when the attribute is not set or if it should be unset.

objectSetAttribute :: GObjectClass o => Quark -> o -> Maybe a -> IO () #

Set the value of an association.

objectGetAttributeUnsafe :: GObjectClass o => Quark -> o -> IO (Maybe a) #

Get the value of an association.

- Note that this function may crash the Haskell run-time since the returned type can be forced to be anything. See `objectCreateAttribute` for a safe wrapper around this funciton.