OpenSceneGraph/include/osgGA/Export

/* -*-c++-*- OpenSceneGraph - Copyright (C) 1998-2003 Robert Osfield 
 *
 * This library is open source and may be redistributed and/or modified under  
 * the terms of the OpenSceneGraph Public License (OSGPL) version 0.0 or 
 * (at your option) any later version.  The full license is in LICENSE file
 * included with this distribution, and on the openscenegraph.org website.
 * 
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the 
 * OpenSceneGraph Public License for more details.
*/

// The following symbol has a underscore suffix for compatibility.
#ifndef OSGGA_EXPORT_
#define OSGGA_EXPORT_ 1

#if defined(WIN32) && !(defined(__CYGWIN__) || defined(__MINGW32__))
    #pragma warning( disable : 4244 )
    #pragma warning( disable : 4251 )
    #pragma warning( disable : 4267 )
    #pragma warning( disable : 4275 )
    #pragma warning( disable : 4290 )
    #pragma warning( disable : 4786 )
#endif

#if defined(_MSC_VER) || defined(__CYGWIN__) || defined(__MINGW32__) || defined( __BCPLUSPLUS__) || defined( __MWERKS__)
        #  ifdef OSGGA_LIBRARY
        #    define OSGGA_EXPORT   __declspec(dllexport)
        #  else
        #    define OSGGA_EXPORT   __declspec(dllimport)
        #endif /* OSGUTIL_LIBRARY */
#else
        #define OSGGA_EXPORT 
#endif 

#endif


/**

\namespace osgGA

The 'GA' in osgGA stands for 'GUI Abstraction'; the osgGA namespace provides facilities to
help developers write the glue to allow the osg to work with varying window systems.

As a cross-platform, window system-agnostic class library, the OpenSceneGraph
has no direct ties to any given windowing environment. Viewers, however, must at
some level interact with a window system - where Window system may refer to a windowing
API, e.g. GLUT, Qt, FLTK, MFC, ...

There is much commonality in the implementation of Viewers for varying windowing
environments. E.g. most Viewers will update a Camera position in response to a mouse
event, and may request that a timer be started as a result of a model being 'spun'.

The purpose of the osgGA namespace is to centralise the common areas of this
functionality. The viewer writer needs then only write a GUIEventAdapter, a
GUIActionAdapter, and assemble a collection of GUIEventHandlers
as appropriate for the viewer.

Events from the windowing environment are adpated, and then fed into the GUIEventHandlers.
The GUIEventHandlers analyse and take action, and make requests of the windowing
environemnt via the GUIActionAdapter. The viewer writer should then honour these
requests, translating them into calls to the windowing API.

*/


// /**
// 
// \namespace osgGA::CmdLineArgs
// 
// A collection of utilities for processing command line arguments.
// 
// An osgGA::CmdLineArgs::Processor class is provided, which implements a chain
// of responsibilty for handline command line arguments. Each item in the chain
// is a subclass of the abstract osgGA::CmdLineArgs::ArgHandler. A number
// of ArgHandlers are provided, though the user if free to implement their
// own subclasses for specific needs (e.g. to validate an argument which
// takes an integer which must be in a specific range).
// 
// Let's look at an example...
// 
// <h2>Example</h2>
// 
// \code
// 
// #include <osgGA/CmdLineArgs>
// 
// int main(int argc, char* argv[])
// {
//         using namespace osg;
//         using namespace osgGA::CmdLineArgs;
// 
//         // Create some handlers
//         ref_ptr<BoolHandler> helpSwitch(new BoolHandler("[-h]","\t\tPrint this help and exit","-h"));
//         ref_ptr<BoolHandler> verboseSwitch(new BoolHandler("[-v]","\t\tActivate verbose output","-v"));
//         ref_ptr<SwitchStringHandler> configFile(
//                                                                         new SwitchStringHandler("[-config <configfile>",
//                                                                         "\t\tSpecify a config file to load"), "-config");
// 
//         Processor clp;
//         clp.push_back(helpSwitch.get());
//         clp.push_back(verboseSwitch.get());
//         clp.push_back(configFile.get());
// 
//         try{
//                 clp.process(argc,argv);
//         }
//         catch(ArgHandlerX& e){
//                 cerr<<e.what()<<endl;
//                 clp.printUsage(cerr);
//                 exit(1);
//         }
//         catch(...){
//                 cerr<<"Unknown exception caught while processing command line arguments."<<endl;
//                 clp.printUsage(cerr);
//                 exit(1);
//         }
// 
//         if(helpSwitch->wasSpecified()){
//                 clp.printHelp(cerr);
//                 exit(0);
//         }
// 
//         if(verboseSwitch->wasSpecified()){
//                 // Activate verbosity...
//         }
// 
//         if(configFile->wasSpecified()){
//                 loadConfigFile(configFile->getString());
//         }
// 
// }
// 
// \endcode
// 
// The processor takes each argument on the command line in turn, and passes it
// to the ArgHandler chain. Each ArgHandler is given the opportunity to handle
// an argument and - if it requires - any subsequent arguments until the
// end of the argument list (it can do this by incrementing the ArgIterator
// passed to it. If an ArgHandler handles an argument (e.g. it's looking for
// and recognises the argument '-h'), it returns true and further processing of
// the argument stops. If an argument is not handled it is passed to the next
// handler in the chain, and so on, until it is either handled, or it drops off
// the end of the chain.
// 
// A number of pre-written ArgHandlers are supplied. User's may use these
// directly, may write their own, or may extend a pre-written ArgHandler to
// customise it for their specific needs.
// 
// */