Cleanup cursor_trail threshold option name and documentation

kitty/cursor_trail.c

@@ -52,10 +52,10 @@ should_skip_cursor_trail_update(CursorTrail *ct, Window *w, OSWindow *os_window)
         return true;
     }
 
-    if (OPT(cursor_trail_distance_threshold) > 0 && !ct->needs_render) {
+    if (OPT(cursor_trail_start_threshold) > 0 && !ct->needs_render) {
         int dx = (int)round((ct->corner_x[0] - EDGE(x, 1)) / WD.dx);
         int dy = (int)round((ct->corner_y[0] - EDGE(y, 0)) / WD.dy);
-        if (abs(dx) + abs(dy) <= OPT(cursor_trail_distance_threshold)) {
+        if (abs(dx) + abs(dy) <= OPT(cursor_trail_start_threshold)) {
             return true;
         }
     }

kitty/options/definition.py

@@ -361,7 +361,8 @@ controls when the animation is trigerred. It is a number of milliseconds. The
 trail animation only follows cursors that have stayed in their position for longer
 than the specified number of milliseconds. This prevents trails from appearing
 for cursors that rapidly change their positions during UI updates in complex applications.
-See :opt:`cursor_trail_decay` to control the animation speed.
+See :opt:`cursor_trail_decay` to control the animation speed and :opt:`cursor_trail_start_threshold`
+to control when a cursor trail is started.
 '''
     )
 
@@ -379,13 +380,13 @@ Adjust these values to control how quickly the cursor trail fades away.
 ''',
     )
 
-opt('cursor_trail_distance_threshold', '2',
+opt('cursor_trail_start_threshold', '2',
     option_type='positive_int', ctype='int',
     long_text='''
-Set the distance threshold for updating the cursor trail. This option accepts a
+Set the distance threshold for starting the cursor trail. This option accepts a
-positive integer value that represents the minimum distance (in cell units) the
+positive integer value that represents the minimum number of cells the
-cursor must move before the trail is updated. When the cursor moves less than
+cursor must move before the trail is started. When the cursor moves less than
-this threshold, the trail update is skipped, reducing unnecessary cursor trail
+this threshold, the trail is skipped, reducing unnecessary cursor trail
 animation.
 '''
     )

kitty/options/parse.py

@@ -937,8 +937,8 @@ class Parser:
     def cursor_trail_decay(self, val: str, ans: typing.Dict[str, typing.Any]) -> None:
         ans['cursor_trail_decay'] = cursor_trail_decay(val)
 
-    def cursor_trail_distance_threshold(self, val: str, ans: typing.Dict[str, typing.Any]) -> None:
+    def cursor_trail_start_threshold(self, val: str, ans: typing.Dict[str, typing.Any]) -> None:
-        ans['cursor_trail_distance_threshold'] = positive_int(val)
+        ans['cursor_trail_start_threshold'] = positive_int(val)
 
     def cursor_underline_thickness(self, val: str, ans: typing.Dict[str, typing.Any]) -> None:
         ans['cursor_underline_thickness'] = positive_float(val)

kitty/options/to-c-generated.h

@@ -188,15 +188,15 @@ convert_from_opts_cursor_trail_decay(PyObject *py_opts, Options *opts) {
 }
 
 static void
-convert_from_python_cursor_trail_distance_threshold(PyObject *val, Options *opts) {
+convert_from_python_cursor_trail_start_threshold(PyObject *val, Options *opts) {
-    opts->cursor_trail_distance_threshold = PyLong_AsLong(val);
+    opts->cursor_trail_start_threshold = PyLong_AsLong(val);
 }
 
 static void
-convert_from_opts_cursor_trail_distance_threshold(PyObject *py_opts, Options *opts) {
+convert_from_opts_cursor_trail_start_threshold(PyObject *py_opts, Options *opts) {
-    PyObject *ret = PyObject_GetAttrString(py_opts, "cursor_trail_distance_threshold");
+    PyObject *ret = PyObject_GetAttrString(py_opts, "cursor_trail_start_threshold");
     if (ret == NULL) return;
-    convert_from_python_cursor_trail_distance_threshold(ret, opts);
+    convert_from_python_cursor_trail_start_threshold(ret, opts);
     Py_DECREF(ret);
 }
 
@@ -1166,7 +1166,7 @@ convert_opts_from_python_opts(PyObject *py_opts, Options *opts) {
     if (PyErr_Occurred()) return false;
     convert_from_opts_cursor_trail_decay(py_opts, opts);
     if (PyErr_Occurred()) return false;
-    convert_from_opts_cursor_trail_distance_threshold(py_opts, opts);
+    convert_from_opts_cursor_trail_start_threshold(py_opts, opts);
     if (PyErr_Occurred()) return false;
     convert_from_opts_scrollback_indicator_opacity(py_opts, opts);
     if (PyErr_Occurred()) return false;

kitty/options/types.py

@@ -336,7 +336,7 @@ option_names = (  # {{{
  'cursor_text_color',
  'cursor_trail',
  'cursor_trail_decay',
- 'cursor_trail_distance_threshold',
+ 'cursor_trail_start_threshold',
  'cursor_underline_thickness',
  'default_pointer_shape',
  'detect_urls',
@@ -515,7 +515,7 @@ class Options:
     cursor_text_color: typing.Optional[kitty.fast_data_types.Color] = Color(17, 17, 17)
     cursor_trail: int = 0
     cursor_trail_decay: typing.Tuple[float, float] = (0.1, 0.4)
-    cursor_trail_distance_threshold: int = 2
+    cursor_trail_start_threshold: int = 2
     cursor_underline_thickness: float = 2.0
     default_pointer_shape: choices_for_default_pointer_shape = 'beam'
     detect_urls: bool = True

kitty/state.h

@@ -49,7 +49,7 @@ typedef struct {
     monotonic_t cursor_trail;
     float cursor_trail_decay_fast;
     float cursor_trail_decay_slow;
-    float cursor_trail_distance_threshold;
+    float cursor_trail_start_threshold;
     unsigned int url_style;
     unsigned int scrollback_pager_history_size;
     bool scrollback_fill_enlarged_window;