diff --git a/README.md b/README.md index 476bd87a..c9499fd9 100644 --- a/README.md +++ b/README.md @@ -132,6 +132,7 @@ information on what to include when reporting a bug. - Added `glfwInitAllocator` for setting a custom memory allocator (#544,#1628,#1947) - Added `GLFWallocator` struct and `GLFWallocatefun`, `GLFWreallocatefun` and `GLFWdeallocatefun` types (#544,#1628,#1947) + - Added `glfwGetWindowTitle` function for querying window title (#1448,#1909,#2482) - Added `glfwInitVulkanLoader` for using a non-default Vulkan loader (#1374,#1890) - Added `GLFW_RESIZE_NWSE_CURSOR`, `GLFW_RESIZE_NESW_CURSOR`, `GLFW_RESIZE_ALL_CURSOR` and `GLFW_NOT_ALLOWED_CURSOR` cursor shapes (#427) @@ -167,7 +168,6 @@ information on what to include when reporting a bug. - Added support for `XDG_SESSION_TYPE` environment variable - Added `GLFW_PKG_CONFIG_REQUIRES_PRIVATE` and `GLFW_PKG_CONFIG_LIBS_PRIVATE` CMake variables exposing pkg-config dependencies (#1307) - - Added `glfwGetWindowTitle` function for GLFWwindow for querying window titles (#1448,#1909) - Made joystick subsystem initialize at first use (#1284,#1646) - Made `GLFW_DOUBLEBUFFER` a read-only window attribute - Updated the minimum required CMake version to 3.1 diff --git a/docs/news.md b/docs/news.md index 4f8bbbe5..3d820be1 100644 --- a/docs/news.md +++ b/docs/news.md @@ -41,11 +41,13 @@ to whatever window is behind it. This can also be changed after window creation with the matching [window attribute](@ref GLFW_MOUSE_PASSTHROUGH_attrib). -#### Ability to get a window's title {#features_34_get_window_title} +#### Ability to get window title {#features_34_window_title} -GLFW now supports retrieving a window's title with the @ref glfwGetWindowTitle +GLFW now supports querying the title of a window with the @ref glfwGetWindowTitle function. +For more information see @ref window_title. + #### Wayland libdecor decorations {#wayland_libdecor_34} diff --git a/docs/window.md b/docs/window.md index bfd99bc8..3d6c6805 100644 --- a/docs/window.md +++ b/docs/window.md @@ -897,7 +897,7 @@ glfwGetWindowPos(window, &xpos, &ypos); All GLFW windows have a title, although undecorated or full screen windows may not display it or only display it in a task bar or similar interface. You can -set a UTF-8 encoded window title with @ref glfwSetWindowTitle. +set a new UTF-8 encoded window title with @ref glfwSetWindowTitle. ```c glfwSetWindowTitle(window, "My Window"); @@ -919,16 +919,12 @@ If you are using C++11 or C11, you can use a UTF-8 string literal. glfwSetWindowTitle(window, u8"This is always a UTF-8 string"); ``` -The window title can be retrieved with @ref glfwGetWindowTitle. +The current window title can be queried with @ref glfwGetWindowTitle. ```c const char* title = glfwGetWindowTitle(window); ``` -The title returned is an internally managed copy of the title set -by @ref glfwCreateWindow or @ref glfwSetWindowTitle. It does not -include any additional text which may be appended by the platform. - ### Window icon {#window_icon} Decorated windows have icons on some platforms. You can set this icon by diff --git a/include/GLFW/glfw3.h b/include/GLFW/glfw3.h index 3563ca62..da3c3c57 100644 --- a/include/GLFW/glfw3.h +++ b/include/GLFW/glfw3.h @@ -3305,26 +3305,34 @@ GLFWAPI int glfwWindowShouldClose(GLFWwindow* window); */ GLFWAPI void glfwSetWindowShouldClose(GLFWwindow* window, int value); -/*! @brief Retrieves the title of the specified window. +/*! @brief Returns the title of the specified window. * - * This function gets the window title, encoded as UTF-8, of the specified - * window. + * This function returns the window title, encoded as UTF-8, of the specified + * window. This is the title set previously by @ref glfwCreateWindow + * or @ref glfwSetWindowTitle. * * @param[in] window The window to query. - * @return A copy of the UTF-8 encoded window title, as set by glfwCreateWindow - * or glfwSetWindowTitle, or NULL if there is an error. + * @return The UTF-8 encoded window title, or `NULL` if an + * [error](@ref error_handling) occurred. * - * @errors Possible errors include @ref GLFW_NOT_INITIALIZED + * @errors Possible errors include @ref GLFW_NOT_INITIALIZED. + * + * @remark The returned title is currently a copy of the title last set by @ref + * glfwCreateWindow or @ref glfwSetWindowTitle. It does not include any + * additional text which may be appended by the platform or another program. * * @pointer_lifetime The returned string is allocated and freed by GLFW. You * should not free it yourself. It is valid until the next call to @ref - * glfwSetWindowTitle, or until the library is terminated. + * glfwGetWindowTitle or @ref glfwSetWindowTitle, or until the library is + * terminated. * * @thread_safety This function must only be called from the main thread. * * @sa @ref window_title * @sa @ref glfwSetWindowTitle * + * @since Added in version 3.4. + * * @ingroup window */ GLFWAPI const char* glfwGetWindowTitle(GLFWwindow* window); @@ -3346,6 +3354,7 @@ GLFWAPI const char* glfwGetWindowTitle(GLFWwindow* window); * @thread_safety This function must only be called from the main thread. * * @sa @ref window_title + * @sa @ref glfwGetWindowTitle * * @since Added in version 1.0. * @glfw3 Added window handle parameter.