openscenegraph
GUIActionAdapter
Go to the documentation of this file.
1/* -*-c++-*- OpenSceneGraph - Copyright (C) 1998-2006 Robert Osfield
2 *
3 * This library is open source and may be redistributed and/or modified under
4 * the terms of the OpenSceneGraph Public License (OSGPL) version 0.0 or
5 * (at your option) any later version. The full license is in LICENSE file
6 * included with this distribution, and on the openscenegraph.org website.
7 *
8 * This library is distributed in the hope that it will be useful,
9 * but WITHOUT ANY WARRANTY; without even the implied warranty of
10 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
11 * OpenSceneGraph Public License for more details.
12*/
13
14#ifndef OSGGA_GUIACTIONADAPTER
15#define OSGGA_GUIACTIONADAPTER 1
16
17#include <osgGA/Export>
18#include <osg/View>
19#include <osgUtil/LineSegmentIntersector>
20
21namespace osgGA{
22
23/**
24Abstract base class defining the interface by which GUIEventHandlers may request
25actions of the GUI system in use. These requests for actions should then be honored
26by the GUI toolkit of the user's application.
27
28To provide more detail, when a GUIEventHandler (e.g. a TrackballManipulator)
29handles an incoming event, such as a mouse event, it may wish to make
30a request of the GUI. E.g. if a model is 'thrown', the trackball manipulator
31may wish to start a timer, and be repeatedly called, to continuously refresh the
32camera's position and orientation. However, it has no way of doing this, as it
33knows nothing of the window system in which it's operating. Instead, the
34GUIEventHandler issues it's request via a GUIActionAdapter, and the viewer
35in use should honour the request, using the GUI system in play.
36
37There is more than one way of using the GUIActionAdapter. E.g. it may be inherited
38into a Viewer class, as is done with osgGLUT::Viewer. Alternatively, a simple
39subclass of GUIActionAdapter (e.g. osgQt::QtActionAdapter) may be passed to
40the GUIEventHandler::handle() function; once the function has returned, the viewer
41will then unpack the results and work out what to do to respond to the
42requests.
43
44Also there are several ways to run your app and handle the updating of
45the window. osgGLUT::Viewer always has a idle callback registered which does a
46redraw all the time. osgGLUT::Viewer can safely ignore both requestRedraw() and
47requestContinousUpdate() as these are happening all the time anyway.
48
49Other apps will probably want to respond to the requestRedraw() and
50requestContinousUpdate(bool) and again there is more than one way to handle it.
51You can override requestRedraw() and implement to call your own window
52redraw straight away. Or you can implement so that a flag is set and
53then you then respond the flag being set in your own leisure.
54
55
56
57*/
58
59class GUIEventAdapter;
60
61class GUIActionAdapter
62{
63public:
64 virtual ~GUIActionAdapter() {}
65
66 /** Provide a mechanism for getting the osg::View associated with this GUIActionAdapter.
67 * One would use this to case view to osgViewer::View(er) if supported by the subclass.*/
68 virtual osg::View* asView() { return 0; }
69
70 /**
71 requestRedraw() requests a single redraw.
72 */
73 virtual void requestRedraw() = 0;
74
75 /**
76 requestContinuousUpdate(bool) is for en/disabling a throw or idle
77 callback to be requested by a GUIEventHandler (typically a CameraManipulator,
78 though other GUIEventHandler's may also provide functionality).
79 GUI toolkits can respond to this immediately by registering an idle/timed
80 callback, or can delay setting the callback and update at their own leisure.
81 */
82 virtual void requestContinuousUpdate(bool needed=true) = 0;
83
84 /**
85 requestWarpPointer(int,int) is requesting a repositioning of the mouse pointer
86 to a specified x,y location on the window. This is used by some camera manipulators
87 to initialise the mouse pointer when mouse position relative to a controls
88 neutral mouse position is required, i.e when mimicking an aircraft joystick.
89 */
90 virtual void requestWarpPointer(float x,float y) = 0;
91
92
93 /** Compute intersections of a ray, starting the current mouse position, through the specified camera. */
94 virtual bool computeIntersections(const osgGA::GUIEventAdapter& /*ea*/, osgUtil::LineSegmentIntersector::Intersections& /*intersections*/,osg::Node::NodeMask /*traversalMask*/ = 0xffffffff) { return false; }
95
96 /** Compute intersections of a ray, starting the current mouse position, through the specified master camera's window/eye coordinates and a specified nodePath's subgraph. */
97 virtual bool computeIntersections(const osgGA::GUIEventAdapter& /*ea*/, const osg::NodePath& /*nodePath*/, osgUtil::LineSegmentIntersector::Intersections& /*intersections*/,osg::Node::NodeMask /*traversalMask*/ = 0xffffffff) { return false; }
98
99};
100
101}
102
103#endif
104