Improve (?) reference documentation for callbacks
diff --git a/include/GLFW/glfw3.h b/include/GLFW/glfw3.h
index 9cedc76..07345ae 100644
--- a/include/GLFW/glfw3.h
+++ b/include/GLFW/glfw3.h
@@ -1164,13 +1164,21 @@
*/
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 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 (* 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 (* 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 (* 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 (* 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 (* 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 (* 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 (* 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 (* 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 (* 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 (* 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 (* 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 (* 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 (* 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 (* 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 (* 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 (* 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 @@
*
* @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 (* 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 @@
* 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 @@
*
* @ingroup init
*/
-GLFWAPI GLFWerrorfun glfwSetErrorCallback(GLFWerrorfun cbfun);
+GLFWAPI GLFWerrorfun glfwSetErrorCallback(GLFWerrorfun callback);
/*! @brief Returns the currently connected monitors.
*
@@ -2125,11 +2216,18 @@
* 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 @@
*
* @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 @@
* 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 @@
*
* @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 @@
* 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 @@
*
* @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 @@
* 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 @@
*
* @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 @@
* 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 @@
*
* @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 @@
* 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 @@
*
* @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 @@
* 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.
*
* @thread_safety This function must only be called from the main thread.
@@ -3633,7 +3773,7 @@
*
* @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.
*
@@ -3641,11 +3781,18 @@
* 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.
@@ -3656,7 +3803,7 @@
*
* @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.
*
@@ -3664,11 +3811,18 @@
* 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.
@@ -3679,7 +3833,7 @@
*
* @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.
*
@@ -3687,11 +3841,18 @@
* 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.
@@ -3703,7 +3864,7 @@
*
* @ingroup window
*/
-GLFWAPI GLFWwindowcontentscalefun glfwSetWindowContentScaleCallback(GLFWwindow* window, GLFWwindowcontentscalefun cbfun);
+GLFWAPI GLFWwindowcontentscalefun glfwSetWindowContentScaleCallback(GLFWwindow* window, GLFWwindowcontentscalefun callback);
/*! @brief Processes all pending events.
*
@@ -4350,11 +4511,18 @@
* 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.
@@ -4366,7 +4534,7 @@
*
* @ingroup input
*/
-GLFWAPI GLFWkeyfun glfwSetKeyCallback(GLFWwindow* window, GLFWkeyfun cbfun);
+GLFWAPI GLFWkeyfun glfwSetKeyCallback(GLFWwindow* window, GLFWkeyfun callback);
/*! @brief Sets the Unicode character callback.
*
@@ -4386,11 +4554,18 @@
* 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.
@@ -4402,7 +4577,7 @@
*
* @ingroup input
*/
-GLFWAPI GLFWcharfun glfwSetCharCallback(GLFWwindow* window, GLFWcharfun cbfun);
+GLFWAPI GLFWcharfun glfwSetCharCallback(GLFWwindow* window, GLFWcharfun callback);
/*! @brief Sets the Unicode character with modifiers callback.
*
@@ -4420,11 +4595,18 @@
* [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.
@@ -4437,7 +4619,7 @@
*
* @ingroup input
*/
-GLFWAPI GLFWcharmodsfun glfwSetCharModsCallback(GLFWwindow* window, GLFWcharmodsfun cbfun);
+GLFWAPI GLFWcharmodsfun glfwSetCharModsCallback(GLFWwindow* window, GLFWcharmodsfun callback);
/*! @brief Sets the mouse button callback.
*
@@ -4451,11 +4633,18 @@
* [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.
@@ -4467,7 +4656,7 @@
*
* @ingroup input
*/
-GLFWAPI GLFWmousebuttonfun glfwSetMouseButtonCallback(GLFWwindow* window, GLFWmousebuttonfun cbfun);
+GLFWAPI GLFWmousebuttonfun glfwSetMouseButtonCallback(GLFWwindow* window, GLFWmousebuttonfun callback);
/*! @brief Sets the cursor position callback.
*
@@ -4477,11 +4666,18 @@
* 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.
@@ -4492,20 +4688,27 @@
*
* @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.
@@ -4516,7 +4719,7 @@
*
* @ingroup input
*/
-GLFWAPI GLFWcursorenterfun glfwSetCursorEnterCallback(GLFWwindow* window, GLFWcursorenterfun cbfun);
+GLFWAPI GLFWcursorenterfun glfwSetCursorEnterCallback(GLFWwindow* window, GLFWcursorenterfun callback);
/*! @brief Sets the scroll callback.
*
@@ -4528,11 +4731,18 @@
* 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.
@@ -4543,12 +4753,12 @@
*
* @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
@@ -4556,11 +4766,18 @@
* 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.
@@ -4573,7 +4790,7 @@
*
* @ingroup input
*/
-GLFWAPI GLFWdropfun glfwSetDropCallback(GLFWwindow* window, GLFWdropfun cbfun);
+GLFWAPI GLFWdropfun glfwSetDropCallback(GLFWwindow* window, GLFWdropfun callback);
/*! @brief Returns whether the specified joystick is present.
*
@@ -4892,11 +5109,18 @@
* 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.
@@ -4907,7 +5131,7 @@
*
* @ingroup input
*/
-GLFWAPI GLFWjoystickfun glfwSetJoystickCallback(GLFWjoystickfun cbfun);
+GLFWAPI GLFWjoystickfun glfwSetJoystickCallback(GLFWjoystickfun callback);
/*! @brief Adds the specified SDL_GameControllerDB gamepad mappings.
*
