Xfce Foundation Classes

Main Page  | Index |  Namespace List  |  Alphabetical List  |  Class List  |  File List

Xfc::G::Object Class Reference

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

#include <xfc/glib/object.hh>

Inheritance diagram for Xfc::G::Object:

List of all members.

Signal Prototypes

• const NotifySignalType notify_signal

  Notify signal (see signal_notify()).
  

Public Member Functions

Constructors

• virtual ~Object ()

  Destructor.
  

Accessors

• GObject * g_object () const

  Get a pointer to the GObject structure.
  

• operator GObject * () const

  Conversion operator; safely converts a G::Object to a GObject pointer.
  

• 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_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.
  

Signal Methods

• 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 signal_notify (const String &property_name)

  Connect to the notify_signal; emitted when a property on an object is changed.
  

Static Public Member Functions

Accessors

• Object * pointer (GObject *object)

  Get the G::Object pointer for the specified GTK+ object.
  

Templates

• template<typename T, typename gObject> T * wrap (gObject *object, bool owns_reference=false)

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

• template<typename T, typename gObject> T * wrap_new (gObject *object, bool owns_reference=false)

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

Protected Member Functions

Constructors

• Object (GObject *object, bool owns_reference=true)

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

---

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

Xfc::G::Object::Object (  GObject *  object, bool  owns_reference = true )  [explicit, protected]

Construct a new G::Object from an existing GObject. Parameters: object  A pointer to a GObject. owns_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 owns_reference is false the object's initial reference count is floating and must not be unreferenced, unless the object was first referenced. If owns_reference is true the gfcal reference is owned by you and must be unreferenced. Each derived class declares a similar constructor with a default value for owns_reference that indicates whether or not the gfcal reference count is floating. The XFC smart pointer, Xfc::Pointer, uses this value to determine if the object's initial reference count needs to be cleared.

---

Member Function Documentation

bool Xfc::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 Xfc::G::Object::dispose (   )  [virtual]

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

void Xfc::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* Xfc::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* Xfc::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 Xfc::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.

Object* Xfc::G::Object::pointer (  GObject *  object  )  [static]

Get the G::Object pointer for the specified GTK+ object. Parameters: object  A pointer to a GTK+ C object. Returns: A G::Object pointer, or null if the GTK+ object has no C++ wrapper.

virtual void Xfc::G::Object::ref (   )  [virtual]

Increase the reference count of the object. This method is declared virtual for XFC's use only. You are not meant to override it. Reimplemented from Xfc::Trackable. Reimplemented in Xfc::Gtk::Object.

void* Xfc::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 or notify is true. 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) and null is returned. Usually you wont use a destroy function so you can ignore notify.

void* Xfc::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 or notify is true. 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) and null is returned. Usually you wont use a destroy function so you can ignore notify.

void Xfc::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 Xfc::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 Xfc::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.

const NotifySignalProxy Xfc::G::Object::signal_notify (  const String &  property_name  )

Connect to the notify_signal; emitted when a property on an object is changed. Parameters: property_name  The property name to be notified of changes to. If property_name is provided it is appended to the signal name so that the signal connected to becomes "notify::property_name". What this does is ensure that your notification slot is only called if property_name matches the property name of the "notify" signal being emitted.

void Xfc::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 XFC name. Signals in XFC are named by adding the "_signal" suffix to the GTK+ name. For example, the XFC name for the GTK+ "clicked" signal is "clicked_signal".

virtual void Xfc::G::Object::unref (   )  [virtual]

Decrease the reference count of the object. This method is declared virtual for XFC's use only. You are not meant to override it. Reimplemented from Xfc::Trackable.

template<typename T, typename gObject> T* Xfc::G::Object::wrap (  gObject *  object, bool  owns_reference = false )  [static]

Wrap a GTK+ C object in as C++ wrapper class. Parameters: object  A pointer to a GTK+ C object. owns_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 object 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 gObject> T* Xfc::G::Object::wrap_new (  gObject *  object, bool  owns_reference = false )  [static]

Wrap a GTK+ C object in a C++ wrapper class. Parameters: object  A pointer to a GTK+ C object. owns_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 object has not been wrapped before. Usually reference is false. Set reference to true if the wrapped object must be unreferenced when finished.

---

Member Data Documentation

const NotifySignalType Xfc::G::Object::notify_signal [static, protected]

Notify signal (see signal_notify()). Calls a slot with the signature: void function(GParamSpec *pspec); // pspec: A GParamSpec object that holds the meta data specifying the new property.

---

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

• libXFCcore/xfc/glib/object.hh

---

Copyright © 2004-2005 The XFC Development Team

XFC 4.3