Add documentation of the change as described in the GLFW contributers guide

This commit is contained in:
Alex Sanchez-Stern 2024-10-13 15:28:36 -07:00
parent c31de75111
commit 06f21df20e
4 changed files with 78 additions and 2 deletions

View File

@ -294,6 +294,7 @@ video tutorials.
- Jonas Ådahl
- Lasse Öörni
- Leonard König
- Alex Sanchez-Stern
- All the unmentioned and anonymous contributors in the GLFW community, for bug
reports, patches, feedback, testing and encouragement

View File

@ -132,7 +132,11 @@ information on what to include when reporting a bug.
- [Null] Added EGL context creation on Mesa via `EGL_MESA_platform_surfaceless`
- [EGL] Allowed native access on Wayland with `GLFW_CONTEXT_CREATION_API` set to
`GLFW_NATIVE_CONTEXT_API` (#2518)
- [X11] Added `getSelectionRequestHandler`, `setSelectionRequestHander`,
`getGLFWDisplay`, and `getGLFWHelperWindow` functions. to allow
clients to implement more X clipboard functionality than is
built-in; with these primitives clients can add copy paste support
for files, images, colors, and other non-text data types.
## Contact
@ -148,4 +152,3 @@ request, please file it in the
Finally, if you're interested in helping out with the development of GLFW or
porting it to your favorite platform, join us on the forum or GitHub.

View File

@ -973,6 +973,53 @@ The contents of the system clipboard can be set to a UTF-8 encoded string with
glfwSetClipboardString(NULL, "A string with words in it");
```
\par Advanced Usage
While GLFW does not directly support using other data types with the
system clipboard, on many platforms this is possible using platform
specific code. If you are primarily targetting a small set of
platforms, this may be viable for your application.
\par
On Windows, you can do clipboard operations directly using <a
href="https://learn.microsoft.com/en-us/windows/win32/api/winuser/">winuser.h</a>,
allowing you to copy and paste datatypes other than text. On X11 you
can also use the platform specific API to get this functionality, but
you must hook into GLFW's X11 event handling code to allow copying
<i>out</i> of your application. Example code for most of this functionality
can be found in general X11 documentation like <a
href="http://www.uninformativ.de/blog/postings/2017-04-02/0/POSTING-en.html">this
page</a>; the GLFW-specific part is including
\par
@code
#include <GLFW/glfw3.h>
#include <X11/Xlib.h>
#define GLFW_EXPOSE_NATIVE_X11
#include <GLFW/glfw3native.h>
@endcode
\par
At the top of your file (guarded by platform), and then running
\par
@code
setSelectionRequestHandler(myHandler);
@endcode
\par
on initialization. Your selection handler must have the signature:
\par
@code
void myHandler(XEvent*);
@endcode
\par
and it will receive all X Selection events. To ensure compatibility
use `getGLFWDisplay()` to get a display object instead of
`XOpenDisplay()` and use the result of `getGLFWHelperWindow()` as the
target window for the selection.
## Path drop input {#path_drop}

View File

@ -14,6 +14,25 @@ values over 8. For compatibility with older versions, the
@ref GLFW_UNLIMITED_MOUSE_BUTTONS input mode needs to be set to make use of
this.
### Support for custom X11 clipboard functionality {#x11_custom_selection}
This change allows clients to implement custom X11 clipboard
functionality like the copying and pasting of files across
applications.
GLFW itself only allows plain text to be copied to the
clipboard and back on all platforms. On some platforms, like Windows,
you can use platform specific APIs to add extra clipboard
functionality like copying of other data types. However, on X11, this
was previously not fully possible due to the fact that GLFW internal
code has full control over the X11 event queue.
This change exposes several new symbols that allow you to get and set
the handler for X11 selection events that GLFW will use. It also
allows getting the internal display connection and selection helper
window, for use in that kind of code.
## Caveats {#caveats}
## Deprecations {#deprecations}
@ -24,6 +43,12 @@ this.
### New functions {#new_functions}
#### X11-specific
- @ref getSelectionRequestHandler
- @ref setSelectionRequestHanddler
- @ref getGLFWDisplay
- @ref getGLFWHelperWindow
### New types {#new_types}
### New constants {#new_constants}