mirror of
https://github.com/ghostty-org/ghostty.git
synced 2025-10-09 11:26:41 +00:00
lib-vt: update documentation with more examples
This commit is contained in:
Mitchell Hashimoto
269
DoxygenLayout.xml
Normal file
269
DoxygenLayout.xml
Normal file
@@ -0,0 +1,269 @@
|
|||||||
|
<?xml version="1.0" encoding="UTF-8"?>
|
||||||
|
<doxygenlayout version="2.0">
|
||||||
|
<!-- Generated by doxygen 1.14.0 -->
|
||||||
|
<!-- Navigation index tabs for HTML output -->
|
||||||
|
<navindex>
|
||||||
|
<tab type="mainpage" visible="yes" title=""/>
|
||||||
|
<tab type="pages" visible="yes" title="" intro=""/>
|
||||||
|
<tab type="topics" visible="yes" title="" intro=""/>
|
||||||
|
<tab type="modules" visible="yes" title="" intro="">
|
||||||
|
<tab type="modulelist" visible="yes" title="" intro=""/>
|
||||||
|
<tab type="modulemembers" visible="yes" title="" intro=""/>
|
||||||
|
</tab>
|
||||||
|
<tab type="namespaces" visible="yes" title="">
|
||||||
|
<tab type="namespacelist" visible="yes" title="" intro=""/>
|
||||||
|
<tab type="namespacemembers" visible="yes" title="" intro=""/>
|
||||||
|
</tab>
|
||||||
|
<tab type="concepts" visible="yes" title="">
|
||||||
|
</tab>
|
||||||
|
<tab type="interfaces" visible="yes" title="">
|
||||||
|
<tab type="interfacelist" visible="yes" title="" intro=""/>
|
||||||
|
<tab type="interfaceindex" visible="$ALPHABETICAL_INDEX" title=""/>
|
||||||
|
<tab type="interfacehierarchy" visible="yes" title="" intro=""/>
|
||||||
|
</tab>
|
||||||
|
<tab type="classes" visible="yes" title="">
|
||||||
|
<tab type="classlist" visible="yes" title="" intro=""/>
|
||||||
|
<tab type="classindex" visible="$ALPHABETICAL_INDEX" title=""/>
|
||||||
|
<tab type="hierarchy" visible="yes" title="" intro=""/>
|
||||||
|
<tab type="classmembers" visible="yes" title="" intro=""/>
|
||||||
|
</tab>
|
||||||
|
<tab type="structs" visible="yes" title="">
|
||||||
|
<tab type="structlist" visible="yes" title="" intro=""/>
|
||||||
|
<tab type="structindex" visible="$ALPHABETICAL_INDEX" title=""/>
|
||||||
|
</tab>
|
||||||
|
<tab type="exceptions" visible="yes" title="">
|
||||||
|
<tab type="exceptionlist" visible="yes" title="" intro=""/>
|
||||||
|
<tab type="exceptionindex" visible="$ALPHABETICAL_INDEX" title=""/>
|
||||||
|
<tab type="exceptionhierarchy" visible="yes" title="" intro=""/>
|
||||||
|
</tab>
|
||||||
|
<tab type="files" visible="yes" title="">
|
||||||
|
<tab type="filelist" visible="yes" title="" intro=""/>
|
||||||
|
<tab type="globals" visible="yes" title="" intro=""/>
|
||||||
|
</tab>
|
||||||
|
<tab type="examples" visible="yes" title="" intro=""/>
|
||||||
|
</navindex>
|
||||||
|
|
||||||
|
<!-- Layout definition for a class page -->
|
||||||
|
<class>
|
||||||
|
<briefdescription visible="yes"/>
|
||||||
|
<includes visible="$SHOW_HEADERFILE"/>
|
||||||
|
<inheritancegraph visible="yes"/>
|
||||||
|
<collaborationgraph visible="yes"/>
|
||||||
|
<memberdecl>
|
||||||
|
<nestedclasses visible="yes" title=""/>
|
||||||
|
<publictypes visible="yes" title=""/>
|
||||||
|
<services visible="yes" title=""/>
|
||||||
|
<interfaces visible="yes" title=""/>
|
||||||
|
<publicslots visible="yes" title=""/>
|
||||||
|
<signals visible="yes" title=""/>
|
||||||
|
<publicmethods visible="yes" title=""/>
|
||||||
|
<publicstaticmethods visible="yes" title=""/>
|
||||||
|
<publicattributes visible="yes" title=""/>
|
||||||
|
<publicstaticattributes visible="yes" title=""/>
|
||||||
|
<protectedtypes visible="yes" title=""/>
|
||||||
|
<protectedslots visible="yes" title=""/>
|
||||||
|
<protectedmethods visible="yes" title=""/>
|
||||||
|
<protectedstaticmethods visible="yes" title=""/>
|
||||||
|
<protectedattributes visible="yes" title=""/>
|
||||||
|
<protectedstaticattributes visible="yes" title=""/>
|
||||||
|
<packagetypes visible="yes" title=""/>
|
||||||
|
<packagemethods visible="yes" title=""/>
|
||||||
|
<packagestaticmethods visible="yes" title=""/>
|
||||||
|
<packageattributes visible="yes" title=""/>
|
||||||
|
<packagestaticattributes visible="yes" title=""/>
|
||||||
|
<properties visible="yes" title=""/>
|
||||||
|
<events visible="yes" title=""/>
|
||||||
|
<privatetypes visible="yes" title=""/>
|
||||||
|
<privateslots visible="yes" title=""/>
|
||||||
|
<privatemethods visible="yes" title=""/>
|
||||||
|
<privatestaticmethods visible="yes" title=""/>
|
||||||
|
<privateattributes visible="yes" title=""/>
|
||||||
|
<privatestaticattributes visible="yes" title=""/>
|
||||||
|
<friends visible="yes" title=""/>
|
||||||
|
<related visible="yes" title="" subtitle=""/>
|
||||||
|
<membergroups visible="yes"/>
|
||||||
|
</memberdecl>
|
||||||
|
<detaileddescription visible="yes" title=""/>
|
||||||
|
<memberdef>
|
||||||
|
<inlineclasses visible="yes" title=""/>
|
||||||
|
<typedefs visible="yes" title=""/>
|
||||||
|
<enums visible="yes" title=""/>
|
||||||
|
<services visible="yes" title=""/>
|
||||||
|
<interfaces visible="yes" title=""/>
|
||||||
|
<constructors visible="yes" title=""/>
|
||||||
|
<functions visible="yes" title=""/>
|
||||||
|
<related visible="yes" title=""/>
|
||||||
|
<variables visible="yes" title=""/>
|
||||||
|
<properties visible="yes" title=""/>
|
||||||
|
<events visible="yes" title=""/>
|
||||||
|
</memberdef>
|
||||||
|
<allmemberslink visible="yes"/>
|
||||||
|
<usedfiles visible="$SHOW_USED_FILES"/>
|
||||||
|
<authorsection visible="yes"/>
|
||||||
|
</class>
|
||||||
|
|
||||||
|
<!-- Layout definition for a namespace page -->
|
||||||
|
<namespace>
|
||||||
|
<briefdescription visible="yes"/>
|
||||||
|
<memberdecl>
|
||||||
|
<nestednamespaces visible="yes" title=""/>
|
||||||
|
<constantgroups visible="yes" title=""/>
|
||||||
|
<interfaces visible="yes" title=""/>
|
||||||
|
<classes visible="yes" title=""/>
|
||||||
|
<concepts visible="yes" title=""/>
|
||||||
|
<structs visible="yes" title=""/>
|
||||||
|
<exceptions visible="yes" title=""/>
|
||||||
|
<typedefs visible="yes" title=""/>
|
||||||
|
<sequences visible="yes" title=""/>
|
||||||
|
<dictionaries visible="yes" title=""/>
|
||||||
|
<enums visible="yes" title=""/>
|
||||||
|
<functions visible="yes" title=""/>
|
||||||
|
<variables visible="yes" title=""/>
|
||||||
|
<properties visible="yes" title=""/>
|
||||||
|
<membergroups visible="yes"/>
|
||||||
|
</memberdecl>
|
||||||
|
<detaileddescription visible="yes" title=""/>
|
||||||
|
<memberdef>
|
||||||
|
<inlineclasses visible="yes" title=""/>
|
||||||
|
<typedefs visible="yes" title=""/>
|
||||||
|
<sequences visible="yes" title=""/>
|
||||||
|
<dictionaries visible="yes" title=""/>
|
||||||
|
<enums visible="yes" title=""/>
|
||||||
|
<functions visible="yes" title=""/>
|
||||||
|
<variables visible="yes" title=""/>
|
||||||
|
<properties visible="yes" title=""/>
|
||||||
|
</memberdef>
|
||||||
|
<authorsection visible="yes"/>
|
||||||
|
</namespace>
|
||||||
|
|
||||||
|
<!-- Layout definition for a concept page -->
|
||||||
|
<concept>
|
||||||
|
<briefdescription visible="yes"/>
|
||||||
|
<includes visible="$SHOW_HEADERFILE"/>
|
||||||
|
<definition visible="yes" title=""/>
|
||||||
|
<detaileddescription visible="yes" title=""/>
|
||||||
|
<authorsection visible="yes"/>
|
||||||
|
</concept>
|
||||||
|
|
||||||
|
<!-- Layout definition for a file page -->
|
||||||
|
<file>
|
||||||
|
<briefdescription visible="yes"/>
|
||||||
|
<includes visible="$SHOW_INCLUDE_FILES"/>
|
||||||
|
<includegraph visible="yes"/>
|
||||||
|
<includedbygraph visible="yes"/>
|
||||||
|
<sourcelink visible="yes"/>
|
||||||
|
<memberdecl>
|
||||||
|
<interfaces visible="yes" title=""/>
|
||||||
|
<classes visible="yes" title=""/>
|
||||||
|
<structs visible="yes" title=""/>
|
||||||
|
<exceptions visible="yes" title=""/>
|
||||||
|
<namespaces visible="yes" title=""/>
|
||||||
|
<concepts visible="yes" title=""/>
|
||||||
|
<constantgroups visible="yes" title=""/>
|
||||||
|
<defines visible="yes" title=""/>
|
||||||
|
<typedefs visible="yes" title=""/>
|
||||||
|
<sequences visible="yes" title=""/>
|
||||||
|
<dictionaries visible="yes" title=""/>
|
||||||
|
<enums visible="yes" title=""/>
|
||||||
|
<functions visible="yes" title=""/>
|
||||||
|
<variables visible="yes" title=""/>
|
||||||
|
<properties visible="yes" title=""/>
|
||||||
|
<membergroups visible="yes"/>
|
||||||
|
</memberdecl>
|
||||||
|
<detaileddescription visible="yes" title=""/>
|
||||||
|
<memberdef>
|
||||||
|
<inlineclasses visible="yes" title=""/>
|
||||||
|
<defines visible="yes" title=""/>
|
||||||
|
<typedefs visible="yes" title=""/>
|
||||||
|
<sequences visible="yes" title=""/>
|
||||||
|
<dictionaries visible="yes" title=""/>
|
||||||
|
<enums visible="yes" title=""/>
|
||||||
|
<functions visible="yes" title=""/>
|
||||||
|
<variables visible="yes" title=""/>
|
||||||
|
<properties visible="yes" title=""/>
|
||||||
|
</memberdef>
|
||||||
|
<authorsection/>
|
||||||
|
</file>
|
||||||
|
|
||||||
|
<!-- Layout definition for a group page -->
|
||||||
|
<group>
|
||||||
|
<briefdescription visible="yes"/>
|
||||||
|
<detaileddescription visible="yes" title=""/>
|
||||||
|
<memberdecl>
|
||||||
|
<nestedgroups visible="yes" title=""/>
|
||||||
|
<typedefs visible="yes" title=""/>
|
||||||
|
<enums visible="yes" title=""/>
|
||||||
|
<enumvalues visible="no" title=""/>
|
||||||
|
<functions visible="yes" title=""/>
|
||||||
|
<variables visible="yes" title=""/>
|
||||||
|
<defines visible="yes" title=""/>
|
||||||
|
<modules visible="yes" title=""/>
|
||||||
|
<dirs visible="yes" title=""/>
|
||||||
|
<files visible="yes" title=""/>
|
||||||
|
<namespaces visible="yes" title=""/>
|
||||||
|
<concepts visible="yes" title=""/>
|
||||||
|
<classes visible="yes" title=""/>
|
||||||
|
<sequences visible="yes" title=""/>
|
||||||
|
<dictionaries visible="yes" title=""/>
|
||||||
|
<signals visible="yes" title=""/>
|
||||||
|
<publicslots visible="yes" title=""/>
|
||||||
|
<protectedslots visible="yes" title=""/>
|
||||||
|
<privateslots visible="yes" title=""/>
|
||||||
|
<events visible="yes" title=""/>
|
||||||
|
<properties visible="yes" title=""/>
|
||||||
|
<friends visible="yes" title=""/>
|
||||||
|
<membergroups visible="yes"/>
|
||||||
|
</memberdecl>
|
||||||
|
<memberdef>
|
||||||
|
<pagedocs/>
|
||||||
|
<inlineclasses visible="yes" title=""/>
|
||||||
|
<typedefs visible="yes" title=""/>
|
||||||
|
<enums visible="yes" title=""/>
|
||||||
|
<enumvalues visible="yes" title=""/>
|
||||||
|
<functions visible="yes" title=""/>
|
||||||
|
<variables visible="yes" title=""/>
|
||||||
|
<defines visible="yes" title=""/>
|
||||||
|
<sequences visible="yes" title=""/>
|
||||||
|
<dictionaries visible="yes" title=""/>
|
||||||
|
<signals visible="yes" title=""/>
|
||||||
|
<publicslots visible="yes" title=""/>
|
||||||
|
<protectedslots visible="yes" title=""/>
|
||||||
|
<privateslots visible="yes" title=""/>
|
||||||
|
<events visible="yes" title=""/>
|
||||||
|
<properties visible="yes" title=""/>
|
||||||
|
<friends visible="yes" title=""/>
|
||||||
|
</memberdef>
|
||||||
|
<groupgraph visible="yes"/>
|
||||||
|
<authorsection visible="yes"/>
|
||||||
|
</group>
|
||||||
|
|
||||||
|
<!-- Layout definition for a C++20 module page -->
|
||||||
|
<module>
|
||||||
|
<briefdescription visible="yes"/>
|
||||||
|
<exportedmodules visible="yes"/>
|
||||||
|
<memberdecl>
|
||||||
|
<concepts visible="yes" title=""/>
|
||||||
|
<classes visible="yes" title=""/>
|
||||||
|
<enums visible="yes" title=""/>
|
||||||
|
<typedefs visible="yes" title=""/>
|
||||||
|
<functions visible="yes" title=""/>
|
||||||
|
<variables visible="yes" title=""/>
|
||||||
|
<membergroups visible="yes" title=""/>
|
||||||
|
</memberdecl>
|
||||||
|
<detaileddescription visible="yes" title=""/>
|
||||||
|
<memberdecl>
|
||||||
|
<files visible="yes"/>
|
||||||
|
</memberdecl>
|
||||||
|
</module>
|
||||||
|
|
||||||
|
<!-- Layout definition for a directory page -->
|
||||||
|
<directory>
|
||||||
|
<briefdescription visible="yes"/>
|
||||||
|
<directorygraph visible="yes"/>
|
||||||
|
<memberdecl>
|
||||||
|
<dirs visible="yes"/>
|
||||||
|
<files visible="yes"/>
|
||||||
|
</memberdecl>
|
||||||
|
<detaileddescription visible="yes" title=""/>
|
||||||
|
</directory>
|
||||||
|
</doxygenlayout>
|
||||||
@@ -327,6 +327,63 @@ typedef struct {
|
|||||||
* Utilities for encoding key events into terminal escape sequences,
|
* Utilities for encoding key events into terminal escape sequences,
|
||||||
* supporting both legacy encoding as well as Kitty Keyboard Protocol.
|
* supporting both legacy encoding as well as Kitty Keyboard Protocol.
|
||||||
*
|
*
|
||||||
|
* ## Basic Usage
|
||||||
|
*
|
||||||
|
* 1. Create an encoder instance with ghostty_key_encoder_new()
|
||||||
|
* 2. Configure encoder options with ghostty_key_encoder_setopt().
|
||||||
|
* 3. For each key event:
|
||||||
|
* - Create a key event with ghostty_key_event_new()
|
||||||
|
* - Set event properties (action, key, modifiers, etc.)
|
||||||
|
* - Encode with ghostty_key_encoder_encode()
|
||||||
|
* - Free the event with ghostty_key_event_free()
|
||||||
|
* - Note: You can also reuse the same key event multiple times by
|
||||||
|
* changing its properties.
|
||||||
|
* 4. Free the encoder with ghostty_key_encoder_free() when done
|
||||||
|
*
|
||||||
|
* ## Example
|
||||||
|
*
|
||||||
|
* @code{.c}
|
||||||
|
* #include <assert.h>
|
||||||
|
* #include <stdio.h>
|
||||||
|
* #include <ghostty/vt.h>
|
||||||
|
*
|
||||||
|
* int main() {
|
||||||
|
* // Create encoder
|
||||||
|
* GhosttyKeyEncoder encoder;
|
||||||
|
* GhosttyResult result = ghostty_key_encoder_new(NULL, &encoder);
|
||||||
|
* assert(result == GHOSTTY_SUCCESS);
|
||||||
|
*
|
||||||
|
* // Enable Kitty keyboard protocol with all features
|
||||||
|
* ghostty_key_encoder_setopt(encoder, GHOSTTY_KEY_ENCODER_OPT_KITTY_FLAGS,
|
||||||
|
* &(uint8_t){GHOSTTY_KITTY_KEY_ALL});
|
||||||
|
*
|
||||||
|
* // Create and configure key event for Ctrl+C press
|
||||||
|
* GhosttyKeyEvent event;
|
||||||
|
* result = ghostty_key_event_new(NULL, &event);
|
||||||
|
* assert(result == GHOSTTY_SUCCESS);
|
||||||
|
* ghostty_key_event_set_action(event, GHOSTTY_KEY_ACTION_PRESS);
|
||||||
|
* ghostty_key_event_set_key(event, GHOSTTY_KEY_C);
|
||||||
|
* ghostty_key_event_set_mods(event, GHOSTTY_MODS_CTRL);
|
||||||
|
*
|
||||||
|
* // Encode the key event
|
||||||
|
* char buf[128];
|
||||||
|
* size_t written = 0;
|
||||||
|
* result = ghostty_key_encoder_encode(encoder, event, buf, sizeof(buf), &written);
|
||||||
|
* assert(result == GHOSTTY_SUCCESS);
|
||||||
|
*
|
||||||
|
* // Use the encoded sequence (e.g., write to terminal)
|
||||||
|
* fwrite(buf, 1, written, stdout);
|
||||||
|
*
|
||||||
|
* // Cleanup
|
||||||
|
* ghostty_key_event_free(event);
|
||||||
|
* ghostty_key_encoder_free(encoder);
|
||||||
|
* return 0;
|
||||||
|
* }
|
||||||
|
* @endcode
|
||||||
|
*
|
||||||
|
* For a complete working example, see example/c-vt-key-encode in the
|
||||||
|
* repository.
|
||||||
|
*
|
||||||
* @{
|
* @{
|
||||||
*/
|
*/
|
||||||
|
|
||||||
@@ -949,6 +1006,48 @@ void ghostty_key_encoder_setopt(GhosttyKeyEncoder encoder, GhosttyKeyEncoderOpti
|
|||||||
* @param out_len Pointer to store the number of bytes written (may be NULL)
|
* @param out_len Pointer to store the number of bytes written (may be NULL)
|
||||||
* @return GHOSTTY_SUCCESS on success, GHOSTTY_OUT_OF_MEMORY if buffer too small, or other error code
|
* @return GHOSTTY_SUCCESS on success, GHOSTTY_OUT_OF_MEMORY if buffer too small, or other error code
|
||||||
*
|
*
|
||||||
|
* ## Example: Calculate required buffer size
|
||||||
|
*
|
||||||
|
* @code{.c}
|
||||||
|
* // Query the required size with a NULL buffer (always returns OUT_OF_MEMORY)
|
||||||
|
* size_t required = 0;
|
||||||
|
* GhosttyResult result = ghostty_key_encoder_encode(encoder, event, NULL, 0, &required);
|
||||||
|
* assert(result == GHOSTTY_OUT_OF_MEMORY);
|
||||||
|
*
|
||||||
|
* // Allocate buffer of required size
|
||||||
|
* char *buf = malloc(required);
|
||||||
|
*
|
||||||
|
* // Encode with properly sized buffer
|
||||||
|
* size_t written = 0;
|
||||||
|
* result = ghostty_key_encoder_encode(encoder, event, buf, required, &written);
|
||||||
|
* assert(result == GHOSTTY_SUCCESS);
|
||||||
|
*
|
||||||
|
* // Use the encoded sequence...
|
||||||
|
*
|
||||||
|
* free(buf);
|
||||||
|
* @endcode
|
||||||
|
*
|
||||||
|
* ## Example: Direct encoding with static buffer
|
||||||
|
*
|
||||||
|
* @code{.c}
|
||||||
|
* // Most escape sequences are short, so a static buffer often suffices
|
||||||
|
* char buf[128];
|
||||||
|
* size_t written = 0;
|
||||||
|
* GhosttyResult result = ghostty_key_encoder_encode(encoder, event, buf, sizeof(buf), &written);
|
||||||
|
*
|
||||||
|
* if (result == GHOSTTY_SUCCESS) {
|
||||||
|
* // Write the encoded sequence to the terminal
|
||||||
|
* write(pty_fd, buf, written);
|
||||||
|
* } else if (result == GHOSTTY_OUT_OF_MEMORY) {
|
||||||
|
* // Buffer too small, written contains required size
|
||||||
|
* char *dynamic_buf = malloc(written);
|
||||||
|
* result = ghostty_key_encoder_encode(encoder, event, dynamic_buf, written, &written);
|
||||||
|
* assert(result == GHOSTTY_SUCCESS);
|
||||||
|
* write(pty_fd, dynamic_buf, written);
|
||||||
|
* free(dynamic_buf);
|
||||||
|
* }
|
||||||
|
* @endcode
|
||||||
|
*
|
||||||
* @ingroup key
|
* @ingroup key
|
||||||
*/
|
*/
|
||||||
GhosttyResult ghostty_key_encoder_encode(GhosttyKeyEncoder encoder, GhosttyKeyEvent event, char *out_buf, size_t out_buf_size, size_t *out_len);
|
GhosttyResult ghostty_key_encoder_encode(GhosttyKeyEncoder encoder, GhosttyKeyEvent event, char *out_buf, size_t out_buf_size, size_t *out_len);
|
||||||
|
|||||||
Reference in New Issue
Block a user