Xfce Foundation Classes
Main Page  | IndexNamespace 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:

Xfc::G::TypeInstance Xfc::Trackable Xfc::Atk::Hyperlink Xfc::Atk::Object Xfc::Atk::ObjectFactory Xfc::Atk::Registry Xfc::Atk::Relation Xfc::Atk::RelationSet Xfc::Atk::StateSet Xfc::Gdk::Colormap Xfc::Gdk::Device Xfc::Gdk::Display Xfc::Gdk::DisplayManager Xfc::Gdk::DragContext Xfc::Gdk::Drawable Xfc::Gdk::GC Xfc::Gdk::Image Xfc::Gdk::Keymap Xfc::Gdk::Pixbuf Xfc::Gdk::PixbufAnimation Xfc::Gdk::PixbufAnimationIter Xfc::Gdk::PixbufLoader Xfc::Gdk::Screen Xfc::Gdk::Visual Xfc::Glade::Xml Xfc::Gtk::AccelGroup Xfc::Gtk::AccelMap Xfc::Gtk::Action Xfc::Gtk::ActionGroup Xfc::Gtk::Clipboard Xfc::Gtk::EntryCompletion Xfc::Gtk::IconFactory Xfc::Gtk::IconTheme Xfc::Gtk::ListStore Xfc::Gtk::Object Xfc::Gtk::RcStyle Xfc::Gtk::Settings Xfc::Gtk::SizeGroup Xfc::Gtk::SourceLanguage Xfc::Gtk::SourceLanguagesManager Xfc::Gtk::SourcePrintJob Xfc::Gtk::Style Xfc::Gtk::TextBuffer Xfc::Gtk::TextChildAnchor Xfc::Gtk::TextMark Xfc::Gtk::TextTag Xfc::Gtk::TextTagTable Xfc::Gtk::TreeModelFilter Xfc::Gtk::TreeModelSort Xfc::Gtk::TreeSelection Xfc::Gtk::TreeStore Xfc::Gtk::UIManager Xfc::Gtk::WindowGroup Xfc::Pango::Context Xfc::Pango::Font Xfc::Pango::FontFace Xfc::Pango::FontFamily Xfc::Pango::FontMap Xfc::Pango::Fontset Xfc::Pango::Layout Xfc::Pango::Renderer List of all members.

Signal Prototypes

Public Member Functions

Accessors
Methods
Signal Methods
Signal Proxies

Static Public Member Functions

Accessors
Templates

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.

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

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.

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

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

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.

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::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 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_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::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::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::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::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".

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.

template<typename T, typename gObject>
static 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>
static 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.

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.


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: Xfce Foundation Classes
Copyright © 2004-2005 The XFC Development Team XFC 4.3