ic
/
magnum
mirror of https://github.com/mosra/magnum.git
6
0
Fork 0
Code Issues Projects Releases Wiki Activity
Browse Source

Platform: ugh, documentation should not be an afterthought.

pull/651/head
Vladimír Vondruš 2 years ago
parent
049a3f8fce
commit
8553c2313b
7 changed files with 478 additions and 201 deletions
Whitespace
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Split View
Diff Options
Show Stats Download Patch File Download Diff File
  1. 190
      doc/platform.dox
  2. 138
      doc/snippets/Platform.cpp
  3. 49
      src/Magnum/Platform/AbstractXApplication.h
  4. 32
      src/Magnum/Platform/AndroidApplication.h
  5. 110
      src/Magnum/Platform/EmscriptenApplication.h
  6. 74
      src/Magnum/Platform/GlfwApplication.h
  7. 86
      src/Magnum/Platform/Sdl2Application.h

190
doc/platform.dox
Unescape View File

@ -31,84 +31,150 @@ namespace Magnum {
@tableofcontents
@m_footernavigation
@ref Platform namespace contains classes integrating Magnum engine into
various toolkits, both windowed and windowless. Each class has slightly
different dependencies and platform requirements, see documentation of
The @ref Platform namespace contains `*Application` classes integrating Magnum
into various toolkits, both windowed and windowless. Each class has slightly
different dependencies and platform requirements, see documentation of the
@ref Platform namespace and particular `*Application` classes for more
information about building and usage with CMake.
All the classes have common API to achieve static polymorphism, so basically
you can use different toolkits on different platforms and the only thing you
need to change is the class name, everything else is the same. Basic usage is
to subclass the chosen `*Application` class and implement required methods.
The classes aim to provide a common API to achieve static polymorphism, which
ultimately means you should be able to use different toolkits on different
platforms by only changing an @cpp #include @ce and linking to a different
library.
@section platform-windowed Windowed applications
Windowed applications provide a window and keyboard and mouse handling. The
de-facto standard and most widely used toolkit is SDL2, which is implemented in
@ref Platform::Sdl2Application. As said above, the usage is similar for all
toolkits, you must provide one-argument constructor and implement at least
@ref Platform::Sdl2Application::drawEvent() "drawEvent()" function. The class
can be then used directly in @cpp main() @ce, but for convenience and
portability it's better to use @ref MAGNUM_SDL2APPLICATION_MAIN() macro.
To simplify the porting, the library provides @cpp Platform::Application @ce
typedef and @cpp MAGNUM_APPLICATION_MAIN() @ce macro (but only if only one
application header is included, to avoid ambiguity). Changing the code to use
different toolkit is then matter of replacing only the @cpp #include @ce
statement (and changing one line in CMake build script, as you see later).
Windowed applications provide a window, keyboard and pointer input handling.
The most widely used toolkit is SDL2, which is implemented in
@ref Platform::Sdl2Application. At the very least, provide an one-argument
constructor and the @relativeref{Platform::Sdl2Application,drawEvent()}
function. The class can be then used directly in @cpp main() @ce, but for
convenience and portability to other toolkits and platforms it's better to use
the @ref MAGNUM_SDL2APPLICATION_MAIN() macro. If just a single application
header is included, the class is aliased to a @cpp Platform::Application @ce
typedef and to a @cpp MAGNUM_APPLICATION_MAIN() @ce macro.
Barebone application implementation which will just clear the window to dark
blue color is shown in the following code listing.
@note Fully contained base application along with CMake setup is available in
`base` branch of [Magnum Bootstrap](https://github.com/mosra/magnum-bootstrap)
@note A fully contained base application along with CMake setup is available in
the `base` branch of the [Magnum Bootstrap](https://github.com/mosra/magnum-bootstrap)
repository.
@snippet Platform.cpp windowed
@subsection platform-windowed-viewport Responding to viewport size changes
@subsection platform-windowed-pointer-events Handling mouse, touch and pen events
All application implementations have a generalized pointer input that covers
mouse, (multi-)touch and pen input in a single interface, exposed through
@relativeref{Platform::Sdl2Application,pointerPressEvent()},
@relativeref{Platform::Sdl2Application,pointerReleaseEvent()} and
@relativeref{Platform::Sdl2Application,pointerMoveEvent()}. Override a subset
based on the events you want to handle. Mouse input is present in every
application, touch and pen support varies based on the underlying toolkit.
To make the application touch- and pen-aware, all you need to do is treat
@relativeref{Platform::Sdl2Application,Pointer::Finger} (and
@relativeref{Platform::AndroidApplication,Pointer::Pen}) the same way as
@relativeref{Platform::Sdl2Application,Pointer::MouseLeft}. The pointer types
can be ORed into an enum set for a simpler check, as shown below. Additionally,
pointer events report also secondary touches from multi-touch interfaces.
Unless you specifically handle multi-touch gestures in the application, it
makes sense to handle only primary touches, i.e. only the first pressed finger,
with @relativeref{Platform::Sdl2Application,PointerEvent::isPrimary()}. Mouse
and pen input is marked as primary always.
@snippet Platform.cpp windowed-pointer-events
In addition to the above generalized interface, there's
@relativeref{Platform::Sdl2Application,scrollEvent()} providing 2D scroll
events from a mouse wheel, trackball or touchpad.
@subsection platform-windowed-key-events Attaching to keyboard and text input
The @relativeref{Platform::Sdl2Application,keyPressEvent()} and
@relativeref{Platform::Sdl2Application,keyReleaseEvent()} provide key input
events, both a from a physical keyboard and a virtual one on touch-only
devices. Apart from the @relativeref{Platform::Sdl2Application,Key} being
pressed or released, they track information about which keyboard
@relativeref{Platform::Sdl2Application,Modifiers} are pressed.
For text input there's @relativeref{Platform::Sdl2Application,textInputEvent()},
which has to be explicitly enabled with
@relativeref{Platform::Sdl2Application,startTextInput()} and then disabled
again with @relativeref{Platform::Sdl2Application,stopTextInput()}. The text
input directly gives the application bits of UTF-8 text, matching current
keyboard layout, system configuration and other platform-specific state.
Key events are still fired even with text input enabled in order to be able to
react to arrow keys for cursor movement, editing shortcuts and such. Key events
* *should not* be used for getting actual typed characters, attempting to do so
will never lead to a solution that works reliably on all platforms.
@snippet Platform.cpp windowed-key-events
For [IME](https://en.wikipedia.org/wiki/Input_method) and other advanced text
editing, certain application implementations provide also a
@relativeref{Platform::Sdl2Application,textEditingEvent()}.
@section platform-windowed-configuration Specifying configuration
By default the application is created with reasonable defaults (such as a
window size of 800x600 pixels). Pass a
@relativeref{Platform::Sdl2Application,Configuration} instance to the
application constructor to modify those. Using method chaining it can be done
conveniently like this:
@snippet Platform.cpp windowed-configuration
@subsection platform-windowed-viewport-events Responding to window size changes
By default the application doesn't respond to window size changes in any way,
as the window has fixed size in most cases. To respond to size change for
example by resizing the default framebuffer, you need to reimplement
@ref Platform::Sdl2Application::viewportEvent() "viewportEvent()" function and
pass the new size to the framebuffer:
and the window has a fixed size. To make the window resizable and properly
respond to size changes, construct the application with
@relativeref{Platform::Sdl2Application,Configuration::WindowFlag::Resizable}
and override the @relativeref{Platform::Sdl2Application,viewportEvent()}
function, where you pass the new size to the default framebuffer and where else
is appropriate:
@snippet Platform.cpp size
@snippet Platform.cpp windowed-viewport-events
@section platform-windowless Windowless applications
Windowless applications provide just a context for ofscreen rendering or
performing tasks on GPU. There is not yet any platform-independent toolkit
Windowless applications provide just a context for offscreen rendering or for
performing tasks on a GPU. For OpenGL there is no platform-independent toolkit
which could handle this in portable way, thus you have to use platform-specific
ones. Magnum provides windowless applications for X11-based Unix, macOS and
Windows. To make things simple, as an example we will use only
@ref Platform::WindowlessEglApplication, see link for bootstrap application
below for fully portable example.
You need to implement just @ref Platform::WindowlessEglApplication::exec() "exec()"
function. The class can be then used directly in @cpp main() @ce, but again,
for convenience and portability it's better to use
@ref MAGNUM_WINDOWLESSEGLAPPLICATION_MAIN() macro.
Similarly as with windowed applications, to simplify the porting, the library
provides @cpp Platform::WindowlessApplication @ce typedef and
@cpp MAGNUM_WINDOWLESSAPPLICATION_MAIN() @ce macro, but only if just one
windowless application header is included. Changing the code to use different
toolkit is then matter of replacing only the @cpp #include @ce statement.
Aliases for windowless applications are separated from aliases for windowed
applications, because projects commonly contain both graphics application and
command-line tools (for data preparation etc.).
Barebone application which will just print out current OpenGL version and
renderer string and exits is in the following code listing.
@note Fully contained windowless application using @ref Platform::WindowlessCglApplication
on macOS, @ref Platform::WindowlessGlxApplication on Unix and
implementations. Magnum provides windowless applications for GLX and EGL on
Unix, CGL on macOS and WGL or EGL on Windows. To make things simple, as an
example we will use only @ref Platform::WindowlessEglApplication, below is a
link to a bootstrap application for a fully cross-platform example.
You need to implement just the
@relativeref{Platform::WindowlessEglApplication,exec()} function. The class can
be then used directly in @cpp main() @ce, but again, for convenience and
portability it's better to use the @ref MAGNUM_WINDOWLESSEGLAPPLICATION_MAIN()
macro.
Similarly as with windowed applications, if just a single windowless
application header is included, the library provides a
@cpp Platform::WindowlessApplication @ce typedef and a
@cpp MAGNUM_WINDOWLESSAPPLICATION_MAIN() @ce macro. Changing the code to use
a different toolkit is then again a matter of using a different
@cpp #include @ce and linking to a different library. Aliases for windowless
applications are separated from aliases for windowed applications, because
projects commonly contain both graphics applications and helper command-line
tools for data processing and such.
A barebone application which will just print out the current OpenGL version and
renderer string is in the following code listing.
@note A fully contained windowless application using
@ref Platform::WindowlessCglApplication on macOS,
@ref Platform::WindowlessGlxApplication /
@ref Platform::WindowlessEglApplication on Unix and
@ref Platform::WindowlessWglApplication on Windows along with CMake setup
is available in `windowless` branch of [Magnum Bootstrap](https://github.com/mosra/magnum-bootstrap)
repository.
is available in the `windowless` branch of the
[Magnum Bootstrap](https://github.com/mosra/magnum-bootstrap) repository.
@snippet Platform-windowless.cpp windowless
@ -134,17 +200,7 @@ target_link_libraries(myapplication
Magnum::Application)
@endcode
@section platform-configuration Specifying configuration
By default the application is created with some reasonable defaults (e.g.
window size 800x600 pixels). If you want something else, you can pass
@ref Platform::Sdl2Application::Configuration "Configuration" instance to
application constructor. Using method chaining it can be done conveniently like
this:
@snippet Platform.cpp configuration
@subsection platform-configuration-delayed Delayed context creation
@section platform-configuration-delayed Delayed context creation
Sometimes you may want to set up the application based on a configuration file
or system introspection, which can't really be done inside the base class

138
doc/snippets/Platform.cpp
Unescape View File

@ -41,19 +41,21 @@
#include <Magnum/Platform/GLContext.h>
using namespace Magnum;
using namespace Magnum::Math::Literals;
class MyApplication: public Platform::Application {
public:
MyApplication(const Arguments& arguments);
explicit MyApplication(const Arguments& arguments);
private:
void drawEvent() override;
};
MyApplication::MyApplication(const Arguments& arguments): Platform::Application{arguments} {
using namespace Math::Literals;
/* Set clear color to dark blue */
GL::Renderer::setClearColor(0x000066_rgbf);
MyApplication::MyApplication(const Arguments& arguments):
Platform::Application{arguments}
{
/* Set clear color to a nice blue */
GL::Renderer::setClearColor(0x2f83cc_rgbf);
}
void MyApplication::drawEvent() {
@ -70,42 +72,100 @@ MAGNUM_APPLICATION_MAIN(MyApplication)
/* In this case `int main()` can't be avoided, but other snippets compiled into
the same static library all use a different name so it shouldn't conflict */
/* Sdl2Application is included unconditionally as part of a snippet above, and
it doesn't implement Pointer::Finger on Emscripten */
#ifndef CORRADE_TARGET_EMSCRIPTEN
namespace B {
/* [size] */
/* [windowed-pointer-events] */
class MyApplication: public Platform::Application {
// ...
DOXYGEN_ELLIPSIS()
private:
void viewportEvent(ViewportEvent& event) override;
void pointerPressEvent(PointerEvent& event) override {
/* Handling just left mouse press or equivalent */
if(!event.isPrimary() ||
!(event.pointer() & (Pointer::MouseLeft|Pointer::Finger)))
return;
DOXYGEN_ELLIPSIS()
event.setAccepted();
}
void pointerReleaseEvent(PointerEvent& event) override {
/* Handling just left mouse press or equivalent */
if(!event.isPrimary() ||
!(event.pointer() & (Pointer::MouseLeft|Pointer::Finger)))
return;
DOXYGEN_ELLIPSIS()
event.setAccepted();
}
void pointerMoveEvent(PointerMoveEvent& event) override {
/* Handling just left mouse drag or equivalent */
if(!event.isPrimary() ||
!(event.pointers() & (Pointer::MouseLeft|Pointer::Finger)))
return;
DOXYGEN_ELLIPSIS()
event.setAccepted();
}
};
/* [windowed-pointer-events] */
// ...
void MyApplication::viewportEvent(ViewportEvent& event) {
GL::defaultFramebuffer.setViewport({{}, event.framebufferSize()});
}
/* [size] */
#endif
namespace C {
/* [windowed-key-events] */
class MyApplication: public Platform::Application {
DOXYGEN_ELLIPSIS(void performUndo() {} void performRedo() {} void performInput(int, Containers::StringView) {})
private:
void keyPressEvent(KeyEvent& event) override {
/* Editing shortcuts */
if(event.key() == Key::Z &&
event.modifiers() == Modifier::Ctrl)
performUndo(DOXYGEN_ELLIPSIS());
else if(event.key() == Key::Z &&
event.modifiers() == (Modifier::Shift|Modifier::Ctrl))
performRedo(DOXYGEN_ELLIPSIS());
DOXYGEN_ELLIPSIS()
else return;
event.setAccepted();
}
void textInputEvent(TextInputEvent& event) override {
/* Assuming text input is currently active */
performInput(DOXYGEN_ELLIPSIS(0), event.text());
event.setAccepted();
}
};
/* [windowed-key-events] */
}
namespace C {
namespace D {
struct MyApplication: Platform::Application {
MyApplication(const Arguments& arguments);
explicit MyApplication(const Arguments& arguments);
void foo();
};
/* [configuration] */
/* [windowed-configuration] */
MyApplication::MyApplication(const Arguments& arguments):
Platform::Application{arguments, Configuration{}
.setTitle("My Application")
.setSize({800, 600})}
.setSize({12800, 800})}
{
// ...
DOXYGEN_ELLIPSIS()
}
/* [configuration] */
/* [windowed-configuration] */
void MyApplication::foo() {
/* [Sdl2Application-dpi-scaling] */
@ -116,9 +176,29 @@ static_cast<void>(scaling);
}
namespace D {
namespace E {
constexpr Vector2i size;
/* [windowed-viewport-events] */
class MyApplication: public Platform::Application {
public:
explicit MyApplication(const Arguments& arguments):
Platform::Application{arguments, Configuration{}
.addWindowFlags(Configuration::WindowFlag::Resizable)}
{
DOXYGEN_ELLIPSIS()
}
private:
void viewportEvent(ViewportEvent& event) override {
GL::defaultFramebuffer.setViewport({{}, event.framebufferSize()});
DOXYGEN_ELLIPSIS()
}
};
/* [windowed-viewport-events] */
}
namespace F {
struct MyApplication: Platform::Application {
MyApplication(const Arguments& arguments);
@ -128,19 +208,19 @@ struct MyApplication: Platform::Application {
MyApplication::MyApplication(const Arguments& arguments):
Platform::Application{arguments, NoCreate}
{
// ...
DOXYGEN_ELLIPSIS(Vector2i size;)
create(Configuration{}
.setTitle("My Application")
.setSize(size));
// ...
DOXYGEN_ELLIPSIS()
}
/* [createcontext] */
}
namespace E {
namespace G {
struct MyApplication: Platform::Application {
MyApplication(const Arguments& arguments);
@ -150,7 +230,7 @@ struct MyApplication: Platform::Application {
MyApplication::MyApplication(const Arguments& arguments):
Platform::Application{arguments, NoCreate}
{
// ...
DOXYGEN_ELLIPSIS()
Configuration conf;
conf.setTitle("My Application");
@ -160,13 +240,13 @@ MyApplication::MyApplication(const Arguments& arguments):
if(!tryCreate(conf, glConf))
create(conf, glConf.setSampleCount(0));
// ...
DOXYGEN_ELLIPSIS()
}
/* [trycreatecontext] */
}
namespace F {
namespace H {
/* On MSVC 2017, deprecation warning suppression doesn't work on virtual
function overrides, so ScreenedApplication overriding mousePressEvent(),
@ -218,7 +298,7 @@ for(Platform::Screen* s = app.screens().first(); s; s = s->nextFartherScreen())
}
namespace G {
namespace I {
struct MyApplication: Platform::Application {
MyApplication(const Arguments& arguments);
@ -243,7 +323,7 @@ MyApplication::MyApplication(const Arguments& arguments):
}
#if defined(CORRADE_TARGET_UNIX) || (defined(CORRADE_TARGET_WINDOWS) && !defined(CORRADE_TARGET_WINDOWS_RT)) || defined(CORRADE_TARGET_EMSCRIPTEN)
namespace H {
namespace J {
struct MyApplication: Platform::Application {
MyApplication(const Arguments& arguments);

49
src/Magnum/Platform/AbstractXApplication.h
Unescape View File

@ -125,7 +125,7 @@ class AbstractXApplication {
* @brief Set of keyboard modifiers
* @m_since_latest
*
* @see @ref InputEvent::modifiers()
* @see @ref InputEvent::modifiers(), @ref platform-windowed-key-events
*/
typedef Containers::EnumSet<Modifier> Modifiers;
@ -134,7 +134,8 @@ class AbstractXApplication {
* @m_since_latest
*
* @see @ref KeyEvent::pointers(), @ref PointerMoveEvent::pointers(),
* @ref ScrollEvent::pointers()
* @ref ScrollEvent::pointers(),
* @ref platform-windowed-pointer-events
*/
typedef Containers::EnumSet<Pointer> Pointers;
@ -290,6 +291,7 @@ class AbstractXApplication {
* cameras, framebuffers etc. in application constructor rather than
* relying on this function to be called. Size of the window can be
* retrieved using @ref windowSize().
* @see @ref platform-windowed-viewport-events
*/
virtual void viewportEvent(ViewportEvent& event);
@ -304,10 +306,20 @@ class AbstractXApplication {
/** @{ @name Keyboard handling */
/** @copydoc Sdl2Application::keyPressEvent() */
/**
* @brief Key press event
*
* Called when a key is pressed. Default implementation does nothing.
* @see @ref platform-windowed-key-events
*/
virtual void keyPressEvent(KeyEvent& event);
/** @copydoc Sdl2Application::keyReleaseEvent() */
/**
* @brief Key release event
*
* Called when a key is released. Default implementation does nothing.
* @see @ref platform-windowed-key-events
*/
virtual void keyReleaseEvent(KeyEvent& event);
/* Since 1.8.17, the original short-hand group closing doesn't work
@ -331,6 +343,7 @@ class AbstractXApplication {
* implementation delegates to @ref mousePressEvent(). On builds with
* deprecated functionality disabled, default implementation does
* nothing.
* @see @ref platform-windowed-pointer-events
*/
virtual void pointerPressEvent(PointerEvent& event);
@ -358,6 +371,7 @@ class AbstractXApplication {
* implementation delegates to @ref mouseReleaseEvent(). On builds with
* deprecated functionality disabled, default implementation does
* nothing.
* @see @ref platform-windowed-pointer-events
*/
virtual void pointerReleaseEvent(PointerEvent& event);
@ -388,6 +402,7 @@ class AbstractXApplication {
* @ref mousePressEvent() or @ref mouseReleaseEvent(). On builds with
* deprecated functionality disabled, default implementation does
* nothing.
* @see @ref platform-windowed-pointer-events
*/
virtual void pointerMoveEvent(PointerMoveEvent& event);
@ -414,6 +429,7 @@ class AbstractXApplication {
* implementation delegates to @ref mousePressEvent() and
* @ref mouseReleaseEvent() with @ref MouseEvent::Button::WheelDown and
* @ref MouseEvent::Button::WheelUp.
* @see @ref platform-windowed-pointer-events
*/
virtual void scrollEvent(ScrollEvent& event);
@ -468,7 +484,8 @@ class AbstractXApplication {
@brief Keyboard modifier
@m_since_latest
@see @ref Modifiers, @ref InputEvent::modifiers()
@see @ref Modifiers, @ref InputEvent::modifiers(),
@ref platform-windowed-key-events
*/
enum class AbstractXApplication::Modifier: unsigned int {
/**
@ -515,7 +532,7 @@ CORRADE_ENUMSET_OPERATORS(AbstractXApplication::Modifiers)
@brief Key
@m_since_latest
@see @ref KeyEvent::key()
@see @ref KeyEvent::key(), @ref platform-windowed-key-events
*/
enum class AbstractXApplication::Key: KeySym {
/**
@ -851,7 +868,8 @@ enum class AbstractXApplication::Key: KeySym {
@brief Pointer event source
@m_since_latest
@see @ref PointerEvent::source(), @ref PointerMoveEvent::source()
@see @ref PointerEvent::source(), @ref PointerMoveEvent::source(),
@ref platform-windowed-pointer-events
*/
enum class AbstractXApplication::PointerEventSource: UnsignedByte {
/**
@ -868,7 +886,7 @@ enum class AbstractXApplication::PointerEventSource: UnsignedByte {
@see @ref Pointers, @ref KeyEvent::pointers(), @ref PointerEvent::pointer(),
@ref PointerMoveEvent::pointer(), @ref PointerMoveEvent::pointers(),
@ref ScrollEvent::pointers()
@ref ScrollEvent::pointers(), @ref platform-windowed-pointer-events
*/
enum class AbstractXApplication::Pointer: UnsignedByte {
/**
@ -1061,7 +1079,7 @@ class AbstractXApplication::Configuration {
/**
@brief Viewport event
@see @ref viewportEvent()
@see @ref viewportEvent(), @ref platform-windowed-viewport-events
*/
class AbstractXApplication::ViewportEvent {
public:
@ -1162,7 +1180,7 @@ class AbstractXApplication::InputEvent {
/** @copydoc Sdl2Application::InputEvent::isAccepted() */
bool isAccepted() const { return _accepted; }
/** @brief Modifiers */
/** @brief Keyboard modifiers */
AbstractXApplication::Modifiers modifiers() const {
return AbstractXApplication::Modifiers(_modifiers & (ShiftMask|ControlMask|Mod1Mask|Mod5Mask|LockMask|Mod2Mask));
}
@ -1201,7 +1219,8 @@ CORRADE_IGNORE_DEPRECATED_POP
/**
@brief Key event
@see @ref keyPressEvent(), @ref keyReleaseEvent()
@see @ref keyPressEvent(), @ref keyReleaseEvent(),
@ref platform-windowed-key-events
*/
class AbstractXApplication::KeyEvent: public AbstractXApplication::InputEvent {
public:
@ -1243,7 +1262,7 @@ class AbstractXApplication::KeyEvent: public AbstractXApplication::InputEvent {
@m_since_latest
@see @ref PointerMoveEvent, @ref pointerPressEvent(),
@ref pointerReleaseEvent()
@ref pointerReleaseEvent(), @ref platform-windowed-pointer-events
*/
class AbstractXApplication::PointerEvent: public InputEvent {
public:
@ -1362,7 +1381,8 @@ class CORRADE_DEPRECATED("use PointerEvent, pointerPressEvent() and pointerRelea
@brief Pointer move event
@m_since_latest
@see @ref PointerEvent, @ref pointerMoveEvent()
@see @ref PointerEvent, @ref pointerMoveEvent(),
@ref platform-windowed-pointer-events
*/
class AbstractXApplication::PointerMoveEvent: public InputEvent {
public:
@ -1469,7 +1489,8 @@ class CORRADE_DEPRECATED("use PointerMoveEvent and pointerMoveEvent() instead")
@brief Scroll event
@m_since_latest
@see @ref PointerEvent, @ref PointerMoveEvent, @ref scrollEvent()
@see @ref PointerEvent, @ref PointerMoveEvent, @ref scrollEvent(),
@ref platform-windowed-pointer-events
*/
class AbstractXApplication::ScrollEvent: public InputEvent {
public:

32
src/Magnum/Platform/AndroidApplication.h
Unescape View File

@ -162,7 +162,7 @@ output to Android log buffer with tag `"magnum"`, which can be then accessed
through `logcat` utility. See also @ref Corrade::Utility::AndroidLogStreamBuffer
for more information.
@section Platform-AndroidApplication-touch Touch input
@section Platform-AndroidApplication-touch Touch input on Android
The application recognizes touch and pen input and reports it as
@ref Pointer::Finger, @ref Pointer::Pen, @ref Pointer::Eraser with
@ -192,6 +192,9 @@ lifted, and then never again, or the IDs may get heavily reused, being unique
only for the period given finger is pressed. For @ref PointerEventSource::Mouse
and @ref PointerEventSource::Pen the ID is a constant, as there's always just
a single mouse cursor or a pen stylus.
See also @ref platform-windowed-pointer-events for general information about
handling pointer input in a portable way.
*/
class AndroidApplication {
public:
@ -219,7 +222,8 @@ class AndroidApplication {
* @brief Set of pointer types
* @m_since_latest
*
* @see @ref PointerMoveEvent::pointers()
* @see @ref PointerMoveEvent::pointers(),
* @ref platform-windowed-pointer-events
*/
typedef Containers::EnumSet<Pointer> Pointers;
@ -421,6 +425,7 @@ class AndroidApplication {
* via @ref framebufferSize() and DPI scaling using @ref dpiScaling().
* See @ref Platform-GlfwApplication-dpi for detailed info about these
* values.
* @see @ref platform-windowed-viewport-events
*/
virtual void viewportEvent(ViewportEvent& event);
@ -449,6 +454,8 @@ class AndroidApplication {
* implementation delegates to @ref mousePressEvent(). On builds with
* deprecated functionality disabled, default implementation does
* nothing.
* @see @ref platform-windowed-pointer-events,
* @ref Platform-AndroidApplication-touch
*/
virtual void pointerPressEvent(PointerEvent& event);
@ -476,6 +483,8 @@ class AndroidApplication {
* implementation delegates to @ref mouseReleaseEvent(). On builds with
* deprecated functionality disabled, default implementation does
* nothing.
* @see @ref platform-windowed-pointer-events,
* @ref Platform-AndroidApplication-touch
*/
virtual void pointerReleaseEvent(PointerEvent& event);
@ -506,6 +515,8 @@ class AndroidApplication {
* @ref mousePressEvent() or @ref mouseReleaseEvent(). On builds with
* deprecated functionality disabled, default implementation does
* nothing.
* @see @ref platform-windowed-pointer-events,
* @ref Platform-AndroidApplication-touch
*/
virtual void pointerMoveEvent(PointerMoveEvent& event);
@ -581,7 +592,9 @@ class AndroidApplication {
@brief Pointer event source
@m_since_latest
@see @ref PointerEvent::source(), @ref PointerMoveEvent::source()
@see @ref PointerEvent::source(), @ref PointerMoveEvent::source(),
@ref platform-windowed-pointer-events,
@ref Platform-AndroidApplication-touch
*/
enum class AndroidApplication::PointerEventSource: UnsignedByte {
/**
@ -619,7 +632,9 @@ enum class AndroidApplication::PointerEventSource: UnsignedByte {
@m_since_latest
@see @ref Pointers, @ref PointerEvent::pointer(),
@ref PointerMoveEvent::pointer(), @ref PointerMoveEvent::pointers()
@ref PointerMoveEvent::pointer(), @ref PointerMoveEvent::pointers(),
@ref platform-windowed-pointer-events,
@ref Platform-AndroidApplication-touch
*/
enum class AndroidApplication::Pointer: UnsignedByte {
/**
@ -885,7 +900,7 @@ class AndroidApplication::Configuration {
/**
@brief Viewport event
@see @ref viewportEvent()
@see @ref viewportEvent(), @ref platform-windowed-viewport-events
*/
class AndroidApplication::ViewportEvent {
public:
@ -983,7 +998,8 @@ class AndroidApplication::InputEvent {
@m_since_latest
@see @ref PointerMoveEvent, @ref pointerPressEvent(),
@ref pointerReleaseEvent()
@ref pointerReleaseEvent(), @ref platform-windowed-pointer-events,
@ref Platform-AndroidApplication-touch
*/
class AndroidApplication::PointerEvent: public InputEvent {
public:
@ -1104,7 +1120,9 @@ class CORRADE_DEPRECATED("use PointerEvent, pointerPressEvent() and pointerRelea
@brief Pointer move event
@m_since_latest
@see @ref PointerEvent, @ref pointerMoveEvent()
@see @ref PointerEvent, @ref pointerMoveEvent(),
@ref platform-windowed-pointer-events,
@ref Platform-AndroidApplication-touch
*/
class AndroidApplication::PointerMoveEvent: public InputEvent {
public:

110
src/Magnum/Platform/EmscriptenApplication.h
Unescape View File

@ -185,7 +185,7 @@ If no other application header is included, this class is also aliased to
@cpp Platform::Application @ce and the macro is aliased to
@cpp MAGNUM_APPLICATION_MAIN() @ce to simplify porting.
@section Platform-EmscriptenApplication-touch Touch input
@section Platform-EmscriptenApplication-touch Touch input in HTML5
The application recognizes touch input and reports it as @ref Pointer::Finger
and @ref PointerEventSource::Touch. Because both mouse and touch events are
@ -218,6 +218,9 @@ lifted, and then never again, or the IDs may get heavily reused, being unique
only for the period given finger is pressed. For @ref PointerEventSource::Mouse
the ID is a constant, as there's always just a single mouse cursor.
See also @ref platform-windowed-pointer-events for general information about
handling pointer input in a portable way.
@section Platform-EmscriptenApplication-browser Browser-specific behavior
Leaving a default (zero) size in @ref Configuration will cause the app to use a
@ -355,7 +358,8 @@ class EmscriptenApplication {
*
* @see @ref KeyEvent::modifiers(), @ref PointerEvent::modifiers(),
* @ref PointerMoveEvent::modifiers(),
* @ref ScrollEvent::modifiers()
* @ref ScrollEvent::modifiers(),
* @ref platform-windowed-key-events
*/
typedef Containers::EnumSet<Modifier> Modifiers;
@ -363,7 +367,9 @@ class EmscriptenApplication {
* @brief Set of pointer types
* @m_since_latest
*
* @see @ref PointerMoveEvent::pointers()
* @see @ref PointerMoveEvent::pointers(),
* @ref platform-windowed-pointer-events,
* @ref Platform-EmscriptenApplication-touch
*/
typedef Containers::EnumSet<Pointer> Pointers;
@ -639,7 +645,25 @@ class EmscriptenApplication {
void redraw();
private:
/** @copydoc GlfwApplication::viewportEvent(ViewportEvent&) */
/**
* @brief Viewport event
*
* Called when window size changes. The default implementation does
* nothing. If you want to respond to size changes, you should pass the
* new size to @ref GL::DefaultFramebuffer::setViewport() (if using
* OpenGL) and possibly elsewhere (to
* @ref SceneGraph::Camera::setViewport(), other framebuffers...).
*
* Note that this function might not get called at all if the window
* size doesn't change. You should configure the initial state of your
* cameras, framebuffers etc. in application constructor rather than
* relying on this function to be called. Size of the window can be
* retrieved using @ref windowSize(), size of the backing framebuffer
* via @ref framebufferSize() and DPI scaling using @ref dpiScaling().
* See @ref Platform-EmscriptenApplication-dpi for detailed info about
* these values.
* @see @ref platform-windowed-viewport-events
*/
virtual void viewportEvent(ViewportEvent& event);
/** @copydoc Sdl2Application::drawEvent() */
@ -653,10 +677,20 @@ class EmscriptenApplication {
/** @{ @name Keyboard handling */
/** @copydoc Sdl2Application::keyPressEvent() */
/**
* @brief Key press event
*
* Called when a key is pressed. Default implementation does nothing.
* @see @ref platform-windowed-key-events
*/
virtual void keyPressEvent(KeyEvent& event);
/** @copydoc Sdl2Application::keyReleaseEvent() */
/**
* @brief Key release event
*
* Called when a key is released. Default implementation does nothing.
* @see @ref platform-windowed-key-events
*/
virtual void keyReleaseEvent(KeyEvent& event);
/* Since 1.8.17, the original short-hand group closing doesn't work
@ -887,6 +921,8 @@ class EmscriptenApplication {
* translation to compatibility mouse events in this case, which is
* otherwise disabled. On builds with deprecated functionality
* disabled, default implementation does nothing.
* @see @ref platform-windowed-pointer-events,
* @ref Platform-EmscriptenApplication-touch
*/
virtual void pointerPressEvent(PointerEvent& event);
@ -917,6 +953,8 @@ class EmscriptenApplication {
* translation to compatibility mouse events in this case, which is
* otherwise disabled. On builds with deprecated functionality
* disabled, default implementation does nothing.
* @see @ref platform-windowed-pointer-events,
* @ref Platform-EmscriptenApplication-touch
*/
virtual void pointerReleaseEvent(PointerEvent& event);
@ -949,6 +987,8 @@ class EmscriptenApplication {
* compatibility mouse events before, so they're not propagated now
* either. On builds with deprecated functionality disabled, default
* implementation does nothing.
* @see @ref platform-windowed-pointer-events,
* @ref Platform-EmscriptenApplication-touch
*/
virtual void pointerMoveEvent(PointerMoveEvent& event);
@ -975,6 +1015,7 @@ class EmscriptenApplication {
* implementation delegates to @ref mouseScrollEvent(). On builds with
* deprecated functionality disabled, default implementation does
* nothing.
* @see @ref platform-windowed-pointer-events
*/
virtual void scrollEvent(ScrollEvent& event);
@ -1004,7 +1045,8 @@ class EmscriptenApplication {
* @note Note that in @ref CORRADE_TARGET_EMSCRIPTEN "Emscripten" the
* value is emulated and might not reflect external events like
* closing on-screen keyboard.
* @see @ref startTextInput(), @ref stopTextInput()
* @see @ref startTextInput(), @ref stopTextInput(),
* @ref platform-windowed-key-events
*/
bool isTextInputActive() const;
@ -1013,7 +1055,7 @@ class EmscriptenApplication {
*
* Starts text input that will go to @ref textInputEvent().
* @see @ref stopTextInput(), @ref isTextInputActive(),
* @ref setTextInputRect()
* @ref setTextInputRect(), @ref platform-windowed-key-events
*/
void startTextInput();
@ -1022,7 +1064,7 @@ class EmscriptenApplication {
*
* Stops text input that went to @ref textInputEvent().
* @see @ref startTextInput(), @ref isTextInputActive(),
* @ref textInputEvent()
* @ref textInputEvent(), @ref platform-windowed-key-events
*/
void stopTextInput();
@ -1031,8 +1073,9 @@ class EmscriptenApplication {
*
* The @p rect defines an area where the text is being displayed, for
* example to hint the system where to place on-screen keyboard.
* @note Currently not implemented, included only for compatibility with
* other Application implementations.
* @note Currently not implemented, included only for compatibility
* with other Application implementations.
* @see @ref platform-windowed-key-events
*/
void setTextInputRect(const Range2Di& rect);
@ -1041,7 +1084,7 @@ class EmscriptenApplication {
* @brief Text input event
*
* Called when text input is active and the text is being input.
* @see @ref isTextInputActive()
* @see @ref isTextInputActive(), @ref platform-windowed-key-events
*/
virtual void textInputEvent(TextInputEvent& event);
@ -1117,7 +1160,7 @@ class EmscriptenApplication {
@see @ref Modifiers, @ref KeyEvent::modifiers(),
@ref PointerEvent::modifiers(), @ref PointerMoveEvent::modifiers(),
@ref ScrollEvent::modifiers()
@ref ScrollEvent::modifiers(), @ref platform-windowed-key-events
*/
enum class EmscriptenApplication::Modifier: Int {
/**
@ -1155,7 +1198,7 @@ CORRADE_ENUMSET_OPERATORS(EmscriptenApplication::Modifiers)
@brief Key
@m_since_latest
@see @ref KeyEvent::key()
@see @ref KeyEvent::key(), @ref platform-windowed-key-events
*/
enum class EmscriptenApplication::Key: Int {
Unknown, /**< Unknown key */
@ -1351,7 +1394,9 @@ enum class EmscriptenApplication::Key: Int {
@brief Pointer event source
@m_since_latest
@see @ref PointerEvent::source(), @ref PointerMoveEvent::source()
@see @ref PointerEvent::source(), @ref PointerMoveEvent::source(),
@ref platform-windowed-pointer-events,
@ref Platform-EmscriptenApplication-touch
*/
enum class EmscriptenApplication::PointerEventSource: UnsignedByte {
/**
@ -1377,7 +1422,9 @@ enum class EmscriptenApplication::PointerEventSource: UnsignedByte {
@m_since_latest
@see @ref Pointers, @ref PointerEvent::pointer(),
@ref PointerMoveEvent::pointer(), @ref PointerMoveEvent::pointers()
@ref PointerMoveEvent::pointer(), @ref PointerMoveEvent::pointers(),
@ref platform-windowed-pointer-events,
@ref Platform-EmscriptenApplication-touch
*/
enum class EmscriptenApplication::Pointer: UnsignedByte {
/**
@ -1848,7 +1895,7 @@ CORRADE_ENUMSET_OPERATORS(EmscriptenApplication::Configuration::WindowFlags)
/**
@brief Viewport event
@see @ref viewportEvent()
@see @ref viewportEvent(), @ref platform-windowed-viewport-events
*/
class EmscriptenApplication::ViewportEvent {
public:
@ -2014,7 +2061,8 @@ class EmscriptenApplication::InputEvent {
@m_since_latest
@see @ref PointerMoveEvent, @ref ScrollEvent, @ref pointerPressEvent(),
@ref pointerReleaseEvent()
@ref pointerReleaseEvent(), @ref platform-windowed-pointer-events,
@ref Platform-EmscriptenApplication-touch
*/
class EmscriptenApplication::PointerEvent: public InputEvent {
public:
@ -2070,7 +2118,7 @@ class EmscriptenApplication::PointerEvent: public InputEvent {
*/
Vector2 position() const { return _position; }
/** @brief Modifiers */
/** @brief Keyboard modifiers */
EmscriptenApplication::Modifiers modifiers() const { return _modifiers; }
/**
@ -2151,7 +2199,7 @@ class CORRADE_DEPRECATED("use PointerEvent, pointerPressEvent() and pointerRelea
/** @brief Position */
Vector2i position() const;
/** @brief Modifiers */
/** @brief Keyboard modifiers */
Modifiers modifiers() const;
/** @brief Underlying Emscripten event */
@ -2170,7 +2218,9 @@ class CORRADE_DEPRECATED("use PointerEvent, pointerPressEvent() and pointerRelea
@brief Pointer move event
@m_since_latest
@see @ref PointerEvent, @ref ScrollEvent, @ref pointerMoveEvent()
@see @ref PointerEvent, @ref ScrollEvent, @ref pointerMoveEvent(),
@ref platform-windowed-pointer-events,
@ref Platform-EmscriptenApplication-touch
*/
class EmscriptenApplication::PointerMoveEvent: public InputEvent {
public:
@ -2252,7 +2302,7 @@ class EmscriptenApplication::PointerMoveEvent: public InputEvent {
*/
Vector2 relativePosition() const { return _relativePosition; }
/** @brief Modifiers */
/** @brief Keyboard modifiers */
EmscriptenApplication::Modifiers modifiers() const { return _modifiers; }
/**
@ -2354,7 +2404,7 @@ class CORRADE_DEPRECATED("use PointerMoveEvent and pointerMoveEvent() instead")
/** @brief Mouse buttons */
Buttons buttons() const;
/** @brief Modifiers */
/** @brief Keyboard modifiers */
EmscriptenApplication::Modifiers modifiers() const;
/** @brief Underlying Emscripten event */
@ -2378,7 +2428,8 @@ CORRADE_IGNORE_DEPRECATED_POP
@brief Scroll event
@m_since_latest
@see @ref PointerEvent, @ref PointerMoveEvent, @ref scrollEvent()
@see @ref PointerEvent, @ref PointerMoveEvent, @ref scrollEvent(),
@ref platform-windowed-pointer-events
*/
class EmscriptenApplication::ScrollEvent: public EmscriptenApplication::InputEvent {
public:
@ -2392,7 +2443,7 @@ class EmscriptenApplication::ScrollEvent: public EmscriptenApplication::InputEve
*/
Vector2 position() const;
/** @brief Modifiers */
/** @brief Keyboard modifiers */
EmscriptenApplication::Modifiers modifiers() const;
/** @brief Underlying Emscripten event */
@ -2422,7 +2473,7 @@ class CORRADE_DEPRECATED("use ScrollEvent and scrollEvent() instead") Emscripten
/** @brief Position */
Vector2i position() const;
/** @brief Modifiers */
/** @brief Keyboard modifiers */
EmscriptenApplication::Modifiers modifiers() const;
/** @brief Underlying Emscripten event */
@ -2440,7 +2491,8 @@ class CORRADE_DEPRECATED("use ScrollEvent and scrollEvent() instead") Emscripten
/**
@brief Key event
@see @ref keyPressEvent(), @ref keyReleaseEvent()
@see @ref keyPressEvent(), @ref keyReleaseEvent(),
@ref platform-windowed-key-events
*/
class EmscriptenApplication::KeyEvent: public EmscriptenApplication::InputEvent {
public:
@ -2493,7 +2545,7 @@ class EmscriptenApplication::KeyEvent: public EmscriptenApplication::InputEvent
*/
Containers::StringView scanCodeName() const;
/** @brief Modifiers */
/** @brief Keyboard modifiers */
EmscriptenApplication::Modifiers modifiers() const;
/** @brief Underlying Emscripten event */
@ -2510,7 +2562,7 @@ class EmscriptenApplication::KeyEvent: public EmscriptenApplication::InputEvent
/**
@brief Text input event
@see @ref textInputEvent()
@see @ref textInputEvent(), @ref platform-windowed-key-events
*/
class EmscriptenApplication::TextInputEvent {
public:

74
src/Magnum/Platform/GlfwApplication.h
Unescape View File

@ -202,7 +202,8 @@ class GlfwApplication {
*
* @see @ref KeyEvent::modifiers(), @ref PointerEvent::modifiers(),
* @ref PointerMoveEvent::modifiers(),
* @ref ScrollEvent::modifiers()
* @ref ScrollEvent::modifiers(),
* @ref platform-windowed-key-events
*/
typedef Containers::EnumSet<Modifier> Modifiers;
@ -210,7 +211,8 @@ class GlfwApplication {
* @brief Set of pointer types
* @m_since_latest
*
* @see @ref PointerMoveEvent::pointers()
* @see @ref PointerMoveEvent::pointers(),
* @ref platform-windowed-pointer-events
*/
typedef Containers::EnumSet<Pointer> Pointers;
@ -632,6 +634,7 @@ class GlfwApplication {
* via @ref framebufferSize() and DPI scaling using @ref dpiScaling().
* See @ref Platform-GlfwApplication-dpi for detailed info about these
* values.
* @see @ref platform-windowed-viewport-events
*/
virtual void viewportEvent(ViewportEvent& event);
@ -646,10 +649,20 @@ class GlfwApplication {
/** @{ @name Keyboard handling */
/** @copydoc Sdl2Application::keyPressEvent() */
/**
* @brief Key press event
*
* Called when a key is pressed. Default implementation does nothing.
* @see @ref platform-windowed-key-events
*/
virtual void keyPressEvent(KeyEvent& event);
/** @copydoc Sdl2Application::keyReleaseEvent() */
/**
* @brief Key release event
*
* Called when a key is released. Default implementation does nothing.
* @see @ref platform-windowed-key-events
*/
virtual void keyReleaseEvent(KeyEvent& event);
/* Since 1.8.17, the original short-hand group closing doesn't work
@ -749,6 +762,7 @@ class GlfwApplication {
* implementation delegates to @ref mousePressEvent(). On builds with
* deprecated functionality disabled, default implementation does
* nothing.
* @see @ref platform-windowed-pointer-events
*/
virtual void pointerPressEvent(PointerEvent& event);
@ -776,6 +790,7 @@ class GlfwApplication {
* implementation delegates to @ref mouseReleaseEvent(). On builds with
* deprecated functionality disabled, default implementation does
* nothing.
* @see @ref platform-windowed-pointer-events
*/
virtual void pointerReleaseEvent(PointerEvent& event);
@ -806,6 +821,7 @@ class GlfwApplication {
* @ref mousePressEvent() or @ref mouseReleaseEvent(). On builds with
* deprecated functionality disabled, default implementation does
* nothing.
* @see @ref platform-windowed-pointer-events
*/
virtual void pointerMoveEvent(PointerMoveEvent& event);
@ -832,6 +848,7 @@ class GlfwApplication {
* implementation delegates to @ref mouseScrollEvent(). On builds with
* deprecated functionality disabled, default implementation does
* nothing.
* @see @ref platform-windowed-pointer-events
*/
virtual void scrollEvent(ScrollEvent& event);
@ -859,7 +876,8 @@ class GlfwApplication {
*
* If text input is active, text input events go to
* @ref textInputEvent().
* @see @ref startTextInput(), @ref stopTextInput()
* @see @ref startTextInput(), @ref stopTextInput(),
* @ref platform-windowed-key-events
*/
bool isTextInputActive() const;
@ -867,7 +885,8 @@ class GlfwApplication {
* @brief Start text input
*
* Starts text input that will go to @ref textInputEvent().
* @see @ref stopTextInput(), @ref isTextInputActive()
* @see @ref stopTextInput(), @ref isTextInputActive(),
* @ref platform-windowed-key-events
*/
void startTextInput();
@ -876,7 +895,7 @@ class GlfwApplication {
*
* Stops text input that went to @ref textInputEvent().
* @see @ref startTextInput(), @ref isTextInputActive(),
* @ref textInputEvent()
* @ref textInputEvent(), @ref platform-windowed-key-events
*/
void stopTextInput();
@ -885,7 +904,7 @@ class GlfwApplication {
* @brief Text input event
*
* Called when text input is active and the text is being input.
* @see @ref isTextInputActive()
* @see @ref isTextInputActive(), @ref platform-windowed-key-events
*/
virtual void textInputEvent(TextInputEvent& event);
@ -1004,7 +1023,7 @@ class GlfwApplication {
@see @ref Modifiers, @ref KeyEvent::modifiers(),
@ref PointerEvent::modifiers(), @ref PointerMoveEvent::modifiers(),
@ref ScrollEvent::modifiers()
@ref ScrollEvent::modifiers(), @ref platform-windowed-key-events
*/
enum class GlfwApplication::Modifier: Int {
/**
@ -1042,7 +1061,7 @@ CORRADE_ENUMSET_OPERATORS(GlfwApplication::Modifiers)
@brief Key
@m_since_latest
@see @ref KeyEvent::key()
@see @ref KeyEvent::key(), @ref platform-windowed-key-events
*/
enum class GlfwApplication::Key: Int {
Unknown = GLFW_KEY_UNKNOWN, /**< Unknown key */
@ -1282,7 +1301,8 @@ enum class GlfwApplication::Key: Int {
@brief Pointer event source
@m_since_latest
@see @ref PointerEvent::source(), @ref PointerMoveEvent::source()
@see @ref PointerEvent::source(), @ref PointerMoveEvent::source(),
@ref platform-windowed-pointer-events
*/
enum class GlfwApplication::PointerEventSource: UnsignedByte {
/**
@ -1300,7 +1320,8 @@ enum class GlfwApplication::PointerEventSource: UnsignedByte {
@m_since_latest
@see @ref Pointers, @ref PointerEvent::pointer(),
@ref PointerMoveEvent::pointer(), @ref PointerMoveEvent::pointers()
@ref PointerMoveEvent::pointer(), @ref PointerMoveEvent::pointers(),
@ref platform-windowed-pointer-events
*/
enum class GlfwApplication::Pointer: UnsignedByte {
/**
@ -2005,7 +2026,7 @@ class GlfwApplication::ExitEvent {
/**
@brief Viewport event
@see @ref viewportEvent()
@see @ref viewportEvent(), @ref platform-windowed-viewport-events
*/
class GlfwApplication::ViewportEvent {
public:
@ -2134,7 +2155,8 @@ class GlfwApplication::InputEvent {
/**
@brief Key event
@see @ref keyPressEvent(), @ref keyReleaseEvent()
@see @ref keyPressEvent(), @ref keyReleaseEvent(),
@ref platform-windowed-key-events
*/
class GlfwApplication::KeyEvent: public GlfwApplication::InputEvent {
public:
@ -2185,7 +2207,7 @@ class GlfwApplication::KeyEvent: public GlfwApplication::InputEvent {
*/
Containers::StringView keyName() const;
/** @brief Modifiers */
/** @brief Keyboard modifiers */
GlfwApplication::Modifiers modifiers() const { return _modifiers; }
/** @copydoc Sdl2Application::KeyEvent::isRepeated() */
@ -2207,7 +2229,7 @@ class GlfwApplication::KeyEvent: public GlfwApplication::InputEvent {
@m_since_latest
@see @ref PointerMoveEvent, @ref ScrollEvent, @ref pointerPressEvent(),
@ref pointerReleaseEvent()
@ref pointerReleaseEvent(), @ref platform-windowed-pointer-events
*/
class GlfwApplication::PointerEvent: public InputEvent {
public:
@ -2262,7 +2284,7 @@ class GlfwApplication::PointerEvent: public InputEvent {
*/
Vector2 position() const { return _position; }
/** @brief Modifiers */
/** @brief Keyboard modifiers */
GlfwApplication::Modifiers modifiers() const { return _modifiers; }
private:
@ -2312,7 +2334,7 @@ class CORRADE_DEPRECATED("use PointerEvent, pointerPressEvent() and pointerRelea
/** @brief Position */
Vector2i position() const { return _position; }
/** @brief Modifiers */
/** @brief Keyboard modifiers */
GlfwApplication::Modifiers modifiers() const { return _modifiers; }
private:
@ -2330,7 +2352,8 @@ class CORRADE_DEPRECATED("use PointerEvent, pointerPressEvent() and pointerRelea
@brief Pointer move event
@m_since_latest
@see @ref PointerEvent, @ref ScrollEvent, @ref pointerMoveEvent()
@see @ref PointerEvent, @ref ScrollEvent, @ref pointerMoveEvent(),
@ref platform-windowed-pointer-events
*/
class GlfwApplication::PointerMoveEvent: public InputEvent {
public:
@ -2416,7 +2439,7 @@ class GlfwApplication::PointerMoveEvent: public InputEvent {
Vector2 relativePosition() const { return _relativePosition; }
/**
* @brief Modifiers
* @brief Keyboard modifiers
*
* Lazily populated on first request.
*/
@ -2485,7 +2508,7 @@ class CORRADE_DEPRECATED("use PointerMoveEvent and pointerMoveEvent() instead")
Vector2i relativePosition() const { return _relativePosition; }
/**
* @brief Modifiers
* @brief Keyboard modifiers
*
* Lazily populated on first request.
*/
@ -2511,7 +2534,8 @@ CORRADE_IGNORE_DEPRECATED_POP
@brief Scroll event
@m_since_latest
@see @ref PointerEvent, @ref PointerMoveEvent, @ref scrollEvent()
@see @ref PointerEvent, @ref PointerMoveEvent, @ref scrollEvent(),
@ref platform-windowed-pointer-events
*/
class GlfwApplication::ScrollEvent: public InputEvent {
public:
@ -2529,7 +2553,7 @@ class GlfwApplication::ScrollEvent: public InputEvent {
Vector2 position();
/**
* @brief Modifiers
* @brief Keyboard modifiers
*
* Lazily populated on first request.
*/
@ -2567,7 +2591,7 @@ class CORRADE_DEPRECATED("use ScrollEvent and scrollEvent() instead") GlfwApplic
Vector2i position();
/**
* @brief Modifiers
* @brief Keyboard modifiers
*
* Lazily populated on first request.
*/
@ -2588,7 +2612,7 @@ class CORRADE_DEPRECATED("use ScrollEvent and scrollEvent() instead") GlfwApplic
/**
@brief Text input event
@see @ref textInputEvent()
@see @ref textInputEvent(), @ref platform-windowed-key-events
*/
class GlfwApplication::TextInputEvent {
public:

86
src/Magnum/Platform/Sdl2Application.h
Unescape View File

@ -298,7 +298,7 @@ If no other application header is included, this class is also aliased to
@cpp Platform::Application @ce and the macro is aliased to @cpp MAGNUM_APPLICATION_MAIN() @ce
to simplify porting.
@section Platform-Sdl2Application-touch Touch input
@section Platform-Sdl2Application-touch Touch input in SDL2
The application recognizes touch input and reports it as @ref Pointer::Finger
and @ref PointerEventSource::Touch. Because both mouse and touch events are
@ -330,6 +330,9 @@ each new touch may generate a new ID that's only used until given finger is
lifted, and then never again. For @ref PointerEventSource::Mouse the ID is a
constant, as there's always just a single mouse cursor.
See also @ref platform-windowed-pointer-events for general information about
handling pointer input in a portable way.
@section Platform-Sdl2Application-platform-specific Platform-specific behavior
@subsection Platform-Sdl2Application-platform-specific-power Power management
@ -574,7 +577,8 @@ class Sdl2Application {
*
* @see @ref KeyEvent::modifiers(), @ref PointerEvent::modifiers(),
* @ref PointerMoveEvent::modifiers(),
* @ref ScrollEvent::modifiers()
* @ref ScrollEvent::modifiers(),
* @ref platform-windowed-key-events
*/
typedef Containers::EnumSet<Modifier> Modifiers;
@ -582,7 +586,8 @@ class Sdl2Application {
* @brief Set of pointer types
* @m_since_latest
*
* @see @ref PointerMoveEvent::pointers()
* @see @ref PointerMoveEvent::pointers(),
* @ref platform-windowed-pointer-events
*/
typedef Containers::EnumSet<Pointer> Pointers;
@ -1102,6 +1107,7 @@ class Sdl2Application {
* via @ref framebufferSize() and DPI scaling using @ref dpiScaling().
* See @ref Platform-Sdl2Application-dpi for detailed info about these
* values.
* @see @ref platform-windowed-viewport-events
*/
virtual void viewportEvent(ViewportEvent& event);
@ -1127,14 +1133,16 @@ class Sdl2Application {
/**
* @brief Key press event
*
* Called when an key is pressed. Default implementation does nothing.
* Called when a key is pressed. Default implementation does nothing.
* @see @ref platform-windowed-key-events
*/
virtual void keyPressEvent(KeyEvent& event);
/**
* @brief Key release event
*
* Called when an key is released. Default implementation does nothing.
* Called when a key is released. Default implementation does nothing.
* @see @ref platform-windowed-key-events
*/
virtual void keyReleaseEvent(KeyEvent& event);
@ -1238,6 +1246,8 @@ class Sdl2Application {
* @ref mousePressEvent(), interpreting @ref Pointer::Finger as
* @ref MouseEvent::Button::Left. On builds with deprecated
* functionality disabled, default implementation does nothing.
* @see @ref platform-windowed-pointer-events,
* @ref Platform-Sdl2Application-touch
*/
virtual void pointerPressEvent(PointerEvent& event);
@ -1267,6 +1277,8 @@ class Sdl2Application {
* @ref mouseReleaseEvent(), interpreting @ref Pointer::Finger as
* @ref MouseEvent::Button::Left. On builds with deprecated
* functionality disabled, default implementation does nothing.
* @see @ref platform-windowed-pointer-events,
* @ref Platform-Sdl2Application-touch
*/
virtual void pointerReleaseEvent(PointerEvent& event);
@ -1298,6 +1310,8 @@ class Sdl2Application {
* @ref Pointer::Finger is interpreted as @ref MouseEvent::Button::Left.
* On builds with deprecated functionality disabled, default
* implementation does nothing.
* @see @ref platform-windowed-pointer-events,
* @ref Platform-Sdl2Application-touch
*/
virtual void pointerMoveEvent(PointerMoveEvent& event);
@ -1324,6 +1338,7 @@ class Sdl2Application {
* implementation delegates to @ref mouseScrollEvent(). On builds with
* deprecated functionality disabled, default implementation does
* nothing.
* @see @ref platform-windowed-pointer-events
*/
virtual void scrollEvent(ScrollEvent& event);
@ -1358,12 +1373,13 @@ class Sdl2Application {
/**
* @brief Whether text input is active
*
* If text input is active, text input events go to @ref textInputEvent()
* and @ref textEditingEvent().
* If text input is active, text input events go to
* @ref textInputEvent() and @ref textEditingEvent().
* @note Note that in @ref CORRADE_TARGET_EMSCRIPTEN "Emscripten" the
* value is emulated and might not reflect external events like
* closing on-screen keyboard.
* @see @ref startTextInput(), @ref stopTextInput()
* @see @ref startTextInput(), @ref stopTextInput(),
* @ref platform-windowed-key-events
*/
bool isTextInputActive();
@ -1373,7 +1389,7 @@ class Sdl2Application {
* Starts text input that will go to @ref textInputEvent() and
* @ref textEditingEvent().
* @see @ref stopTextInput(), @ref isTextInputActive(),
* @ref setTextInputRect()
* @ref setTextInputRect(), @ref platform-windowed-key-events
*/
void startTextInput();
@ -1382,8 +1398,9 @@ class Sdl2Application {
*
* Stops text input that went to @ref textInputEvent() and
* @ref textEditingEvent().
* @see @ref startTextInput(), @ref isTextInputActive(), @ref textInputEvent()
* @ref textEditingEvent()
* @see @ref startTextInput(), @ref isTextInputActive(),
* @ref textInputEvent(), @ref textEditingEvent(),
* @ref platform-windowed-key-events
*/
void stopTextInput();
@ -1392,6 +1409,7 @@ class Sdl2Application {
*
* The @p rect defines an area where the text is being displayed, for
* example to hint the system where to place on-screen keyboard.
* @see @ref platform-windowed-key-events
*/
void setTextInputRect(const Range2Di& rect);
@ -1400,7 +1418,7 @@ class Sdl2Application {
* @brief Text input event
*
* Called when text input is active and the text is being input.
* @see @ref isTextInputActive()
* @see @ref isTextInputActive(), @ref platform-windowed-key-events
*/
virtual void textInputEvent(TextInputEvent& event);
@ -1408,6 +1426,7 @@ class Sdl2Application {
* @brief Text editing event
*
* Called when text input is active and the text is being edited.
* @see @ref platform-windowed-key-events
*/
virtual void textEditingEvent(TextEditingEvent& event);
@ -1543,7 +1562,7 @@ class Sdl2Application {
@see @ref Modifiers, @ref KeyEvent::modifiers(),
@ref PointerEvent::modifiers(), @ref PointerMoveEvent::modifiers(),
@ref ScrollEvent::modifiers()
@ref ScrollEvent::modifiers(), @ref platform-windowed-key-events
*/
enum class Sdl2Application::Modifier: Uint16 {
/**
@ -1603,7 +1622,7 @@ CORRADE_ENUMSET_OPERATORS(Sdl2Application::Modifiers)
@brief Key
@m_since_latest
@see @ref KeyEvent::key()
@see @ref KeyEvent::key(), @ref platform-windowed-key-events
*/
enum class Sdl2Application::Key: SDL_Keycode {
Unknown = SDLK_UNKNOWN, /**< Unknown key */
@ -1857,7 +1876,8 @@ enum class Sdl2Application::Key: SDL_Keycode {
@brief Pointer event source
@m_since_latest
@see @ref PointerEvent::source(), @ref PointerMoveEvent::source()
@see @ref PointerEvent::source(), @ref PointerMoveEvent::source(),
@ref platform-windowed-pointer-events, @ref Platform-Sdl2Application-touch
*/
enum class Sdl2Application::PointerEventSource: UnsignedByte {
/**
@ -1888,7 +1908,8 @@ enum class Sdl2Application::PointerEventSource: UnsignedByte {
@m_since_latest
@see @ref Pointers, @ref PointerEvent::pointer(),
@ref PointerMoveEvent::pointer(), @ref PointerMoveEvent::pointers()
@ref PointerMoveEvent::pointer(), @ref PointerMoveEvent::pointers(),
@ref platform-windowed-pointer-events, @ref Platform-Sdl2Application-touch
*/
enum class Sdl2Application::Pointer: UnsignedByte {
/**
@ -2680,7 +2701,7 @@ class Sdl2Application::ExitEvent {
/**
@brief Viewport event
@see @ref viewportEvent()
@see @ref viewportEvent(), @ref platform-windowed-viewport-events
*/
class Sdl2Application::ViewportEvent {
public:
@ -2853,7 +2874,8 @@ class Sdl2Application::InputEvent {
/**
@brief Key event
@see @ref keyPressEvent(), @ref keyReleaseEvent()
@see @ref keyPressEvent(), @ref keyReleaseEvent(),
@ref platform-windowed-key-events
*/
class Sdl2Application::KeyEvent: public Sdl2Application::InputEvent {
public:
@ -2925,7 +2947,7 @@ class Sdl2Application::KeyEvent: public Sdl2Application::InputEvent {
Containers::StringView scanCodeName() const;
#endif
/** @brief Modifiers */
/** @brief Keyboard modifiers */
Sdl2Application::Modifiers modifiers() const { return _modifiers; }
/**
@ -2952,7 +2974,8 @@ class Sdl2Application::KeyEvent: public Sdl2Application::InputEvent {
@m_since_latest
@see @ref PointerMoveEvent, @ref pointerPressEvent(),
@ref pointerReleaseEvent()
@ref pointerReleaseEvent(), @ref platform-windowed-pointer-events,
@ref Platform-Sdl2Application-touch
*/
class Sdl2Application::PointerEvent: public InputEvent {
public:
@ -3015,7 +3038,7 @@ class Sdl2Application::PointerEvent: public InputEvent {
#endif
/**
* @brief Modifiers
* @brief Keyboard modifiers
*
* Lazily populated on first request.
*/
@ -3090,7 +3113,7 @@ class CORRADE_DEPRECATED("use PointerEvent, pointerPressEvent() and pointerRelea
#endif
/**
* @brief Modifiers
* @brief Keyboard modifiers
*
* Lazily populated on first request.
*/
@ -3122,7 +3145,8 @@ class CORRADE_DEPRECATED("use PointerEvent, pointerPressEvent() and pointerRelea
@brief Pointer move event
@m_since_latest
@see @ref PointerEvent, @ref pointerMoveEvent()
@see @ref PointerEvent, @ref pointerMoveEvent(),
@ref platform-windowed-pointer-events, @ref Platform-Sdl2Application-touch
*/
class Sdl2Application::PointerMoveEvent: public InputEvent {
public:
@ -3211,7 +3235,7 @@ class Sdl2Application::PointerMoveEvent: public InputEvent {
Vector2 relativePosition() const { return _relativePosition; }
/**
* @brief Modifiers
* @brief Keyboard modifiers
*
* Lazily populated on first request.
*/
@ -3280,7 +3304,7 @@ class CORRADE_DEPRECATED("use PointerMoveEvent and pointerMoveEvent() instead")
Buttons buttons() const { return _buttons; }
/**
* @brief Modifiers
* @brief Keyboard modifiers
*
* Lazily populated on first request.
*/
@ -3305,7 +3329,8 @@ CORRADE_IGNORE_DEPRECATED_POP
@brief Scroll event
@m_since_latest
@see @ref PointerEvent, @ref PointerMoveEvent, @ref scrollEvent()
@see @ref PointerEvent, @ref PointerMoveEvent, @ref scrollEvent(),
@ref platform-windowed-pointer-events
*/
class Sdl2Application::ScrollEvent: public Sdl2Application::InputEvent {
public:
@ -3321,7 +3346,7 @@ class Sdl2Application::ScrollEvent: public Sdl2Application::InputEvent {
Vector2 position();
/**
* @brief Modifiers
* @brief Keyboard modifiers
*
* Lazily populated on first request.
*/
@ -3358,7 +3383,7 @@ class CORRADE_DEPRECATED("use ScrollEvent and scrollEvent() instead") Sdl2Applic
Vector2i position();
/**
* @brief Modifiers
* @brief Keyboard modifiers
*
* Lazily populated on first request.
*/
@ -3456,7 +3481,8 @@ class Sdl2Application::MultiGestureEvent {
/**
@brief Text input event
@see @ref TextEditingEvent, @ref textInputEvent()
@see @ref TextEditingEvent, @ref textInputEvent(),
@ref platform-windowed-key-events
*/
class Sdl2Application::TextInputEvent {
public:
@ -3514,7 +3540,7 @@ class Sdl2Application::TextInputEvent {
/**
@brief Text editing event
@see @ref textEditingEvent()
@see @ref textEditingEvent(), @ref platform-windowed-key-events
*/
class Sdl2Application::TextEditingEvent {
public:

Write Preview
Loading…
Cancel
Save