(*---------------------------------------------------------------------------
   Copyright (c) 2025 Anil Madhavapeddy. All rights reserved.
   SPDX-License-Identifier: ISC
  ---------------------------------------------------------------------------*)

(** Cursor Movement Behavior

    Controls cursor position after displaying an image.

    {2 Protocol Details}

    Cursor movement is specified via the [C] key in the control data:
    - [C=0] or no [C] key: move cursor after display (default)
    - [C=1]: keep cursor in place (static)

    This key was added in Kitty 0.20.0.

    {2 Default Behavior}

    By default ([{`Move}]), after displaying an image the cursor advances:
    - Right by the number of columns the image occupies
    - Down by the number of rows the image occupies

    This matches how the cursor moves after printing text, allowing images
    to flow naturally with text content.

    {2 Static Cursor}

    With [{`Static}], the cursor remains at its original position. This is
    useful when:
    - Overlaying images on existing content
    - Positioning multiple images relative to the same starting point
    - Implementing custom cursor management

    {2 Relative Placements}

    Note: When using relative placements (positioning images relative to
    other placements), the cursor never moves regardless of this setting. *)

type t = [ `Move | `Static ]
(** Cursor movement behavior.

    - [`Move] - Advance cursor past the displayed image (default).
      Cursor moves right by the number of columns and down by the
      number of rows occupied by the image.
    - [`Static] - Keep cursor at its original position. The image
      is displayed but cursor position is unchanged. *)

val to_int : t -> int
(** Convert to protocol integer.

    Returns 0 for [`Move] or 1 for [`Static].
    These values are used in the [C=] control data key. *)