clap

commit cd06b330d239ac4307b84e8f4d25a4e8e585f308
parent b128a0cc8821b282748d36dddcee8957161f1091
Author: Alexandre Bique <bique.alexandre@gmail.com>
Date:   Mon, 12 Dec 2022 15:04:42 +0100

context-menu: rework documentation

Diffstat:
M
include/clap/ext/draft/context-menu.h
 | 
32
+++++++++++++++++++++++++-------

1 file changed, 25 insertions(+), 7 deletions(-)
diff --git a/include/clap/ext/draft/context-menu.h b/include/clap/ext/draft/context-menu.h
@@ -15,6 +15,7 @@ extern "C" {
 enum {
    CLAP_CONTEXT_MENU_TARGET_KIND_GLOBAL = 0,
    CLAP_CONTEXT_MENU_TARGET_KIND_PARAM = 1,
+   // TODO: kind trigger once the trigger ext is marked as stable
 };
 
 // Describes the context menu target
@@ -50,14 +51,21 @@ typedef struct clap_context_menu_accelerator {
 typedef struct clap_context_menu_builder {
    void *ctx;
 
-   // accelerator may be null
+   // Adds a clickable menu entry.
+   // label: text to be displayed
+   // accelerator: shortcut which would trigger this action, this field is informational and may be null
+   // is_enable: if false, then the menu entry is greyed out and not clickable
    bool(CLAP_ABI *add_entry)(const struct clap_context_menu_builder *builder,
                              const char                             *label,
                              const clap_context_menu_accelerator_t  *accelerator,
                              bool                                    is_enabled,
                              clap_id                                 action_id);
 
-   // accelerator may be null
+   // Adds a clickable menu entry which will feature both a checkmark and a label.
+   // label: text to be displayed
+   // accelerator: shortcut which would trigger this action, this field is informational and may be null
+   // is_enable: if false, then the menu entry is greyed out and not clickable
+   // is_checked: if true, then the menu entry will be displayed as checked
    bool(CLAP_ABI *add_checkmark)(const struct clap_context_menu_builder *builder,
                                  const char                             *label,
                                  const clap_context_menu_accelerator_t  *accelerator,
@@ -65,23 +73,28 @@ typedef struct clap_context_menu_builder {
                                  bool                                    is_checked,
                                  clap_id                                 action_id);
 
+   // Adds a separator line.
    bool(CLAP_ABI *add_separator)(const struct clap_context_menu_builder *builder);
 
+   // Starts a sub menu with the given label.
    // Each begin_submenu() must have a corresponding end_submenu()
    bool(CLAP_ABI *begin_submenu)(const struct clap_context_menu_builder *builder,
                                  const char                             *label);
 
+   // Ends the current sub menu.
    bool(CLAP_ABI *end_submenu)(const struct clap_context_menu_builder *builder);
 } clap_context_menu_builder_t;
 
 typedef struct clap_plugin_context_menu {
-   // If target is null, assume global context
+   // Insert plugin's menu items into the menu builder.
+   // If target is null, assume global context.
    // [main-thread]
    bool(CLAP_ABI *populate)(const clap_plugin_t               *plugin,
                             const clap_context_menu_target_t  *target,
                             const clap_context_menu_builder_t *builder);
 
-   // If target is null, assume global context
+   // Performs the given action, which was previously provided to the host via populate().
+   // If target is null, assume global context.
    // [main-thread]
    bool(CLAP_ABI *perform)(const clap_plugin_t              *plugin,
                            const clap_context_menu_target_t *target,
@@ -89,25 +102,30 @@ typedef struct clap_plugin_context_menu {
 } clap_plugin_context_menu_t;
 
 typedef struct clap_host_context_menu {
-   // If target is null, assume global context
+   // Insert host's menu items into the menu builder.
+   // If target is null, assume global context.
    // [main-thread]
    bool(CLAP_ABI *populate)(const clap_host_t                 *host,
                             const clap_context_menu_target_t  *target,
                             const clap_context_menu_builder_t *builder);
 
-   // If target is null, assume global context
+   // Performs the given action, which was previously provided to the plugin via populate().
+   // If target is null, assume global context.
    // [main-thread]
    bool(CLAP_ABI *perform)(const clap_host_t                *host,
                            const clap_context_menu_target_t *target,
                            clap_id action_id);
 
+   // Returns true if the host can display a popup menu for the plugin.
+   // This may depends upon the current windowing system used to display the plugin, so the
+   // return value is invalidated after creating the plugin window.
    // [main-thread]
    bool(CLAP_ABI *can_popup)(const clap_host_t *host);
 
    // Shows the host popup menu for a given parameter.
    // If the plugin is using embedded GUI, then x and y are relative to the plugin's window,
    // otherwise they're absolute coordinate, and screen index might be set accordingly.
-   // If target is null, assume global context
+   // If target is null, assume global context.
    // [main-thread]
    bool(CLAP_ABI *popup)(const clap_host_t                *host,
                          const clap_context_menu_target_t *target,