Xfce Foundation Classes
Main Page  | Index |  Namespace List  |  Alphabetical List  |  Class List  |  File List


libXFCui / xfc

libXFCui/xfc/main.hh File Reference

Initialization and main processing loop interface. More...

#include <xfc/pointer.hh>
#include <xfc/gdk/types.hh>
#include <sigc++/sigc++.h>
#include <gtk/gtkmain.h>
#include <vector>

Namespaces

Classes

Initializers

Accessors

Main Event Loop

Signals

Defines

Detailed Description

Initialization and main processing loop interface.

XFC wraps the GTK+ initialization functions and events into the Main namespace rather than a static class. Before using XFC, you need to initialize it. Initialization connects to the window system display, and parses some standard command line arguments. The init() function initializes XFC. init() exits the application if errors occur; to avoid this, use init_check(). init_check() allows you to recover from a failed XFC initialization - you might start up your application in text mode instead.

Like all GUI toolkits, XFC uses an event-driven programming model. When the user is doing nothing, XFC sits in the main loop and waits for input. If the user performs some action - say, a mouse click - then the main loop "wakes up" and delivers an event to XFC. XFC forwards the event to one or more widgets.

When widgets receive an event, they frequently emit one or more signals. Signals notify your program that "something interesting happened" by invoking slots you've connected to the signal with the signal's connect() method. Slots are callable objects that can be connected to signals. Slots can be used to connect static functions, class methods and function objects to a signal. When your slot is called it invokes your function or method.

When your methods are invoked, you would typically take some action - for example, when an Open button is clicked you might display a Gtk::FileSelectionDialog. After a callback finishes, XFC will return to the main loop and await more user input.

Function Documentation

PangoLanguage* default_language (   ) 
 

Get the default language currently in effect.

Returns:
The ISO language code for the default language currently in effect.
Note that this can change over the life of an application. The default language is derived from the current locale. It determines, for example, whether XFC uses the right-to-left or left-to-right text direction.

bool events_pending (   ) 
 

Checks if any events are pending.

Returns:
true if any events are pending, false otherwise.
This can be used to update the GUI and invoke timeouts etc. while doing some time intensive computation.

Example: Updating the GUI during a long computation. 

     // computation going on
     ...
     while (events_pending())
        iterate();
     ...
     // computation continued

Pointer<Gdk::Event> get_current_event (   ) 
 

Obtains a copy of the event currently being processed by GTK+.

Returns:
A copy of the current event, or null if there is no current event.
For example, if you get a "clicked" signal from Gtk::Button, the current event will be the Gdk::EventButton that triggered the "clicked" signal. If there is no current event, the function returns null.

bool get_current_event_state (  Gdk::ModifierTypeField *  state  ) 
 

If there is a current event and it has a state field, place that state field in state and return true, otherwise return false.

Parameters:
state The location to store the state of the current event.
Returns:
true if there was a current event and it had a state field.

unsigned int get_current_event_time (   ) 
 

If there is a current event and it has a timestamp, return that timestamp, otherwise return GDK_CURRENT_TIME.

Returns:
The timestamp from the current event, or GDK_CURRENT_TIME.

Gtk::Widget* get_event_widget (  Gdk::Event &  event  ) 
 

Get the widget that originally received the event.

Parameters:
event A reference to a Gdk::Event.
Returns:
The widget that originally received event, or null.
If event is null or the event was not associated with any widget, returns null, otherwise returns the widget that received the event originally. The widget is returned as a smart pointer because there is the possiblity that the widget was wrapped for the first time and needs to be unreferenced.

GOptionGroup* get_option_group (  bool  open_default_display = true  ) 
 

Returns a GOptionGroup for the commandline arguments recognized by GTK+ and GDK.

Parameters:
open_default_display Whether to open the default display when parsing the commandline arguments.
Returns:
A GOptionGroup for the commandline arguments recognized by GTK+.
You should add this group to your option context with G::OptionContext::add_group(), if you are using G::OptionContext:::parse() to parse your commandline arguments.

void grab_add (  Gtk::Widget &  widget  ) 
 

Makes widget the current grabbed widget.

Parameters:
widget The widget that grabs keyboard and pointer events.
This means that interaction with other widgets in the same application is blocked and mouse as well as keyboard events are delivered to this widget.

Gtk::Widget* grab_get_current (   ) 
 

Queries the current grab.

Returns:
The widget which currently has the grab or null if no grab is active.

void grab_remove (  Gtk::Widget &  widget  ) 
 

Removes the grab from the given widget.

Parameters:
widget The widget which gives up the grab. You have to pair calls to grab_add() and grab_remove().

void init (  int *  argc,
char ***  argv
) 
 

Initialize the XFC library.

Parameters:
argc Address of the argc parameter of your main() function, changed if any arguments were handled.
argv Address of the argv parameter of your main() function, any arguments understood by init() are stripped before returning.
Call this method before using any other XFC methods in your GUI applications. It will initialize everything needed to operate the toolkit and parses some standard command line options. argc and argv are adjusted accordingly so your own code will never see those standard arguments.

void init_add (  const sigc::slot< bool > &  callback  ) 
 

Register a slot to be called when the mainloop is started.

Parameters:
callback A slot to invoke when main() is called next.
The callback slot should return false to remove it from the list of slots to call, otherwise it might get called again.

bool init_check (  int *  argc,
char ***  argv
) 
 

Initialize the XFC library.

Parameters:
argc Address of the argc parameter of your main() function.
argv Address of the argv parameter of your main() function.
Returns:
true if the GUI has been successfully initialized, false otherwise.
This method does the same work as init() with only a single change: It does not terminate the program if the GUI can't be initialized. Instead it returns false on failure. This way the application can fall back to some other means of communication with the user - for example a command line interface.

bool init_with_args (  int *  argc,
char ***  argv,
const char *  parameter_string,
G::OptionGroup &  group,
G::Error *  error
) 
 

Initialize the XFC library.

Parameters:
argc Address of the argc parameter of your main() function.
argv Address of the argv parameter of your main() function.
parameter_string The string to display in the first line of --help output, after programname [OPTION...].
group The option group describing the options of your program.
error The return location for errors.
Returns:
true if the GUI has been successfully initialized, false otherwise.
This method does the same work as init_check(). Additionally, it allows you to add your own commandline options, and it automatically generates nicely formatted --help output. Note that your program will be terminated after writing out the help output.

Example: Initializing your application with optional commandline arguments 

     int repeats = 2;
     int max_size = 8;
     bool verbose = false;
     bool beep = false;
     bool rand = false;
    
     int main (int argc, char *argv[])
     {
         using namespace Main;
         G::OptionGroup group;
         group->add("repeats", 'r', &repeats, "Average over N repetitions", "N");
         group->add("max-size", 'm', &max_size, "Test up to 2^M items", "M");
         group->add("verbose", 'v', &verbose, "Be verbose");
         group->add("beep", 'b', &beep, "Beep when done");
         group->add("rand", 0, &rand, "Randomize the data");
    
         G::Error error;
         init_with_args(&argc, &argv, "- test tree model performance", group, &error);
         ...
     }

bool iterate (  bool  blocking = true  ) 
 

Runs a single iteration of the mainloop.

Parameters:
blocking Set true if you want to block if no events are pending.
Returns:
true if quit() has been called for the innermost mainloop.
If blocking is true and no events are waiting to be processed XFC will block until the next event is noticed. If blocking is false and no events are available return.

int level (   ) 
 

Asks for the current nesting level of the main loop.

Returns:
The nesting level of the current invocation of the main loop.
This can be useful when connecting a slot to the quit_signal.

void run (  Gtk::Window *  main_window = 0  ) 
 

Runs the main loop until quit() is called.

Parameters:
main_window The main application window, or null.
If main_window is specified its "destroy" signal is automatically connected to the Main::quit() function and the window is made visible on the screen. If main_window is null you will have to manage showing and destroying the main window yourself.

You can nest calls to run(). In that case quit() will make the innermost invocation of the main loop return.

Xfce Foundation Classes

Copyright © 2004-2005 The XFC Development Team XFC 4.3