Xfce Foundation Classes
Main Page  | IndexNamespace List  |  Alphabetical List  |  Class List  |  File List


Public Types | Public Member Functions
Xfc::G::Source Class Reference

A GSource C++ interface. More...

#include <xfc/glib/main.hh>

Inheritance diagram for Xfc::G::Source:
Xfc::Trackable Xfc::G::ChildWatchSource Xfc::G::IdleSource Xfc::G::IOSource Xfc::G::TimeoutSource

List of all members.

Public Types

Public Member Functions

Constructors

Detailed Description

A GSource C++ interface.

A Custom GSource C++ interface.

A Source corresponds to a single source of input. When sources are created they aren't associated with any main context. Once attached, a source is permanently associated with a particular context and can't be moved to another context.

Source is the base class for the built-in ChildWatchSource, TimeoutSource, IdleSource and IOSource types. In most cases the built-in source types should be enough. When they aren't, or when you need something more powerful, you can create your own custom event source by subclassing G::CustomSource and overriding its pure virtual methods.

One of the unusual features of the GLib/GTK+ main loop functionality is that new types of event source can be created and used in addition to the built-in type of event source. For example, GTK+ creates a new event source type to handle GDK events. A new source type is created by deriving it from CustomSource. The three source methods prepare(), check() and dispatch() determine the behavior of new source types.

New source types basically interact with with the main context in two ways. Their prepare method can set a timeout to determine the maximum amount of time that the main loop will sleep before checking the source again. In addition, or as well, the source can add file descriptors to the set that the main context checks using G::Source::add_poll().

CustomSource has three pure virtual methods: prepare(), check() and dispatch(), that must be overridden in dervied classes. The prepare method asks a source two things: does it have any events, and when does it need to be asked again. For example, a TimeoutSource requires that it wakes up after a certain time elapses. The check method ask a source if it has any events now, taking into account the results of the poll() call. The dispatch method dispatches the sources with events ready by calling the passed in slot.

For idle sources, the prepare and check methods should always return true to indicate that the source is always ready to be processed. The prepare function should also return a timeout value of 0 to ensure that the poll() call doesn't block (since that would be time wasted which could have been spent running the idle function).

For timeout sources, the prepare and check methods should both return true if the timeout interval has expired. The prepare function also returns a timeout value to ensure that the poll() call doesn't block too long and miss the next timeout.

For file descriptor sources, the prepare method typically returns false, since it must wait until poll() has been called before it knows whether any events need to be processed. It should set the returned timeout to -1 to indicate that it doesn't mind how long the poll() call blocks. In the check method, it tests the results of the poll() call to see if the required condition has been met, and returns true if so.


Member Typedef Documentation

typedef sigc::slot<bool> Xfc::G::Source::SourceSlot

Signature of the callback slot passed to timeout, idle and custom sources.

Example: Method signature for SourceSlot.

< bool method();
< // return: The slot should return false if the source should be removed.
<

Constructor & Destructor Documentation

Xfc::G::Source::Source ( GSource *  source,
bool  owns_reference = true 
)

Construct a source from an existing GSource object.

Parameters:
sourceA pointer to a GSource.
owns_referenceSet true if the initial reference count is owned by this object.

The Source object takes over the ownership of the GSource and unreferences it when the destructor is called.


Member Function Documentation

unsigned int Xfc::G::Source::attach ( MainContext context = 0)

Adds the source to context so that it will be executed within that context.

Parameters:
contextA MainContext, or null to use the default context.
Returns:
The ID for the source within the MainContext.

Removes a source from its MainContext, if any, and marks it as destroyed.

After calling this method the source cannot be subsequently added to another context.

Checks whether a source is allowed to be called recursively (see set_can_recurse()).

Returns:
Whether recursion is allowed.

Gets the main context with which the source is associated.

Returns:
The associated MainContext, or null if a context has not yet been added to the source.

Calling this function on a destroyed source is an error.

Gets the "current time" to be used when checking this source.

Parameters:
timevalA TimeVal object in which to store the current time.

The advantage of calling this function over calling G::get_current_time() directly is that when checking multiple sources, GLib can cache a single value instead of having to repeatedly get the system time.

unsigned int Xfc::G::Source::get_id ( ) const

Gets the numeric ID for a particular source.

Returns:
The ID for the source.

Gets the priority of the source.

Returns:
The priority of the source.
bool Xfc::G::Source::is_attached ( G::MainContext context) const

Determines whether context is attached to this source.

Returns:
true if context is attached to this source.
void Xfc::G::Source::set_can_recurse ( bool  can_recurse)

Sets whether a source can be called recursively.

Parameters:
can_recurseWhether recursion is allowed for this source.

If can_recurse is true, while the source is being dispatched the source will be processed normally. Otherwise, all processing of the source is blocked until the dispatch function returns.

void Xfc::G::Source::set_priority ( int  priority)

Sets the priority of the source.

Parameters:
priorityThe new priority.

While the main loop is being run, the source will be dispatched if it is ready to be dispatched and no sources at a higher (numerically smaller) priority are ready to be dispatched.

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

Decrease the source reference count by one.

When the reference count becomes zero for a heap object delete is called. Remember, as with all XFC Objects you must call unref() on a dynamically allocated IOChannel, not delete. If you use a smart you don't need to call unref(), the smart pointer will do that for you. You don't need to call unref() on a source allocated on the stack unless you first called ref().

Reimplemented from Xfc::Trackable.


The documentation for this class was generated from the following file:
Xfce Foundation Classes
Copyright © 2004-2005 The XFC Development Team XFC