2 // Copyright (C) 2005, 2006, 2007, 2008, 2009, 2010 Free Software
5 // This program is free software; you can redistribute it and/or modify
6 // it under the terms of the GNU General Public License as published by
7 // the Free Software Foundation; either version 3 of the License, or
8 // (at your option) any later version.
10 // This program is distributed in the hope that it will be useful,
11 // but WITHOUT ANY WARRANTY; without even the implied warranty of
12 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13 // GNU General Public License for more details.
15 // You should have received a copy of the GNU General Public License
16 // along with this program; if not, write to the Free Software
17 // Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
19 /// \page interface Host Interface
21 /// The core Gnash libraries support a flexible way of interacting with
22 /// hosting applications. This is necessary for ActionScript execution, as
23 /// well as for user notifications.
25 /// 1. The hosting application may ignore any message without dangerous
28 /// 2. A set of expected messages exist, which should be supported for
29 /// proper ActionScript compatibility.
31 /// 3. Users must return the exact type expected (see KnownEvent), as
32 /// no implicit conversion is used. This means, for instance, that
33 /// where a std::string is expected, a const char* may not be used.
35 /// 4. There is the possibility to add custom messages for use in
36 /// ActionScript extensions.
38 /// The rationale for the current design is that hosting applications
39 /// should be able to support as many of the expected messages types as
40 /// they choose using a single interface: gnash::HostInterface::call(). This
41 /// should support various types of argument and various types of
42 /// return, so that the different
44 /// The drawback of this flexibility is that there is no compile-time
45 /// check for the correct use of the interface. Within the core
46 /// libraries, this host interface is accessed only through
47 /// gnash::movie_root::callInterface(),
48 /// ensuring that any mistakes in the hosting application are handled
49 /// safely and logged.
51 #ifndef GNASH_HOST_INTERFACE_H
52 #define GNASH_HOST_INTERFACE_H
54 #include <boost/variant.hpp>
55 #include <boost/any.hpp>
61 /// A custom form of communication with the host application.
63 /// This comprises a string and any type of argument.
67 explicit CustomMessage(const std::string
& s
,
68 const boost::any
& arg
= boost::blank())
73 const std::string
& name() const { return _name
; }
74 const boost::any
& arg() const { return _arg
; }
80 /// Built-in forms of communication with the host application.
82 /// These messages should be supported for ActionScript compatibility.
87 /// The messages that a hosting application should handle.
92 /// Whether to display a mouse pointer
93 /// - Argument type: bool
94 /// - Effects: show mouse if true, hide if false
95 /// - Return: boolean, true if the mouse was visible before
99 /// - Argument type: std::pair<int, int>(x, y)
100 /// - Effects: resize stage to x pixels by y pixels
105 /// - Argument type: none
106 /// - Effects: update the stage
110 /// Whether to show the menu or not
111 /// - Argument type: bool
112 /// - Effects: show menu if true, hide if false
114 /// @todo This is probably insufficient.
117 /// Whether to show in fullscreen or not
118 /// - Argument type: movie_root::DisplayState
119 /// - Effects: display fullscreen if movie_root::DISPLAYSTATE_FULLSCREEN,
124 /// Set system clipboard
125 /// - Argument type: std::string
126 /// - Effects: set system clipboard
130 /// Get screen resolution
131 /// - Argument type: none
132 /// - Effects: get screen resolution
133 /// - Return: std::pair<int, int>(x, y)
137 /// - Argument type: none
138 /// - Effects: get screen DPI
142 /// Get pixel aspect ratio
143 /// - Argument type: none
144 /// - Effects: return pixel aspect ratio
149 /// - Argument type: none
150 /// - Effects: return "Plugin" or "StandAlone"
151 /// - Return: std::string
155 /// - Argument type: none
156 /// - Effects: return "Color" or something else
157 /// - Return: std::string
161 /// - Argument type: std::string
162 /// - Effects: notify the user of an error
167 /// - Argument type: std::string
168 /// - Effects: get the answer to a question
172 /// @todo check if the following types are appropriate.
173 EXTERNALINTERFACE_ISPLAYING
,
174 EXTERNALINTERFACE_PAN
,
175 EXTERNALINTERFACE_PLAY
,
176 EXTERNALINTERFACE_REWIND
,
177 EXTERNALINTERFACE_SETZOOMRECT
,
178 EXTERNALINTERFACE_STOPPLAY
,
179 EXTERNALINTERFACE_ZOOM
182 explicit HostMessage(KnownEvent e
, const boost::any
& arg
= boost::blank())
188 KnownEvent
event() const { return _event
; }
189 const boost::any
& arg() const { return _arg
; }
196 /// Abstract base class for FS handlers
200 virtual void notify(const std::string
& cmd
, const std::string
& arg
) = 0;
201 virtual ~FsCallback() {}
204 /// Abstract base class for hosting app handler
209 virtual ~HostInterface() {}
211 typedef boost::variant
<HostMessage
, CustomMessage
> Message
;
213 /// Pass a message to the hosting application with an optional return
215 /// The core library should access this function through
216 /// movie_root::callInterface() or movie_root::callInterface<>()
218 /// @param e The message to pass
219 /// @return A return of any type. Both callers and users
220 /// should know the expected type.
221 virtual boost::any
call(const Message
& e
) = 0;
223 /// Instruct the hosting application to exit.
225 /// The hosting application may ignore this: do not rely on it
226 /// to exit the program.
227 virtual void exit() = 0;
231 /// Stream a description of any host interface message type.
232 std::ostream
& operator<<(std::ostream
& os
, const HostInterface::Message
& e
);
234 /// Stream a description of an expected message.
235 std::ostream
& operator<<(std::ostream
& os
, HostMessage::KnownEvent e
);