Reference Manual

Main Page | Namespace List | Class Hierarchy | Alphabetical List | Compound List | File List | Namespace Members | Compound Members | File Members

# Inti::G::Object Class Reference

Base class for wrapped GTK+ objects and widgets. More...

`#include <inti/glib/object.h>`

Inheritance diagram for Inti::G::Object:

List of all members.

## Public Member Functions

Constructors

- virtual ~Object ()
    Destructor.

Accessors

- GObject * g_object () const
    Get a pointer to the GObject structure.
- GObjectClass * g_object_class () const
    Get a pointer to the GObjectClass structure.
- operator GObject * () const
    Conversion operator; safely converts a G::Object to a GObject pointer.
- void get (const char *first_property_name,...) const
    Gets properties of an object.
- void get_property (const char *property_name, Value &value) const
    Get a property of an object.
- void * get_data (const Quark &quark) const
    Get a user data pointer set by calling set().
- void * get_data (const String &key) const
    Get a user data pointer set by calling set().

Methods

- virtual void ref ()
    Increase the reference count of the object.
- virtual void unref ()
    Decrease the reference count of the object.
- virtual void dispose ()
    Finalize the object.
- void set (const char *first_property_name,...)
    Sets properties on an object.
- void set_property (const char *property_name, const Value &value)
    Set a property on an object.
- void set_data (const Quark &quark, void *data, GDestroyNotify destroy=0)
    Set an opaque named pointer on an object.
- void set_data (const String &key, void *data, GDestroyNotify destroy=0)
    Set an opaque named pointer on an object.
- void * remove_data (const Quark &quark, bool notify=false)
    Remove an opaque named pointer previously set on an object.
- void * remove_data (const String &key, bool notify=false)
    Remove an opaque named pointer previously set on an object.
- unsigned long connect (const char *signal_name, GCallback handler, void *data, GClosureNotify destroy_data=0)
    Connect a function pointer and user data to a signal for a particular object.
- unsigned long connect_after (const char *signal_name, GCallback handler, void *data, GClosureNotify destroy_data=0)
    Connect a function pointer and user data to a signal for a particular object.
- unsigned long connect_swapped (const char *signal_name, GCallback handler, void *data, GClosureNotify destroy_data=0)
    Connect a function pointer and user data to a signal for a particular object.
- void emit_by_name (const char *signal_name,...)
    Emit a signal by name.
- void stop_emission_by_name (const char *detailed_signal)
    Aborts a signal's current emission by name.
- bool disconnect_by_name (const char *signal_name)
    Disconnect a signal by name.

Signal Proxies

- const NotifySignalProxy sig_notify ()
    Connect to the notify_signal; emitted when a property on an object is changed.

## Static Public Member Functions

Templates

- template<typename T> T * pointer (void *obj)
    Get the C++ pointer for a GTK+ object.
- template<typename T, typename gObj> T * wrap (gObj *obj, bool reference=false)
    Wrap a GTK+ C object in as C++ wrapper class.
- template<typename T, typename gObj> T * wrap_new (gObj *obj, bool reference=false)
    Wrap a GTK+ C object in a C++ wrapper class.

## Protected Member Functions

Constructors

- Object (GObject *object, bool reference=true)
    Construct a new G::Object from an existing GObject.

Signal Handlers

- virtual void on_notify (GParamSpec *pspec)
    Called when a property on an object is changed.

## Detailed Description

Base class for wrapped GTK+ objects and widgets.

G::Object wraps the GTK+ stucture GObject and its associated functions. It is the base class from which most C++ wrappers for the various GTK+ objects and widgets are dervied. G::Object is derived from G::TypeInstance and MemoryHandler and is a reference counted object. You reference a G::Object by calling ref(). This increments the internal reference counter. You unreference a G::Object by calling unref(). This decrements the internal reference counter. Objects that derive directly from G::Object are created with a reference count of 1. This initial reference count is owned by you and must be unreferenced. Because you own the initial reference count you don't need to reference the object before using it, but you must remember to unreference it when your finished. When the reference count drops to zero the object is finialized and destroyed. If the object was a created on the heap, operator delete is called to destroy the object. You must not call operator delete. To destroy an object you own a reference to you call unref(). To destroy an object you don't own a reference to you must call dispose();

## Constructor & Destructor Documentation

Inti::G::Object::Object | ( | GObject * | object,
|  | bool | reference = true
| ) | `[explicit, protected]`

Construct a new G::Object from an existing GObject.

Parameters:

  object | A pointer to a GObject.
  reference | Set false if the initial reference count is floating, set true if it's not.

This constructor is used to wrap GTK+ objects. object can be a pointer to newly created GObject or an existing GObject. If reference is false the object's initial reference count is floating and must not be unreferenced, unless the object was first referenced. If reference is true the intial reference is owned by you and must be unreferenced.

Each derived class declares a similar constructor with a default value for reference that indicates whether or not the intial reference count is floating. The Inti smart pointer, Inti::Pointer, uses this value to determine if the object's initial reference count needs to be cleared.

## Member Function Documentation

unsigned long Inti::G::Object::connect | ( | const char * | signal_name,
|  | GCallback | handler,
|  | void * | data,
|  | GClosureNotify | destroy_data = 0
| ) |

Connect a function pointer and user data to a signal for a particular object.

Parameters:

  signal_name | Name of the signal.
  handler | Function pointer to attach to the signal.
  data | Value to pass to your handler.
  destroy_data | Function to call when this particular handler is disconnected.

Returns:
  The connection id.

Usually you wont need to use this connection function. It's defined only for completeness.

unsigned long Inti::G::Object::connect_after | ( | const char * | signal_name,
|  | GCallback | handler,
|  | void * | data,
|  | GClosureNotify | destroy_data = 0
| ) |

Connect a function pointer and user data to a signal for a particular object.

Parameters:

  signal_name | Name of the signal.
  handler | Function pointer to attach to the signal.
  data | Value to pass to your handler.
  destroy_data | Function to call when this particular handler is disconnected.

Returns:
  The connection id.

This connection overrides the default signal behaviour (i.e. GTK_RUN_FIRST and GTK_RUN_LAST) and invokes the user-defined handler after the signal. Usually you wont need to use this connection function. It's defined only for completeness.

unsigned long Inti::G::Object::connect_swapped | ( | const char * | signal_name,
|  | GCallback | handler,
|  | void * | data,
|  | GClosureNotify | destroy_data = 0
| ) |

Connect a function pointer and user data to a signal for a particular object.

Parameters:

  signal_name | Name of the signal.
  handler | Function pointer to attach to the signal.
  data | The user data associated with the handler.
  destroy_data | Function to call when this particular handler is disconnected.

Returns:
  The connection id.

This connection calls the specified handler with the object and data fields swapped.

bool Inti::G::Object::disconnect_by_name | ( | const char * | signal_name | ) |

Disconnect a signal by name.

Parameters:

  signal_name | The name of the signal.

Returns:
  true if the signal was disconnected, false if signal_name is not connected to this object.

This is a convenience method that can be used to disconnect a signal when you don't want to use a Connection object. It looks up the signal_id for signal name and uses it to search for the first signal handler connected to the object. If found, it disconnects the handler and returns true.

virtual void Inti::G::Object::dispose | ( |  | ) | `[virtual]`

| Finalize the object. This method is declared virtual for Inti's use only. Reimplemented in Inti::Gdk::Window, and Inti::Gtk::Object.

void Inti::G::Object::emit_by_name | ( | const char * | signal_name,
|  | ... |
| ) |

Emit a signal by name.

Parameters:

  signal_name | The name of the signal.
  ... | The parameters to pass to the signal handler, followed by a pointer to the return type, if any.

This causes the default handler and user-connected handlers to be run.

void Inti::G::Object::get | ( | const char * | first_property_name,
|  | ... |
| ) | const

Gets properties of an object.

Parameters:

  first_property_name | Name of first property to get the value for.
  ... | Null-terminated list of name-return location pairs.

void* Inti::G::Object::get_data | ( | const String & | key | ) | const

Get a user data pointer set by calling set().

Parameters:

  key | A string naming the user data pointer.

Returns:
  The user data pointer set, or null if none exists.

void* Inti::G::Object::get_data | ( | const Quark & | quark | ) | const

Get a user data pointer set by calling set().

Parameters:

  quark | A G::Quark naming the user data pointer.

Returns:
  The user data pointer set, or null if none exists.

void Inti::G::Object::get_property | ( | const char * | property_name,
|  | Value & | value
| ) | const

Get a property of an object.

Parameters:

  property_name | Name of property to get the value for.
  value | Reference to a G::Value object that will hold the value for property_name.

virtual void Inti::G::Object::on_notify | ( | GParamSpec * | pspec | ) | `[protected, virtual]`

Called when a property on an object is changed.

Parameters:

  pspec | A GParamSpec object that holds the meta data specifying the new property.

template<typename T>
T * Inti::G::Object::pointer | ( | void * | obj | ) | `[inline, static]`

Get the C++ pointer for a GTK+ object.

Parameters:

  obj | A pointer to a GTK+ C object.

Returns:
  The C++ pointer cast to a pointer of type T, or null if no pointer exists.

virtual void Inti::G::Object::ref | ( |  | ) | `[virtual]`

| Increase the reference count of the object. This method is declared virtual for Inti's use only. Reimplemented from Inti::ReferencedBase. Reimplemented in Inti::Gtk::Object.

void* Inti::G::Object::remove_data | ( | const String & | key,
|  | bool | notify = false
| ) |

Remove an opaque named pointer previously set on an object.

Parameters:

  key | A string naming the user data pointer.
  notify | Set true if the destroy function should be invoked (if any was set).

Returns:
  the user data pointer set, or null if none exists.

This function gets back user data pointers stored via set_data() and removes the data from object. If notify is true its destroy function is called (if any was set). Usually you wont use a destroy function so you can ignore notify.

void* Inti::G::Object::remove_data | ( | const Quark & | quark,
|  | bool | notify = false
| ) |

Remove an opaque named pointer previously set on an object.

Parameters:

  quark | A G::Quark, naming the user data pointer.
  notify | Set true if the destroy function should be invoked (if any was set).

Returns:
  The user data pointer set, or null if none exists.

This function gets back user data pointers stored via set_data() and removes the data from object. If notify is true its destroy function is called (if any was set). Usually you wont use a destroy function so you can ignore notify.

void Inti::G::Object::set | ( | const char * | first_property_name,
|  | ... |
| ) |

Sets properties on an object.

Parameters:

  first_property_name | Name of the first property to set the value for.
  ... | The first property value, followed optionally by more name/value pairs, followed by null.

void Inti::G::Object::set_data | ( | const String & | key,
|  | void * | data,
|  | GDestroyNotify | destroy = 0
| ) |

Set an opaque named pointer on an object.

Parameters:

  key | A string naming the user data pointer.
  data | An opaque user data pointer.
  destroy | A static function to invoke with data as its argument, when data needs to be freed.

This sets an opaque, named pointer on an object. The name is specified through a String, and the pointer can be gotten back from the object with get_data() until the object is finalized. Setting a previously set user data pointer, overrides (frees) the old pointer set, using null as the pointer essentially removes the data stored.

void Inti::G::Object::set_data | ( | const Quark & | quark,
|  | void * | data,
|  | GDestroyNotify | destroy = 0
| ) |

Set an opaque named pointer on an object.

Parameters:

  quark | A G::Quark, naming the user data pointer.
  data | An opaque user data pointer.
  destroy | A static function to invoke with data as its argument, when data needs to be freed.

This sets an opaque, named pointer on an object. The name is specified through a G::Quark, and the pointer can be gotten back from the object with get_data() until the object is finalized. Setting a previously set user data pointer, overrides (frees) the old pointer set, using null as the pointer essentially removes the data stored.

void Inti::G::Object::set_property | ( | const char * | property_name,
|  | const Value & | value
| ) |

Set a property on an object.

Parameters:

  property_name | Name of the property to set the value for.
  value | A G::Value that holds the value of the propery being set.

void Inti::G::Object::stop_emission_by_name | ( | const char * | detailed_signal | ) |

Aborts a signal's current emission by name.

Parameters:

  detailed_signal | The name of the signal you wish to stop.

The name of the signal you wish to stop is the GTK+ name, not its Inti name. Signals in Inti are named by adding the "_signal" suffix to the GTK+ name. For example, the Inti name for the GTK+ "clicked" signal is "clicked_signal".

virtual void Inti::G::Object::unref | ( |  | ) | `[virtual]`

| Decrease the reference count of the object. This method is declared virtual for Inti's use only. Reimplemented from Inti::ReferencedBase.

template<typename T, typename gObj>
T * Inti::G::Object::wrap | ( | gObj * | obj,
|  | bool | reference = false
| ) | `[inline, static]`

Wrap a GTK+ C object in as C++ wrapper class.

Parameters:

  obj | A pointer to a GTK+ C object.
  reference | Set true if the GTK+ object must be unreferenced.

Returns:
  A pointer to the C++ class cast to a pointer of type T.

If obj was previously wrapped this function returns the existing C++ pointer cast to a pointer of type T. If no wrapper exists a new one is created. Each GTK+ C object can have only one wrapper. A smart pointer can be used to handle the returned pointer. Otherwise if T->is_referenced() is true, T->unref() must be explicitly called.

template<typename T, typename gObj>
T * Inti::G::Object::wrap_new | ( | gObj * | obj,
|  | bool | reference = false
| ) | `[inline, static]`

Wrap a GTK+ C object in a C++ wrapper class.

Parameters:

  obj | A pointer to a GTK+ C object.
  reference | Set true if the GTK+ object must be unreferenced.

Returns:
  A pointer to the C++ class cast to a pointer of type T.

Only use this if obj has not been wrapped before. Usually reference is false. Set reference to true if the wrapped object must be unreferenced when finished.

The documentation for this class was generated from the following file:

- glib/object.h

Main Page - Footer