diff --git a/README.md b/README.md index f4179fc..4c05080 100644 --- a/README.md +++ b/README.md @@ -54,7 +54,8 @@ - [tp-search](#tp-search---search-all-matches) - [tp-search-map](#tp-search-map---apply-function-to-matched-text) - [The Property Layer System](#the-property-layer-system) - - [Custom Text Properties vs Text Property Layers](#custom-text-properties-vs-text-property-layers) + - [Custom Text Properties](#custom-text-properties) + - [Text Property Layers](#text-property-layers) - [Property Layer Concept](#property-layer-concept) - [Property Layer Definition](#property-layer-definition) - [define-tp / define-tps](#define-tp--define-tps---define-custom-text-properties) @@ -1345,26 +1346,70 @@ Apply FUNCTION to all matches of PROPERTY in OBJECT. The **property layer system** is tp.el's innovative feature that allows stacking multiple sets of properties on the same text region. Only the **top layer** is visible, but lower layers are preserved and can be revealed through rotation or pinning. -### Custom Text Properties vs Text Property Layers +### Custom Text Properties -tp.el unifies the concepts of "custom text properties" and "text property layers": +Custom text properties is a **general-purpose feature** provided by tp.el. After defining with `define-tp`, they can be set using core functions like `tp-set`/`tp-reset`/`tp-add`. -#### Concept Distinction +#### Core Features -1. **Custom Text Properties**: Defined using `define-tp`, when set using `tp-set`/`tp-reset`/`tp-add`, they are treated as regular text properties that can be mixed with built-in Emacs text properties (like `face`, `display`, etc.). +1. **Mixed Use with Built-in Properties**: Custom text properties can be seamlessly mixed with built-in Emacs text properties (such as `face`, `display`, `help-echo`, etc.). -2. **Text Property Layers**: Also defined using `define-tp`, but when set using `tp-put-layer`/`tp-push-layer`, layer-related properties are introduced (`tp-name`, `tp-layers`), enabling layer stacking and operations. - -3. **Custom Text Property Groups**: Defined using `define-tps`, they contain multiple related text properties that can be used individually or as a group. - -#### Definition and Usage +2. **Automatic Merging of Duplicate Properties**: In a single setting operation, if the same property (e.g., `face`) is specified multiple times, they are automatically merged rather than simply overwritten. ```elisp -;; Define custom text property (layer) +;; Define a custom text property (define-tp tp-highlight () '(face (:background "yellow"))) -;; Use as regular text property (no tp-name or layer attributes) +;; Mixed use with built-in properties +(tp-set 1 10 '(tp-highlight t face bold help-echo "tip")) +;; Result: Has tp-highlight's background color, bold style, and help-echo property + +;; Automatic merging of duplicate properties example +(tp-set "emacs" + 'face 'bold + 'face '(:background "green") + 'face '(:foreground "red")) +;; Result: face is ((:background "green" :foreground "red") bold) +;; Three face properties are intelligently merged + +;; Later values override earlier ones for the same sub-property +(tp-set "emacs" + 'face '(:foreground "red") + 'face '(:foreground "yellow")) +;; Result: foreground is "yellow" + +;; Use with tp-palette layer +(tp-set "emacs" + 'tp-palette 'info + 'face '(:foreground "red")) +;; Result: tp-palette's face is merged with (:foreground "red") +``` + +#### Custom Text Property Groups + +Using `define-tps`, you can define multiple related text property groups that can be used individually or as a group. + +--- + +### Text Property Layers + +Text property layers is a **unique feature** of tp.el that requires specific functions (`tp-put-layer`/`tp-push-layer`) to set and use. + +#### Core Features + +1. **Layer-Related Properties**: When set using `tp-push-layer`/`tp-put-layer`, layer-related properties (`tp-name`, `tp-layers`) are automatically introduced to support layer stacking and operations. + +2. **Layer Stacking Mechanism**: Multiple sets of properties can be stacked on the same text region, with only the top layer visible while lower layers are preserved. + +3. **Rich Layer Operations**: Supports various layer operations such as rotation, deletion, merging, etc. + +```elisp +;; Define a text property (can be used as custom property or layer) +(define-tp tp-highlight () + '(face (:background "yellow"))) + +;; Use as regular custom text property (no layer properties) (tp-set 1 10 '(tp-highlight t)) ;; Result: Only face property, no tp-name @@ -1375,9 +1420,12 @@ tp.el unifies the concepts of "custom text properties" and "text property layers #### When to Use Which -- **`tp-set`/`tp-reset`/`tp-add`**: When you only need to set text properties without layer stacking functionality. Suitable for simple property setting scenarios. - -- **`tp-push-layer`/`tp-put-layer`**: When you need to stack multiple sets of properties on the same text region and perform layer operations like rotation, deletion, etc. +| Scenario | Recommended Method | Description | +|----------|-------------------|-------------| +| Simple property setting | `tp-set`/`tp-reset`/`tp-add` | When you only need to set text properties without layer stacking | +| Mixed with built-in properties | `tp-set`/`tp-reset`/`tp-add` | Custom properties can be seamlessly mixed with built-in properties | +| Need layer stacking | `tp-push-layer`/`tp-put-layer` | When you need to stack multiple sets of properties on the same text region | +| Need layer operations | `tp-push-layer`/`tp-put-layer` | When you need to perform rotation, deletion, and other layer operations | ### Property Layer Concept diff --git a/README_CN.md b/README_CN.md index a40c2f2..9d22f04 100644 --- a/README_CN.md +++ b/README_CN.md @@ -53,7 +53,8 @@ - [tp-search](#tp-search---搜索所有匹配) - [tp-search-map](#tp-search-map---对匹配文本应用函数) - [属性层系统](#属性层系统) - - [自定义文本属性与文本属性层](#自定义文本属性与文本属性层) + - [自定义文本属性](#自定义文本属性) + - [文本属性层](#文本属性层) - [属性层概念](#属性层概念) - [属性层定义](#属性层定义) - [define-tp / define-tps](#define-tp--define-tps---定义自定义文本属性) @@ -1339,26 +1340,70 @@ Emacs 的 `text-property-search-forward` 和 `text-property-search-backward` 的 属性层系统是 tp.el 的创新功能,允许在同一文本区域堆叠多组属性。只有顶层属性可见,但下层属性会被保留,并可通过轮转或固定操作使其显现。 -### 自定义文本属性与文本属性层 +### 自定义文本属性 -tp.el 统一了"自定义文本属性"和"文本属性层"两个概念: +自定义文本属性是 tp.el 提供的一个**通用功能**。使用 `define-tp` 定义后,可以通过 `tp-set`/`tp-reset`/`tp-add` 等核心函数设置。 -#### 概念辨析 +#### 核心特性 -1. **自定义文本属性**:使用 `define-tp` 定义的文本属性,当使用 `tp-set`/`tp-reset`/`tp-add` 设置时,被认为是普通文本属性,可以和 Emacs 内置的文本属性(如 `face`、`display` 等)混合使用。 +1. **与内置属性混合使用**:自定义文本属性可以和 Emacs 内置的文本属性(如 `face`、`display`、`help-echo` 等)无缝混合使用。 -2. **文本属性层**:同样使用 `define-tp` 定义,但当使用 `tp-put-layer`/`tp-push-layer` 设置时,会引入层相关的属性(如 `tp-name`、`tp-layers`),支持层的堆叠和操作。 - -3. **自定义文本属性组**:使用 `define-tps` 定义多个相关的文本属性,它们可以单独使用,也可以作为一组使用。 - -#### 定义与使用 +2. **重复属性自动合并**:在一次设置操作中,如果同一个属性(如 `face`)被指定多次,它们会自动合并,而非简单覆盖。 ```elisp -;; 定义自定义文本属性(层) +;; 定义自定义文本属性 (define-tp tp-highlight () '(face (:background "yellow"))) -;; 作为普通文本属性使用(不引入 tp-name 等层属性) +;; 与内置属性混合使用 +(tp-set 1 10 '(tp-highlight t face bold help-echo "提示")) +;; 结果: 同时具有 tp-highlight 的背景色、bold 样式和 help-echo 属性 + +;; 重复属性自动合并示例 +(tp-set "emacs" + 'face 'bold + 'face '(:background "green") + 'face '(:foreground "red")) +;; 结果: face 是 ((:background "green" :foreground "red") bold) +;; 三个 face 属性被智能合并 + +;; 同一子属性后面的覆盖前面的 +(tp-set "emacs" + 'face '(:foreground "red") + 'face '(:foreground "yellow")) +;; 结果: foreground 是 "yellow" + +;; 与 tp-palette 层配合使用 +(tp-set "emacs" + 'tp-palette 'info + 'face '(:foreground "red")) +;; 结果: tp-palette 的 face 与 (:foreground "red") 合并 +``` + +#### 自定义文本属性组 + +使用 `define-tps` 可以定义多个相关的文本属性组,它们可以单独使用,也可以作为一组使用。 + +--- + +### 文本属性层 + +文本属性层是 tp.el 的**独特功能**,需要使用特定的函数(`tp-put-layer`/`tp-push-layer`)才能设置和使用。 + +#### 核心特性 + +1. **引入层相关属性**:当使用 `tp-push-layer`/`tp-put-layer` 设置时,会自动引入 `tp-name`、`tp-layers` 等层相关属性,用于支持层的堆叠和操作。 + +2. **层堆叠机制**:可以在同一文本区域堆叠多组属性,只有顶层可见,下层被保留。 + +3. **丰富的层操作**:支持轮换、删除、合并等多种层操作。 + +```elisp +;; 定义文本属性(可同时用作自定义属性或层) +(define-tp tp-highlight () + '(face (:background "yellow"))) + +;; 作为普通自定义文本属性使用(不引入层属性) (tp-set 1 10 '(tp-highlight t)) ;; 结果: 只有 face 属性,没有 tp-name @@ -1369,9 +1414,12 @@ tp.el 统一了"自定义文本属性"和"文本属性层"两个概念: #### 何时使用哪种方式 -- **`tp-set`/`tp-reset`/`tp-add`**:当你只需要设置文本属性,不需要层堆叠功能时使用。适合简单的属性设置场景。 - -- **`tp-push-layer`/`tp-put-layer`**:当你需要在同一文本区域堆叠多组属性,并进行轮换、删除等层操作时使用。 +| 场景 | 推荐方式 | 说明 | +|------|----------|------| +| 简单属性设置 | `tp-set`/`tp-reset`/`tp-add` | 当你只需要设置文本属性,不需要层堆叠功能时 | +| 与内置属性混合 | `tp-set`/`tp-reset`/`tp-add` | 自定义属性可以和内置属性无缝混合 | +| 需要层堆叠 | `tp-push-layer`/`tp-put-layer` | 当你需要在同一文本区域堆叠多组属性时 | +| 需要层操作 | `tp-push-layer`/`tp-put-layer` | 当你需要进行轮换、删除等层操作时 | ### 属性层概念