Sync SDL3_ttf header -> wiki

libsdl-org · Oct 20, 2024 · 08ecbff · 08ecbff
1 parent fc4f509
commit 08ecbff
Show file tree

Hide file tree

Showing 19 changed files with 338 additions and 1 deletion.
diff --git a/SDL3_ttf/TTF_AppendTextString.md b/SDL3_ttf/TTF_AppendTextString.md
@@ -34,6 +34,12 @@ This function should be called on the thread that created the text.
 
 This function is available since SDL_ttf 3.0.0.
 
+## See Also
+
+- [TTF_DeleteTextString](TTF_DeleteTextString)
+- [TTF_InsertTextString](TTF_InsertTextString)
+- [TTF_SetTextString](TTF_SetTextString)
+
 ----
 [CategoryAPI](CategoryAPI), [CategoryAPIFunction](CategoryAPIFunction)
 
diff --git a/SDL3_ttf/TTF_DeleteTextString.md b/SDL3_ttf/TTF_DeleteTextString.md
@@ -34,6 +34,12 @@ This function should be called on the thread that created the text.
 
 This function is available since SDL_ttf 3.0.0.
 
+## See Also
+
+- [TTF_AppendTextString](TTF_AppendTextString)
+- [TTF_InsertTextString](TTF_InsertTextString)
+- [TTF_SetTextString](TTF_SetTextString)
+
 ----
 [CategoryAPI](CategoryAPI), [CategoryAPIFunction](CategoryAPIFunction)
 
diff --git a/SDL3_ttf/TTF_GetTextColor.md b/SDL3_ttf/TTF_GetTextColor.md
@@ -0,0 +1,46 @@
+###### (This function is part of SDL_ttf, a separate library from SDL.)
+# TTF_GetTextColor
+
+Get the color of a text object.
+
+## Header File
+
+Defined in [<SDL3_ttf/SDL_ttf.h>](https://github.com/libsdl-org/SDL_ttf/blob/main/include/SDL3_ttf/SDL_ttf.h)
+
+## Syntax
+
+```c
+bool TTF_GetTextColor(TTF_Text *text, Uint8 *r, Uint8 *g, Uint8 *b, Uint8 *a);
+```
+
+## Function Parameters
+
+|                        |          |                                                                                    |
+| ---------------------- | -------- | ---------------------------------------------------------------------------------- |
+| [TTF_Text](TTF_Text) * | **text** | the [TTF_Text](TTF_Text) to query.                                                 |
+| Uint8 *                | **r**    | a pointer filled in with the red color value in the range of 0-255, may be NULL.   |
+| Uint8 *                | **g**    | a pointer filled in with the green color value in the range of 0-255, may be NULL. |
+| Uint8 *                | **b**    | a pointer filled in with the blue color value in the range of 0-255, may be NULL.  |
+| Uint8 *                | **a**    | a pointer filled in with the alpha value in the range of 0-255, may be NULL.       |
+
+## Return Value
+
+(bool) Returns true on success or false on failure; call SDL_GetError() for
+more information.
+
+## Thread Safety
+
+This function should be called on the thread that created the text.
+
+## Version
+
+This function is available since SDL_ttf 3.0.0.
+
+## See Also
+
+- [TTF_GetTextColorFloat](TTF_GetTextColorFloat)
+- [TTF_SetTextColor](TTF_SetTextColor)
+
+----
+[CategoryAPI](CategoryAPI), [CategoryAPIFunction](CategoryAPIFunction)
+
diff --git a/SDL3_ttf/TTF_GetTextColorFloat.md b/SDL3_ttf/TTF_GetTextColorFloat.md
@@ -0,0 +1,46 @@
+###### (This function is part of SDL_ttf, a separate library from SDL.)
+# TTF_GetTextColorFloat
+
+Get the color of a text object.
+
+## Header File
+
+Defined in [<SDL3_ttf/SDL_ttf.h>](https://github.com/libsdl-org/SDL_ttf/blob/main/include/SDL3_ttf/SDL_ttf.h)
+
+## Syntax
+
+```c
+bool TTF_GetTextColorFloat(TTF_Text *text, float *r, float *g, float *b, float *a);
+```
+
+## Function Parameters
+
+|                        |          |                                                                                            |
+| ---------------------- | -------- | ------------------------------------------------------------------------------------------ |
+| [TTF_Text](TTF_Text) * | **text** | the [TTF_Text](TTF_Text) to query.                                                         |
+| float *                | **r**    | a pointer filled in with the red color value, normally in the range of 0-1, may be NULL.   |
+| float *                | **g**    | a pointer filled in with the green color value, normally in the range of 0-1, may be NULL. |
+| float *                | **b**    | a pointer filled in with the blue color value, normally in the range of 0-1, may be NULL.  |
+| float *                | **a**    | a pointer filled in with the alpha value in the range of 0-1, may be NULL.                 |
+
+## Return Value
+
+(bool) Returns true on success or false on failure; call SDL_GetError() for
+more information.
+
+## Thread Safety
+
+This function should be called on the thread that created the text.
+
+## Version
+
+This function is available since SDL_ttf 3.0.0.
+
+## See Also
+
+- [TTF_GetTextColor](TTF_GetTextColor)
+- [TTF_SetTextColorFloat](TTF_SetTextColorFloat)
+
+----
+[CategoryAPI](CategoryAPI), [CategoryAPIFunction](CategoryAPIFunction)
+
diff --git a/SDL3_ttf/TTF_GetTextEngine.md b/SDL3_ttf/TTF_GetTextEngine.md
@@ -33,6 +33,10 @@ This function should be called on the thread that created the text.
 
 This function is available since SDL_ttf 3.0.0.
 
+## See Also
+
+- [TTF_SetTextEngine](TTF_SetTextEngine)
+
 ----
 [CategoryAPI](CategoryAPI), [CategoryAPIFunction](CategoryAPIFunction)
 
diff --git a/SDL3_ttf/TTF_GetTextFont.md b/SDL3_ttf/TTF_GetTextFont.md
@@ -32,6 +32,10 @@ This function should be called on the thread that created the text.
 
 This function is available since SDL_ttf 3.0.0.
 
+## See Also
+
+- [TTF_SetTextFont](TTF_SetTextFont)
+
 ----
 [CategoryAPI](CategoryAPI), [CategoryAPIFunction](CategoryAPIFunction)
 
diff --git a/SDL3_ttf/TTF_GetTextPosition.md b/SDL3_ttf/TTF_GetTextPosition.md
@@ -29,6 +29,10 @@ This function should be called on the thread that created the text.
 
 This function is available since SDL_ttf 3.0.0.
 
+## See Also
+
+- [TTF_SetTextPosition](TTF_SetTextPosition)
+
 ----
 [CategoryAPI](CategoryAPI), [CategoryAPIFunction](CategoryAPIFunction)
 
diff --git a/SDL3_ttf/TTF_GetTextWrapping.md b/SDL3_ttf/TTF_GetTextWrapping.md
@@ -33,6 +33,10 @@ This function should be called on the thread that created the text.
 
 This function is available since SDL_ttf 3.0.0.
 
+## See Also
+
+- [TTF_SetTextWrapping](TTF_SetTextWrapping)
+
 ----
 [CategoryAPI](CategoryAPI), [CategoryAPIFunction](CategoryAPIFunction)
 
diff --git a/SDL3_ttf/TTF_InsertTextString.md b/SDL3_ttf/TTF_InsertTextString.md
@@ -35,6 +35,12 @@ This function should be called on the thread that created the text.
 
 This function is available since SDL_ttf 3.0.0.
 
+## See Also
+
+- [TTF_AppendTextString](TTF_AppendTextString)
+- [TTF_DeleteTextString](TTF_DeleteTextString)
+- [TTF_SetTextString](TTF_SetTextString)
+
 ----
 [CategoryAPI](CategoryAPI), [CategoryAPIFunction](CategoryAPIFunction)
 
diff --git a/SDL3_ttf/TTF_SetTextColor.md b/SDL3_ttf/TTF_SetTextColor.md
@@ -0,0 +1,50 @@
+###### (This function is part of SDL_ttf, a separate library from SDL.)
+# TTF_SetTextColor
+
+Set the color of a text object.
+
+## Header File
+
+Defined in [<SDL3_ttf/SDL_ttf.h>](https://github.com/libsdl-org/SDL_ttf/blob/main/include/SDL3_ttf/SDL_ttf.h)
+
+## Syntax
+
+```c
+bool TTF_SetTextColor(TTF_Text *text, Uint8 r, Uint8 g, Uint8 b, Uint8 a);
+```
+
+## Function Parameters
+
+|                        |          |                                              |
+| ---------------------- | -------- | -------------------------------------------- |
+| [TTF_Text](TTF_Text) * | **text** | the [TTF_Text](TTF_Text) to modify.          |
+| Uint8                  | **r**    | the red color value in the range of 0-255.   |
+| Uint8                  | **g**    | the green color value in the range of 0-255. |
+| Uint8                  | **b**    | the blue color value in the range of 0-255.  |
+| Uint8                  | **a**    | the alpha value in the range of 0-255.       |
+
+## Return Value
+
+(bool) Returns true on success or false on failure; call SDL_GetError() for
+more information.
+
+## Remarks
+
+The default text color is white (255, 255, 255, 255).
+
+## Thread Safety
+
+This function should be called on the thread that created the text.
+
+## Version
+
+This function is available since SDL_ttf 3.0.0.
+
+## See Also
+
+- [TTF_GetTextColor](TTF_GetTextColor)
+- [TTF_SetTextColorFloat](TTF_SetTextColorFloat)
+
+----
+[CategoryAPI](CategoryAPI), [CategoryAPIFunction](CategoryAPIFunction)
+
diff --git a/SDL3_ttf/TTF_SetTextColorFloat.md b/SDL3_ttf/TTF_SetTextColorFloat.md
@@ -0,0 +1,50 @@
+###### (This function is part of SDL_ttf, a separate library from SDL.)
+# TTF_SetTextColorFloat
+
+Set the color of a text object.
+
+## Header File
+
+Defined in [<SDL3_ttf/SDL_ttf.h>](https://github.com/libsdl-org/SDL_ttf/blob/main/include/SDL3_ttf/SDL_ttf.h)
+
+## Syntax
+
+```c
+bool TTF_SetTextColorFloat(TTF_Text *text, float r, float g, float b, float a);
+```
+
+## Function Parameters
+
+|                        |          |                                                      |
+| ---------------------- | -------- | ---------------------------------------------------- |
+| [TTF_Text](TTF_Text) * | **text** | the [TTF_Text](TTF_Text) to modify.                  |
+| float                  | **r**    | the red color value, normally in the range of 0-1.   |
+| float                  | **g**    | the green color value, normally in the range of 0-1. |
+| float                  | **b**    | the blue color value, normally in the range of 0-1.  |
+| float                  | **a**    | the alpha value in the range of 0-1.                 |
+
+## Return Value
+
+(bool) Returns true on success or false on failure; call SDL_GetError() for
+more information.
+
+## Remarks
+
+The default text color is white (1.0f, 1.0f, 1.0f, 1.0f).
+
+## Thread Safety
+
+This function should be called on the thread that created the text.
+
+## Version
+
+This function is available since SDL_ttf 3.0.0.
+
+## See Also
+
+- [TTF_GetTextColorFloat](TTF_GetTextColorFloat)
+- [TTF_SetTextColor](TTF_SetTextColor)
+
+----
+[CategoryAPI](CategoryAPI), [CategoryAPIFunction](CategoryAPIFunction)
+
diff --git a/SDL3_ttf/TTF_SetTextEngine.md b/SDL3_ttf/TTF_SetTextEngine.md
@@ -33,6 +33,10 @@ This function should be called on the thread that created the text.
 
 This function is available since SDL_ttf 3.0.0.
 
+## See Also
+
+- [TTF_GetTextEngine](TTF_GetTextEngine)
+
 ----
 [CategoryAPI](CategoryAPI), [CategoryAPIFunction](CategoryAPIFunction)
 
diff --git a/SDL3_ttf/TTF_SetTextFont.md b/SDL3_ttf/TTF_SetTextFont.md
@@ -34,6 +34,10 @@ This function should be called on the thread that created the text.
 
 This function is available since SDL_ttf 3.0.0.
 
+## See Also
+
+- [TTF_GetTextFont](TTF_GetTextFont)
+
 ----
 [CategoryAPI](CategoryAPI), [CategoryAPIFunction](CategoryAPIFunction)
 
diff --git a/SDL3_ttf/TTF_SetTextPosition.md b/SDL3_ttf/TTF_SetTextPosition.md
@@ -34,6 +34,10 @@ This function should be called on the thread that created the text.
 
 This function is available since SDL_ttf 3.0.0.
 
+## See Also
+
+- [TTF_GetTextPosition](TTF_GetTextPosition)
+
 ----
 [CategoryAPI](CategoryAPI), [CategoryAPIFunction](CategoryAPIFunction)
 
diff --git a/SDL3_ttf/TTF_SetTextString.md b/SDL3_ttf/TTF_SetTextString.md
@@ -34,6 +34,12 @@ This function should be called on the thread that created the text.
 
 This function is available since SDL_ttf 3.0.0.
 
+## See Also
+
+- [TTF_AppendTextString](TTF_AppendTextString)
+- [TTF_DeleteTextString](TTF_DeleteTextString)
+- [TTF_InsertTextString](TTF_InsertTextString)
+
 ----
 [CategoryAPI](CategoryAPI), [CategoryAPIFunction](CategoryAPIFunction)
 
diff --git a/SDL3_ttf/TTF_SetTextWrapWhitespaceVisible.md b/SDL3_ttf/TTF_SetTextWrapWhitespaceVisible.md
@@ -0,0 +1,49 @@
+###### (This function is part of SDL_ttf, a separate library from SDL.)
+# TTF_SetTextWrapWhitespaceVisible
+
+Set whether whitespace should be visible when wrapping a text object.
+
+## Header File
+
+Defined in [<SDL3_ttf/SDL_ttf.h>](https://github.com/libsdl-org/SDL_ttf/blob/main/include/SDL3_ttf/SDL_ttf.h)
+
+## Syntax
+
+```c
+bool TTF_SetTextWrapWhitespaceVisible(TTF_Text *text, bool visible);
+```
+
+## Function Parameters
+
+|                        |             |                                                               |
+| ---------------------- | ----------- | ------------------------------------------------------------- |
+| [TTF_Text](TTF_Text) * | **text**    | the [TTF_Text](TTF_Text) to modify.                           |
+| bool                   | **visible** | true to show whitespace when wrapping text, false to hide it. |
+
+## Return Value
+
+(bool) Returns true on success or false on failure; call SDL_GetError() for
+more information.
+
+## Remarks
+
+If the whitespace is visible, it will take up space for purposes of
+alignment and wrapping. This is good for editing, but looks better when
+centered or aligned if whitespace around line wrapping is hidden. This
+defaults false.
+
+## Thread Safety
+
+This function should be called on the thread that created the text.
+
+## Version
+
+This function is available since SDL_ttf 3.0.0.
+
+## See Also
+
+- [TTF_TextWrapWhitespaceVisible](TTF_TextWrapWhitespaceVisible)
+
+----
+[CategoryAPI](CategoryAPI), [CategoryAPIFunction](CategoryAPIFunction)
+
diff --git a/SDL3_ttf/TTF_SetTextWrapping.md b/SDL3_ttf/TTF_SetTextWrapping.md
@@ -33,6 +33,10 @@ This function should be called on the thread that created the text.
 
 This function is available since SDL_ttf 3.0.0.
 
+## See Also
+
+- [TTF_GetTextWrapping](TTF_GetTextWrapping)
+
 ----
 [CategoryAPI](CategoryAPI), [CategoryAPIFunction](CategoryAPIFunction)
 
diff --git a/SDL3_ttf/TTF_Text.md b/SDL3_ttf/TTF_Text.md
@@ -13,7 +13,6 @@ Defined in [<SDL3_ttf/SDL_ttf.h>](https://github.com/libsdl-org/SDL_ttf/blob/mai
 typedef struct TTF_Text
 {
     char *text;             /**< A copy of the text used to create this text object, useful for layout and debugging. This will be freed automatically when the object is destroyed. */
-    SDL_FColor color;       /**< The color of the text, read-write. You can change this anytime. */
     int num_lines;          /**< The number of lines in the text, 0 if it's empty */
 
     int refcount;           /**< Application reference count, used when freeing surface */