mirror/glfw
1
0
Fork 0
mirror of https://github.com/glfw/glfw.git synced 2024-09-19 21:32:16 +00:00
Code Issues Packages Projects Releases Wiki Activity

Improve (?) reference documentation for callbacks

Browse Source 
(cherry picked from commit 51bb76c7c3)
This commit is contained in:
Camilla Löwy 2019-05-24 01:52:49 +02:00
parent 5416e347ad
commit b962ef1241
4 changed files with 328 additions and 103 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
docs/Doxyfile.in
View File

@ -200,6 +200,7 @@ ALIASES = "thread_safety=@par Thread safety^^" \
"analysis=@par Analysis^^" \
"reentrancy=@par Reentrancy^^" \
"errors=@par Errors^^" \
"callback_signature=@par Callback signature^^" \
"glfw3=__GLFW 3:__" \
"x11=__X11:__" \
"wayland=__Wayland:__" \

426
include/GLFW/glfw3.h
View File

@ -1164,13 +1164,21 @@ typedef struct GLFWwindow GLFWwindow;
*/
typedef struct GLFWcursor GLFWcursor;
/*! @brief The function signature for error callbacks.
/*! @brief The function pointer type for error callbacks.
*
* This is the function signature for error callback functions.
* This is the function pointer type for error callbacks. An error callback
* function has the following signature:
* @code
* void callback_name(int error_code, const char* description)
* @endcode
*
* @param[in] error An [error code](@ref errors).
* @param[in] error_code An [error code](@ref errors). Future releases may add
* more error codes.
* @param[in] description A UTF-8 encoded string describing the error.
*
* @pointer_lifetime The error description string is valid until the callback
* function returns.
*
* @sa @ref error_handling
* @sa @ref glfwSetErrorCallback
*
@ -1180,9 +1188,13 @@ typedef struct GLFWcursor GLFWcursor;
*/
typedef void (* GLFWerrorfun)(int,const char*);
/*! @brief The function signature for window position callbacks.
/*! @brief The function pointer type for window position callbacks.
*
* This is the function signature for window position callback functions.
* This is the function pointer type for window position callbacks. A window
* position callback function has the following signature:
* @code
* void callback_name(GLFWwindow* window, int xpos, int ypos)
* @endcode
*
* @param[in] window The window that was moved.
* @param[in] xpos The new x-coordinate, in screen coordinates, of the
@ -1199,9 +1211,13 @@ typedef void (* GLFWerrorfun)(int,const char*);
*/
typedef void (* GLFWwindowposfun)(GLFWwindow*,int,int);
/*! @brief The function signature for window resize callbacks.
/*! @brief The function pointer type for window size callbacks.
*
* This is the function signature for window size callback functions.
* This is the function pointer type for window size callbacks. A window size
* callback function has the following signature:
* @code
* void callback_name(GLFWwindow* window, int width, int height)
* @endcode
*
* @param[in] window The window that was resized.
* @param[in] width The new width, in screen coordinates, of the window.
@ -1217,9 +1233,13 @@ typedef void (* GLFWwindowposfun)(GLFWwindow*,int,int);
*/
typedef void (* GLFWwindowsizefun)(GLFWwindow*,int,int);
/*! @brief The function signature for window close callbacks.
/*! @brief The function pointer type for window close callbacks.
*
* This is the function signature for window close callback functions.
* This is the function pointer type for window close callbacks. A window
* close callback function has the following signature:
* @code
* void function_name(GLFWwindow* window)
* @endcode
*
* @param[in] window The window that the user attempted to close.
*
@ -1233,9 +1253,13 @@ typedef void (* GLFWwindowsizefun)(GLFWwindow*,int,int);
*/
typedef void (* GLFWwindowclosefun)(GLFWwindow*);
/*! @brief The function signature for window content refresh callbacks.
/*! @brief The function pointer type for window content refresh callbacks.
*
* This is the function signature for window refresh callback functions.
* This is the function pointer type for window content refresh callbacks.
* A window content refresh callback function has the following signature:
* @code
* void function_name(GLFWwindow* window);
* @endcode
*
* @param[in] window The window whose content needs to be refreshed.
*
@ -1249,9 +1273,13 @@ typedef void (* GLFWwindowclosefun)(GLFWwindow*);
*/
typedef void (* GLFWwindowrefreshfun)(GLFWwindow*);
/*! @brief The function signature for window focus/defocus callbacks.
/*! @brief The function pointer type for window focus callbacks.
*
* This is the function signature for window focus callback functions.
* This is the function pointer type for window focus callbacks. A window
* focus callback function has the following signature:
* @code
* void function_name(GLFWwindow* window, int focused)
* @endcode
*
* @param[in] window The window that gained or lost input focus.
* @param[in] focused `GLFW_TRUE` if the window was given input focus, or
@ -1266,10 +1294,13 @@ typedef void (* GLFWwindowrefreshfun)(GLFWwindow*);
*/
typedef void (* GLFWwindowfocusfun)(GLFWwindow*,int);
/*! @brief The function signature for window iconify/restore callbacks.
/*! @brief The function pointer type for window iconify callbacks.
*
* This is the function signature for window iconify/restore callback
* functions.
* This is the function pointer type for window iconify callbacks. A window
* iconify callback function has the following signature:
* @code
* void function_name(GLFWwindow* window, int iconified)
* @endcode
*
* @param[in] window The window that was iconified or restored.
* @param[in] iconified `GLFW_TRUE` if the window was iconified, or
@ -1284,10 +1315,13 @@ typedef void (* GLFWwindowfocusfun)(GLFWwindow*,int);
*/
typedef void (* GLFWwindowiconifyfun)(GLFWwindow*,int);
/*! @brief The function signature for window maximize/restore callbacks.
/*! @brief The function pointer type for window maximize callbacks.
*
* This is the function signature for window maximize/restore callback
* functions.
* This is the function pointer type for window maximize callbacks. A window
* maximize callback function has the following signature:
* @code
* void function_name(GLFWwindow* window, int maximized)
* @endcode
*
* @param[in] window The window that was maximized or restored.
* @param[in] iconified `GLFW_TRUE` if the window was maximized, or
@ -1302,10 +1336,13 @@ typedef void (* GLFWwindowiconifyfun)(GLFWwindow*,int);
*/
typedef void (* GLFWwindowmaximizefun)(GLFWwindow*,int);
/*! @brief The function signature for framebuffer resize callbacks.
/*! @brief The function pointer type for framebuffer size callbacks.
*
* This is the function signature for framebuffer resize callback
* functions.
* This is the function pointer type for framebuffer size callbacks.
* A framebuffer size callback function has the following signature:
* @code
* void function_name(GLFWwindow* window, int width, int height)
* @endcode
*
* @param[in] window The window whose framebuffer was resized.
* @param[in] width The new width, in pixels, of the framebuffer.
@ -1320,10 +1357,13 @@ typedef void (* GLFWwindowmaximizefun)(GLFWwindow*,int);
*/
typedef void (* GLFWframebuffersizefun)(GLFWwindow*,int,int);
/*! @brief The function signature for window content scale callbacks.
/*! @brief The function pointer type for window content scale callbacks.
*
* This is the function signature for window content scale callback
* functions.
* This is the function pointer type for window content scale callbacks.
* A window content scale callback function has the following signature:
* @code
* void function_name(GLFWwindow* window, float xscale, float yscale)
* @endcode
*
* @param[in] window The window whose content scale changed.
* @param[in] xscale The new x-axis content scale of the window.
@ -1338,14 +1378,19 @@ typedef void (* GLFWframebuffersizefun)(GLFWwindow*,int,int);
*/
typedef void (* GLFWwindowcontentscalefun)(GLFWwindow*,float,float);
/*! @brief The function signature for mouse button callbacks.
/*! @brief The function pointer type for mouse button callbacks.
*
* This is the function signature for mouse button callback functions.
* This is the function pointer type for mouse button callback functions.
* A mouse button callback function has the following signature:
* @code
* void function_name(GLFWwindow* window, int button, int action, int mods)
* @endcode
*
* @param[in] window The window that received the event.
* @param[in] button The [mouse button](@ref buttons) that was pressed or
* released.
* @param[in] action One of `GLFW_PRESS` or `GLFW_RELEASE`.
* @param[in] action One of `GLFW_PRESS` or `GLFW_RELEASE`. Future releases
* may add more actions.
* @param[in] mods Bit field describing which [modifier keys](@ref mods) were
* held down.
*
@ -1359,9 +1404,13 @@ typedef void (* GLFWwindowcontentscalefun)(GLFWwindow*,float,float);
*/
typedef void (* GLFWmousebuttonfun)(GLFWwindow*,int,int,int);
/*! @brief The function signature for cursor position callbacks.
/*! @brief The function pointer type for cursor position callbacks.
*
* This is the function signature for cursor position callback functions.
* This is the function pointer type for cursor position callbacks. A cursor
* position callback function has the following signature:
* @code
* void function_name(GLFWwindow* window, double xpos, double ypos);
* @endcode
*
* @param[in] window The window that received the event.
* @param[in] xpos The new cursor x-coordinate, relative to the left edge of
@ -1378,9 +1427,13 @@ typedef void (* GLFWmousebuttonfun)(GLFWwindow*,int,int,int);
*/
typedef void (* GLFWcursorposfun)(GLFWwindow*,double,double);
/*! @brief The function signature for cursor enter/leave callbacks.
/*! @brief The function pointer type for cursor enter/leave callbacks.
*
* This is the function signature for cursor enter/leave callback functions.
* This is the function pointer type for cursor enter/leave callbacks.
* A cursor enter/leave callback function has the following signature:
* @code
* void function_name(GLFWwindow* window, int entered)
* @endcode
*
* @param[in] window The window that received the event.
* @param[in] entered `GLFW_TRUE` if the cursor entered the window's content
@ -1395,9 +1448,13 @@ typedef void (* GLFWcursorposfun)(GLFWwindow*,double,double);
*/
typedef void (* GLFWcursorenterfun)(GLFWwindow*,int);
/*! @brief The function signature for scroll callbacks.
/*! @brief The function pointer type for scroll callbacks.
*
* This is the function signature for scroll callback functions.
* This is the function pointer type for scroll callbacks. A scroll callback
* function has the following signature:
* @code
* void function_name(GLFWwindow* window, double xoffset, double yoffset)
* @endcode
*
* @param[in] window The window that received the event.
* @param[in] xoffset The scroll offset along the x-axis.
@ -1412,14 +1469,19 @@ typedef void (* GLFWcursorenterfun)(GLFWwindow*,int);
*/
typedef void (* GLFWscrollfun)(GLFWwindow*,double,double);
/*! @brief The function signature for keyboard key callbacks.
/*! @brief The function pointer type for keyboard key callbacks.
*
* This is the function signature for keyboard key callback functions.
* This is the function pointer type for keyboard key callbacks. A keyboard
* key callback function has the following signature:
* @code
* void function_name(GLFWwindow* window, int key, int scancode, int action, int mods)
* @endcode
*
* @param[in] window The window that received the event.
* @param[in] key The [keyboard key](@ref keys) that was pressed or released.
* @param[in] scancode The system-specific scancode of the key.
* @param[in] action `GLFW_PRESS`, `GLFW_RELEASE` or `GLFW_REPEAT`.
* @param[in] action `GLFW_PRESS`, `GLFW_RELEASE` or `GLFW_REPEAT`. Future
* releases may add more actions.
* @param[in] mods Bit field describing which [modifier keys](@ref mods) were
* held down.
*
@ -1433,9 +1495,13 @@ typedef void (* GLFWscrollfun)(GLFWwindow*,double,double);
*/
typedef void (* GLFWkeyfun)(GLFWwindow*,int,int,int,int);
/*! @brief The function signature for Unicode character callbacks.
/*! @brief The function pointer type for Unicode character callbacks.
*
* This is the function signature for Unicode character callback functions.
* This is the function pointer type for Unicode character callbacks.
* A Unicode character callback function has the following signature:
* @code
* void function_name(GLFWwindow* window, unsigned int codepoint)
* @endcode
*
* @param[in] window The window that received the event.
* @param[in] codepoint The Unicode code point of the character.
@ -1450,12 +1516,16 @@ typedef void (* GLFWkeyfun)(GLFWwindow*,int,int,int,int);
*/
typedef void (* GLFWcharfun)(GLFWwindow*,unsigned int);
/*! @brief The function signature for Unicode character with modifiers
/*! @brief The function pointer type for Unicode character with modifiers
* callbacks.
*
* This is the function signature for Unicode character with modifiers callback
* functions. It is called for each input character, regardless of what
* modifier keys are held down.
* This is the function pointer type for Unicode character with modifiers
* callbacks. It is called for each input character, regardless of what
* modifier keys are held down. A Unicode character with modifiers callback
* function has the following signature:
* @code
* void function_name(GLFWwindow* window, unsigned int codepoint, int mods)
* @endcode
*
* @param[in] window The window that received the event.
* @param[in] codepoint The Unicode code point of the character.
@ -1473,14 +1543,21 @@ typedef void (* GLFWcharfun)(GLFWwindow*,unsigned int);
*/
typedef void (* GLFWcharmodsfun)(GLFWwindow*,unsigned int,int);
/*! @brief The function signature for file drop callbacks.
/*! @brief The function pointer type for path drop callbacks.
*
* This is the function signature for file drop callbacks.
* This is the function pointer type for path drop callbacks. A path drop
* callback function has the following signature:
* @code
* void function_name(GLFWwindow* window, int path_count, const char* paths[])
* @endcode
*
* @param[in] window The window that received the event.
* @param[in] count The number of dropped files.
* @param[in] path_count The number of dropped paths.
* @param[in] paths The UTF-8 encoded file and/or directory path names.
*
* @pointer_lifetime The path array and its strings are valid until the
* callback function returns.
*
* @sa @ref path_drop
* @sa @ref glfwSetDropCallback
*
@ -1488,15 +1565,19 @@ typedef void (* GLFWcharmodsfun)(GLFWwindow*,unsigned int,int);
*
* @ingroup input
*/
typedef void (* GLFWdropfun)(GLFWwindow*,int,const char**);
typedef void (* GLFWdropfun)(GLFWwindow*,int,const char*[]);
/*! @brief The function signature for monitor configuration callbacks.
/*! @brief The function pointer type for monitor configuration callbacks.
*
* This is the function signature for monitor configuration callback functions.
* This is the function pointer type for monitor configuration callbacks.
* A monitor callback function has the following signature:
* @code
* void function_name(GLFWmonitor* monitor, int event)
* @endcode
*
* @param[in] monitor The monitor that was connected or disconnected.
* @param[in] event One of `GLFW_CONNECTED` or `GLFW_DISCONNECTED`. Remaining
* values reserved for future use.
* @param[in] event One of `GLFW_CONNECTED` or `GLFW_DISCONNECTED`. Future
* releases may add more events.
*
* @sa @ref monitor_event
* @sa @ref glfwSetMonitorCallback
@ -1507,14 +1588,17 @@ typedef void (* GLFWdropfun)(GLFWwindow*,int,const char**);
*/
typedef void (* GLFWmonitorfun)(GLFWmonitor*,int);
/*! @brief The function signature for joystick configuration callbacks.
/*! @brief The function pointer type for joystick configuration callbacks.
*
* This is the function signature for joystick configuration callback
* functions.
* This is the function pointer type for joystick configuration callbacks.
* A joystick configuration callback function has the following signature:
* @code
* void function_name(int jid, int event)
* @endcode
*
* @param[in] jid The joystick that was connected or disconnected.
* @param[in] event One of `GLFW_CONNECTED` or `GLFW_DISCONNECTED`. Remaining
* values reserved for future use.
* @param[in] event One of `GLFW_CONNECTED` or `GLFW_DISCONNECTED`. Future
* releases may add more events.
*
* @sa @ref joystick_event
* @sa @ref glfwSetJoystickCallback
@ -1849,10 +1933,17 @@ GLFWAPI int glfwGetError(const char** description);
* Once set, the error callback remains set even after the library has been
* terminated.
*
* @param[in] cbfun The new callback, or `NULL` to remove the currently set
* @param[in] callback The new callback, or `NULL` to remove the currently set
* callback.
* @return The previously set callback, or `NULL` if no callback was set.
*
* @callback_signature
* @code
* void callback_name(int error_code, const char* description)
* @endcode
* For more information about the callback parameters, see the
* [callback pointer type](@ref GLFWerrorfun).
*
* @errors None.
*
* @remark This function may be called before @ref glfwInit.
@ -1866,7 +1957,7 @@ GLFWAPI int glfwGetError(const char** description);
*
* @ingroup init
*/
GLFWAPI GLFWerrorfun glfwSetErrorCallback(GLFWerrorfun cbfun);
GLFWAPI GLFWerrorfun glfwSetErrorCallback(GLFWerrorfun callback);
/*! @brief Returns the currently connected monitors.
*
@ -2125,11 +2216,18 @@ GLFWAPI void* glfwGetMonitorUserPointer(GLFWmonitor* monitor);
* currently set callback. This is called when a monitor is connected to or
* disconnected from the system.
*
* @param[in] cbfun The new callback, or `NULL` to remove the currently set
* @param[in] callback The new callback, or `NULL` to remove the currently set
* callback.
* @return The previously set callback, or `NULL` if no callback was set or the
* library had not been [initialized](@ref intro_init).
*
* @callback_signature
* @code
* void function_name(GLFWmonitor* monitor, int event)
* @endcode
* For more information about the callback parameters, see the
* [function pointer type](@ref GLFWmonitorfun).
*
* @errors Possible errors include @ref GLFW_NOT_INITIALIZED.
*
* @thread_safety This function must only be called from the main thread.
@ -2140,7 +2238,7 @@ GLFWAPI void* glfwGetMonitorUserPointer(GLFWmonitor* monitor);
*
* @ingroup monitor
*/
GLFWAPI GLFWmonitorfun glfwSetMonitorCallback(GLFWmonitorfun cbfun);
GLFWAPI GLFWmonitorfun glfwSetMonitorCallback(GLFWmonitorfun callback);
/*! @brief Returns the available video modes for the specified monitor.
*
@ -3477,11 +3575,18 @@ GLFWAPI void* glfwGetWindowUserPointer(GLFWwindow* window);
* area of the window.
*
* @param[in] window The window whose callback to set.
* @param[in] cbfun The new callback, or `NULL` to remove the currently set
* @param[in] callback The new callback, or `NULL` to remove the currently set
* callback.
* @return The previously set callback, or `NULL` if no callback was set or the
* library had not been [initialized](@ref intro_init).
*
* @callback_signature
* @code
* void function_name(GLFWwindow* window, int xpos, int ypos)
* @endcode
* For more information about the callback parameters, see the
* [function pointer type](@ref GLFWwindowposfun).
*
* @errors Possible errors include @ref GLFW_NOT_INITIALIZED.
*
* @remark @wayland This callback will never be called, as there is no way for
@ -3495,7 +3600,7 @@ GLFWAPI void* glfwGetWindowUserPointer(GLFWwindow* window);
*
* @ingroup window
*/
GLFWAPI GLFWwindowposfun glfwSetWindowPosCallback(GLFWwindow* window, GLFWwindowposfun cbfun);
GLFWAPI GLFWwindowposfun glfwSetWindowPosCallback(GLFWwindow* window, GLFWwindowposfun callback);
/*! @brief Sets the size callback for the specified window.
*
@ -3504,11 +3609,18 @@ GLFWAPI GLFWwindowposfun glfwSetWindowPosCallback(GLFWwindow* window, GLFWwindow
* in screen coordinates, of the content area of the window.
*
* @param[in] window The window whose callback to set.
* @param[in] cbfun The new callback, or `NULL` to remove the currently set
* @param[in] callback The new callback, or `NULL` to remove the currently set
* callback.
* @return The previously set callback, or `NULL` if no callback was set or the
* library had not been [initialized](@ref intro_init).
*
* @callback_signature
* @code
* void function_name(GLFWwindow* window, int width, int height)
* @endcode
* For more information about the callback parameters, see the
* [function pointer type](@ref GLFWwindowsizefun).
*
* @errors Possible errors include @ref GLFW_NOT_INITIALIZED.
*
* @thread_safety This function must only be called from the main thread.
@ -3520,7 +3632,7 @@ GLFWAPI GLFWwindowposfun glfwSetWindowPosCallback(GLFWwindow* window, GLFWwindow
*
* @ingroup window
*/
GLFWAPI GLFWwindowsizefun glfwSetWindowSizeCallback(GLFWwindow* window, GLFWwindowsizefun cbfun);
GLFWAPI GLFWwindowsizefun glfwSetWindowSizeCallback(GLFWwindow* window, GLFWwindowsizefun callback);
/*! @brief Sets the close callback for the specified window.
*
@ -3534,11 +3646,18 @@ GLFWAPI GLFWwindowsizefun glfwSetWindowSizeCallback(GLFWwindow* window, GLFWwind
* The close callback is not triggered by @ref glfwDestroyWindow.
*
* @param[in] window The window whose callback to set.
* @param[in] cbfun The new callback, or `NULL` to remove the currently set
* @param[in] callback The new callback, or `NULL` to remove the currently set
* callback.
* @return The previously set callback, or `NULL` if no callback was set or the
* library had not been [initialized](@ref intro_init).
*
* @callback_signature
* @code
* void function_name(GLFWwindow* window)
* @endcode
* For more information about the callback parameters, see the
* [function pointer type](@ref GLFWwindowclosefun).
*
* @errors Possible errors include @ref GLFW_NOT_INITIALIZED.
*
* @remark @macos Selecting Quit from the application menu will trigger the
@ -3553,7 +3672,7 @@ GLFWAPI GLFWwindowsizefun glfwSetWindowSizeCallback(GLFWwindow* window, GLFWwind
*
* @ingroup window
*/
GLFWAPI GLFWwindowclosefun glfwSetWindowCloseCallback(GLFWwindow* window, GLFWwindowclosefun cbfun);
GLFWAPI GLFWwindowclosefun glfwSetWindowCloseCallback(GLFWwindow* window, GLFWwindowclosefun callback);
/*! @brief Sets the refresh callback for the specified window.
*
@ -3566,11 +3685,18 @@ GLFWAPI GLFWwindowclosefun glfwSetWindowCloseCallback(GLFWwindow* window, GLFWwi
* very infrequently or never at all.
*
* @param[in] window The window whose callback to set.
* @param[in] cbfun The new callback, or `NULL` to remove the currently set
* @param[in] callback The new callback, or `NULL` to remove the currently set
* callback.
* @return The previously set callback, or `NULL` if no callback was set or the
* library had not been [initialized](@ref intro_init).
*
* @callback_signature
* @code
* void function_name(GLFWwindow* window);
* @endcode
* For more information about the callback parameters, see the
* [function pointer type](@ref GLFWwindowrefreshfun).
*
* @errors Possible errors include @ref GLFW_NOT_INITIALIZED.
*
* @thread_safety This function must only be called from the main thread.
@ -3582,7 +3708,7 @@ GLFWAPI GLFWwindowclosefun glfwSetWindowCloseCallback(GLFWwindow* window, GLFWwi
*
* @ingroup window
*/
GLFWAPI GLFWwindowrefreshfun glfwSetWindowRefreshCallback(GLFWwindow* window, GLFWwindowrefreshfun cbfun);
GLFWAPI GLFWwindowrefreshfun glfwSetWindowRefreshCallback(GLFWwindow* window, GLFWwindowrefreshfun callback);
/*! @brief Sets the focus callback for the specified window.
*
@ -3595,11 +3721,18 @@ GLFWAPI GLFWwindowrefreshfun glfwSetWindowRefreshCallback(GLFWwindow* window, GL
* and @ref glfwSetMouseButtonCallback.
*
* @param[in] window The window whose callback to set.
* @param[in] cbfun The new callback, or `NULL` to remove the currently set
* @param[in] callback The new callback, or `NULL` to remove the currently set
* callback.
* @return The previously set callback, or `NULL` if no callback was set or the
* library had not been [initialized](@ref intro_init).
*
* @callback_signature
* @code
* void function_name(GLFWwindow* window, int focused)
* @endcode
* For more information about the callback parameters, see the
* [function pointer type](@ref GLFWwindowfocusfun).
*
* @errors Possible errors include @ref GLFW_NOT_INITIALIZED.
*
* @thread_safety This function must only be called from the main thread.
@ -3610,7 +3743,7 @@ GLFWAPI GLFWwindowrefreshfun glfwSetWindowRefreshCallback(GLFWwindow* window, GL
*
* @ingroup window
*/
GLFWAPI GLFWwindowfocusfun glfwSetWindowFocusCallback(GLFWwindow* window, GLFWwindowfocusfun cbfun);
GLFWAPI GLFWwindowfocusfun glfwSetWindowFocusCallback(GLFWwindow* window, GLFWwindowfocusfun callback);
/*! @brief Sets the iconify callback for the specified window.
*
@ -3618,11 +3751,18 @@ GLFWAPI GLFWwindowfocusfun glfwSetWindowFocusCallback(GLFWwindow* window, GLFWwi
* is called when the window is iconified or restored.
*
* @param[in] window The window whose callback to set.
* @param[in] cbfun The new callback, or `NULL` to remove the currently set
* @param[in] callback The new callback, or `NULL` to remove the currently set
* callback.
* @return The previously set callback, or `NULL` if no callback was set or the
* library had not been [initialized](@ref intro_init).
*
* @callback_signature
* @code
* void function_name(GLFWwindow* window, int iconified)
* @endcode
* For more information about the callback parameters, see the
* [function pointer type](@ref GLFWwindowiconifyfun).
*
* @errors Possible errors include @ref GLFW_NOT_INITIALIZED.
*
* @remark @wayland The wl_shell protocol has no concept of iconification,
@ -3636,7 +3776,7 @@ GLFWAPI GLFWwindowfocusfun glfwSetWindowFocusCallback(GLFWwindow* window, GLFWwi
*
* @ingroup window
*/
GLFWAPI GLFWwindowiconifyfun glfwSetWindowIconifyCallback(GLFWwindow* window, GLFWwindowiconifyfun cbfun);
GLFWAPI GLFWwindowiconifyfun glfwSetWindowIconifyCallback(GLFWwindow* window, GLFWwindowiconifyfun callback);
/*! @brief Sets the maximize callback for the specified window.
*
@ -3644,11 +3784,18 @@ GLFWAPI GLFWwindowiconifyfun glfwSetWindowIconifyCallback(GLFWwindow* window, GL
* is called when the window is maximized or restored.
*
* @param[in] window The window whose callback to set.
* @param[in] cbfun The new callback, or `NULL` to remove the currently set
* @param[in] callback The new callback, or `NULL` to remove the currently set
* callback.
* @return The previously set callback, or `NULL` if no callback was set or the
* library had not been [initialized](@ref intro_init).
*
* @callback_signature
* @code
* void function_name(GLFWwindow* window, int maximized)
* @endcode
* For more information about the callback parameters, see the
* [function pointer type](@ref GLFWwindowmaximizefun).
*
* @errors Possible errors include @ref GLFW_NOT_INITIALIZED.
*
* @thread_safety This function must only be called from the main thread.
@ -3659,7 +3806,7 @@ GLFWAPI GLFWwindowiconifyfun glfwSetWindowIconifyCallback(GLFWwindow* window, GL
*
* @ingroup window
*/
GLFWAPI GLFWwindowmaximizefun glfwSetWindowMaximizeCallback(GLFWwindow* window, GLFWwindowmaximizefun cbfun);
GLFWAPI GLFWwindowmaximizefun glfwSetWindowMaximizeCallback(GLFWwindow* window, GLFWwindowmaximizefun callback);
/*! @brief Sets the framebuffer resize callback for the specified window.
*
@ -3667,11 +3814,18 @@ GLFWAPI GLFWwindowmaximizefun glfwSetWindowMaximizeCallback(GLFWwindow* window,
* which is called when the framebuffer of the specified window is resized.
*
* @param[in] window The window whose callback to set.
* @param[in] cbfun The new callback, or `NULL` to remove the currently set
* @param[in] callback The new callback, or `NULL` to remove the currently set
* callback.
* @return The previously set callback, or `NULL` if no callback was set or the
* library had not been [initialized](@ref intro_init).
*
* @callback_signature
* @code
* void function_name(GLFWwindow* window, int width, int height)
* @endcode
* For more information about the callback parameters, see the
* [function pointer type](@ref GLFWframebuffersizefun).
*
* @errors Possible errors include @ref GLFW_NOT_INITIALIZED.
*
* @thread_safety This function must only be called from the main thread.
@ -3682,7 +3836,7 @@ GLFWAPI GLFWwindowmaximizefun glfwSetWindowMaximizeCallback(GLFWwindow* window,
*
* @ingroup window
*/
GLFWAPI GLFWframebuffersizefun glfwSetFramebufferSizeCallback(GLFWwindow* window, GLFWframebuffersizefun cbfun);
GLFWAPI GLFWframebuffersizefun glfwSetFramebufferSizeCallback(GLFWwindow* window, GLFWframebuffersizefun callback);
/*! @brief Sets the window content scale callback for the specified window.
*
@ -3690,11 +3844,18 @@ GLFWAPI GLFWframebuffersizefun glfwSetFramebufferSizeCallback(GLFWwindow* window
* which is called when the content scale of the specified window changes.
*
* @param[in] window The window whose callback to set.
* @param[in] cbfun The new callback, or `NULL` to remove the currently set
* @param[in] callback The new callback, or `NULL` to remove the currently set
* callback.
* @return The previously set callback, or `NULL` if no callback was set or the
* library had not been [initialized](@ref intro_init).
*
* @callback_signature
* @code
* void function_name(GLFWwindow* window, float xscale, float yscale)
* @endcode
* For more information about the callback parameters, see the
* [function pointer type](@ref GLFWwindowcontentscalefun).
*
* @errors Possible errors include @ref GLFW_NOT_INITIALIZED.
*
* @thread_safety This function must only be called from the main thread.
@ -3706,7 +3867,7 @@ GLFWAPI GLFWframebuffersizefun glfwSetFramebufferSizeCallback(GLFWwindow* window
*
* @ingroup window
*/
GLFWAPI GLFWwindowcontentscalefun glfwSetWindowContentScaleCallback(GLFWwindow* window, GLFWwindowcontentscalefun cbfun);
GLFWAPI GLFWwindowcontentscalefun glfwSetWindowContentScaleCallback(GLFWwindow* window, GLFWwindowcontentscalefun callback);
/*! @brief Processes all pending events.
*
@ -4353,11 +4514,18 @@ GLFWAPI void glfwSetCursor(GLFWwindow* window, GLFWcursor* cursor);
* scancode may be zero.
*
* @param[in] window The window whose callback to set.
* @param[in] cbfun The new key callback, or `NULL` to remove the currently
* @param[in] callback The new key callback, or `NULL` to remove the currently
* set callback.
* @return The previously set callback, or `NULL` if no callback was set or the
* library had not been [initialized](@ref intro_init).
*
* @callback_signature
* @code
* void function_name(GLFWwindow* window, int key, int scancode, int action, int mods)
* @endcode
* For more information about the callback parameters, see the
* [function pointer type](@ref GLFWkeyfun).
*
* @errors Possible errors include @ref GLFW_NOT_INITIALIZED.
*
* @thread_safety This function must only be called from the main thread.
@ -4369,7 +4537,7 @@ GLFWAPI void glfwSetCursor(GLFWwindow* window, GLFWcursor* cursor);
*
* @ingroup input
*/
GLFWAPI GLFWkeyfun glfwSetKeyCallback(GLFWwindow* window, GLFWkeyfun cbfun);
GLFWAPI GLFWkeyfun glfwSetKeyCallback(GLFWwindow* window, GLFWkeyfun callback);
/*! @brief Sets the Unicode character callback.
*
@ -4389,11 +4557,18 @@ GLFWAPI GLFWkeyfun glfwSetKeyCallback(GLFWwindow* window, GLFWkeyfun cbfun);
* on Windows.
*
* @param[in] window The window whose callback to set.
* @param[in] cbfun The new callback, or `NULL` to remove the currently set
* @param[in] callback The new callback, or `NULL` to remove the currently set
* callback.
* @return The previously set callback, or `NULL` if no callback was set or the
* library had not been [initialized](@ref intro_init).
*
* @callback_signature
* @code
* void function_name(GLFWwindow* window, unsigned int codepoint)
* @endcode
* For more information about the callback parameters, see the
* [function pointer type](@ref GLFWcharfun).
*
* @errors Possible errors include @ref GLFW_NOT_INITIALIZED.
*
* @thread_safety This function must only be called from the main thread.
@ -4405,7 +4580,7 @@ GLFWAPI GLFWkeyfun glfwSetKeyCallback(GLFWwindow* window, GLFWkeyfun cbfun);
*
* @ingroup input
*/
GLFWAPI GLFWcharfun glfwSetCharCallback(GLFWwindow* window, GLFWcharfun cbfun);
GLFWAPI GLFWcharfun glfwSetCharCallback(GLFWwindow* window, GLFWcharfun callback);
/*! @brief Sets the Unicode character with modifiers callback.
*
@ -4423,11 +4598,18 @@ GLFWAPI GLFWcharfun glfwSetCharCallback(GLFWwindow* window, GLFWcharfun cbfun);
* [key callback](@ref glfwSetKeyCallback) instead.
*
* @param[in] window The window whose callback to set.
* @param[in] cbfun The new callback, or `NULL` to remove the currently set
* @param[in] callback The new callback, or `NULL` to remove the currently set
* callback.
* @return The previously set callback, or `NULL` if no callback was set or an
* [error](@ref error_handling) occurred.
*
* @callback_signature
* @code
* void function_name(GLFWwindow* window, unsigned int codepoint, int mods)
* @endcode
* For more information about the callback parameters, see the
* [function pointer type](@ref GLFWcharmodsfun).
*
* @deprecated Scheduled for removal in version 4.0.
*
* @errors Possible errors include @ref GLFW_NOT_INITIALIZED.
@ -4440,7 +4622,7 @@ GLFWAPI GLFWcharfun glfwSetCharCallback(GLFWwindow* window, GLFWcharfun cbfun);
*
* @ingroup input
*/
GLFWAPI GLFWcharmodsfun glfwSetCharModsCallback(GLFWwindow* window, GLFWcharmodsfun cbfun);
GLFWAPI GLFWcharmodsfun glfwSetCharModsCallback(GLFWwindow* window, GLFWcharmodsfun callback);
/*! @brief Sets the mouse button callback.
*
@ -4454,11 +4636,18 @@ GLFWAPI GLFWcharmodsfun glfwSetCharModsCallback(GLFWwindow* window, GLFWcharmods
* [window focus callback](@ref glfwSetWindowFocusCallback) has been called.
*
* @param[in] window The window whose callback to set.
* @param[in] cbfun The new callback, or `NULL` to remove the currently set
* @param[in] callback The new callback, or `NULL` to remove the currently set
* callback.
* @return The previously set callback, or `NULL` if no callback was set or the
* library had not been [initialized](@ref intro_init).
*
* @callback_signature
* @code
* void function_name(GLFWwindow* window, int button, int action, int mods)
* @endcode
* For more information about the callback parameters, see the
* [function pointer type](@ref GLFWmousebuttonfun).
*
* @errors Possible errors include @ref GLFW_NOT_INITIALIZED.
*
* @thread_safety This function must only be called from the main thread.
@ -4470,7 +4659,7 @@ GLFWAPI GLFWcharmodsfun glfwSetCharModsCallback(GLFWwindow* window, GLFWcharmods
*
* @ingroup input
*/
GLFWAPI GLFWmousebuttonfun glfwSetMouseButtonCallback(GLFWwindow* window, GLFWmousebuttonfun cbfun);
GLFWAPI GLFWmousebuttonfun glfwSetMouseButtonCallback(GLFWwindow* window, GLFWmousebuttonfun callback);
/*! @brief Sets the cursor position callback.
*
@ -4480,11 +4669,18 @@ GLFWAPI GLFWmousebuttonfun glfwSetMouseButtonCallback(GLFWwindow* window, GLFWmo
* content area of the window.
*
* @param[in] window The window whose callback to set.
* @param[in] cbfun The new callback, or `NULL` to remove the currently set
* @param[in] callback The new callback, or `NULL` to remove the currently set
* callback.
* @return The previously set callback, or `NULL` if no callback was set or the
* library had not been [initialized](@ref intro_init).
*
* @callback_signature
* @code
* void function_name(GLFWwindow* window, double xpos, double ypos);
* @endcode
* For more information about the callback parameters, see the
* [function pointer type](@ref GLFWcursorposfun).
*
* @errors Possible errors include @ref GLFW_NOT_INITIALIZED.
*
* @thread_safety This function must only be called from the main thread.
@ -4495,20 +4691,27 @@ GLFWAPI GLFWmousebuttonfun glfwSetMouseButtonCallback(GLFWwindow* window, GLFWmo
*
* @ingroup input
*/
GLFWAPI GLFWcursorposfun glfwSetCursorPosCallback(GLFWwindow* window, GLFWcursorposfun cbfun);
GLFWAPI GLFWcursorposfun glfwSetCursorPosCallback(GLFWwindow* window, GLFWcursorposfun callback);
/*! @brief Sets the cursor enter/exit callback.
/*! @brief Sets the cursor enter/leave callback.
*
* This function sets the cursor boundary crossing callback of the specified
* window, which is called when the cursor enters or leaves the content area of
* the window.
*
* @param[in] window The window whose callback to set.
* @param[in] cbfun The new callback, or `NULL` to remove the currently set
* @param[in] callback The new callback, or `NULL` to remove the currently set
* callback.
* @return The previously set callback, or `NULL` if no callback was set or the
* library had not been [initialized](@ref intro_init).
*
* @callback_signature
* @code
* void function_name(GLFWwindow* window, int entered)
* @endcode
* For more information about the callback parameters, see the
* [function pointer type](@ref GLFWcursorenterfun).
*
* @errors Possible errors include @ref GLFW_NOT_INITIALIZED.
*
* @thread_safety This function must only be called from the main thread.
@ -4519,7 +4722,7 @@ GLFWAPI GLFWcursorposfun glfwSetCursorPosCallback(GLFWwindow* window, GLFWcursor
*
* @ingroup input
*/
GLFWAPI GLFWcursorenterfun glfwSetCursorEnterCallback(GLFWwindow* window, GLFWcursorenterfun cbfun);
GLFWAPI GLFWcursorenterfun glfwSetCursorEnterCallback(GLFWwindow* window, GLFWcursorenterfun callback);
/*! @brief Sets the scroll callback.
*
@ -4531,11 +4734,18 @@ GLFWAPI GLFWcursorenterfun glfwSetCursorEnterCallback(GLFWwindow* window, GLFWcu
* wheel or a touchpad scrolling area.
*
* @param[in] window The window whose callback to set.
* @param[in] cbfun The new scroll callback, or `NULL` to remove the currently
* set callback.
* @param[in] callback The new scroll callback, or `NULL` to remove the
* currently set callback.
* @return The previously set callback, or `NULL` if no callback was set or the
* library had not been [initialized](@ref intro_init).
*
* @callback_signature
* @code
* void function_name(GLFWwindow* window, double xoffset, double yoffset)
* @endcode
* For more information about the callback parameters, see the
* [function pointer type](@ref GLFWscrollfun).
*
* @errors Possible errors include @ref GLFW_NOT_INITIALIZED.
*
* @thread_safety This function must only be called from the main thread.
@ -4546,12 +4756,12 @@ GLFWAPI GLFWcursorenterfun glfwSetCursorEnterCallback(GLFWwindow* window, GLFWcu
*
* @ingroup input
*/
GLFWAPI GLFWscrollfun glfwSetScrollCallback(GLFWwindow* window, GLFWscrollfun cbfun);
GLFWAPI GLFWscrollfun glfwSetScrollCallback(GLFWwindow* window, GLFWscrollfun callback);
/*! @brief Sets the file drop callback.
/*! @brief Sets the path drop callback.
*
* This function sets the file drop callback of the specified window, which is
* called when one or more dragged files are dropped on the window.
* This function sets the path drop callback of the specified window, which is
* called when one or more dragged paths are dropped on the window.
*
* Because the path array and its strings may have been generated specifically
* for that event, they are not guaranteed to be valid after the callback has
@ -4559,11 +4769,18 @@ GLFWAPI GLFWscrollfun glfwSetScrollCallback(GLFWwindow* window, GLFWscrollfun cb
* make a deep copy.
*
* @param[in] window The window whose callback to set.
* @param[in] cbfun The new file drop callback, or `NULL` to remove the
* @param[in] callback The new file drop callback, or `NULL` to remove the
* currently set callback.
* @return The previously set callback, or `NULL` if no callback was set or the
* library had not been [initialized](@ref intro_init).
*
* @callback_signature
* @code
* void function_name(GLFWwindow* window, int path_count, const char* paths[])
* @endcode
* For more information about the callback parameters, see the
* [function pointer type](@ref GLFWdropfun).
*
* @errors Possible errors include @ref GLFW_NOT_INITIALIZED.
*
* @remark @wayland File drop is currently unimplemented.
@ -4576,7 +4793,7 @@ GLFWAPI GLFWscrollfun glfwSetScrollCallback(GLFWwindow* window, GLFWscrollfun cb
*
* @ingroup input
*/
GLFWAPI GLFWdropfun glfwSetDropCallback(GLFWwindow* window, GLFWdropfun cbfun);
GLFWAPI GLFWdropfun glfwSetDropCallback(GLFWwindow* window, GLFWdropfun callback);
/*! @brief Returns whether the specified joystick is present.
*
@ -4895,11 +5112,18 @@ GLFWAPI int glfwJoystickIsGamepad(int jid);
* called by joystick functions. The function will then return whatever it
* returns if the joystick is not present.
*
* @param[in] cbfun The new callback, or `NULL` to remove the currently set
* @param[in] callback The new callback, or `NULL` to remove the currently set
* callback.
* @return The previously set callback, or `NULL` if no callback was set or the
* library had not been [initialized](@ref intro_init).
*
* @callback_signature
* @code
* void function_name(int jid, int event)
* @endcode
* For more information about the callback parameters, see the
* [function pointer type](@ref GLFWjoystickfun).
*
* @errors Possible errors include @ref GLFW_NOT_INITIALIZED.
*
* @thread_safety This function must only be called from the main thread.
@ -4910,7 +5134,7 @@ GLFWAPI int glfwJoystickIsGamepad(int jid);
*
* @ingroup input
*/
GLFWAPI GLFWjoystickfun glfwSetJoystickCallback(GLFWjoystickfun cbfun);
GLFWAPI GLFWjoystickfun glfwSetJoystickCallback(GLFWjoystickfun callback);
/*! @brief Adds the specified SDL_GameControllerDB gamepad mappings.
*

2
tests/events.c
View File

@ -429,7 +429,7 @@ static void char_callback(GLFWwindow* window, unsigned int codepoint)
get_character_string(codepoint));
}
static void drop_callback(GLFWwindow* window, int count, const char** paths)
static void drop_callback(GLFWwindow* window, int count, const char* paths[])
{
int i;
Slot* slot = glfwGetWindowUserPointer(window);

2
tests/joysticks.c
View File

@ -85,7 +85,7 @@ static void joystick_callback(int jid, int event)
glfwRequestWindowAttention(window);
}
static void drop_callback(GLFWwindow* window, int count, const char** paths)
static void drop_callback(GLFWwindow* window, int count, const char* paths[])
{
int i;