branch: externals/cursory
commit 892c3b81037ece0e1753ab058e3cfda93f985693
Author: Protesilaos Stavrou <i...@protesilaos.com>
Commit: Protesilaos Stavrou <i...@protesilaos.com>
Update to Cursory version 1.2.0
---
CHANGELOG.org | 114 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
README.org | 13 ++++---
cursory.el | 2 +-
3 files changed, 121 insertions(+), 8 deletions(-)
diff --git a/CHANGELOG.org b/CHANGELOG.org
index cfe722209c..97cc5e8ed4 100644
--- a/CHANGELOG.org
+++ b/CHANGELOG.org
@@ -13,6 +13,120 @@ the manual: <https://protesilaos.com/emacs/cursory>.
#+toc: headlines 1 insert TOC here, with one headline level
+* Version 1.2.0 on 2025-07-22
+:PROPERTIES:
+:CUSTOM_ID: h:eb19d9c7-a13b-41ac-bc6c-5b436b75844f
+:END:
+
+This version contains small additions to a stable package.
+
+** Set the last preset when starting up Emacs
+:PROPERTIES:
+:CUSTOM_ID: h:31ab2945-3f9f-41c8-9e06-b9360d23ccd8
+:END:
+
+The new function ~cursory-set-last-or-fallback~ makes it easier to set
+the last known preset when starting Emacs or via a hook such as
~after-init-hook~.
+Internally, it takes care to fall back to a set of default values that
+always work.
+
+Before the introduction of ~cursory-set-last-or-fallback~ users had to
+do something like this:
+
+#+begin_src emacs-lisp
+;; Old way of setting a preset:
+(cursory-set-preset (or cursory-last-selected-preset cursory-recovered-preset
'box))
+
+;; Old way of doing the above via a hook:
+(add-hook 'after-init-hook (lambda () (cursory-set-preset (or
cursory-last-selected-preset cursory-recovered-preset 'box))))
+#+end_src
+
+Those would also fail if the named preset did not exist (=box= in the
+above example). Whereas the addition of a fallback preset guarantees a
+result that works.
+
+Note that I am defining the ~cursory-fallback-preset~ using ~defconst~
+instead of exposing it as a user option. This is to avoid a scenario
+where the values are accidentally set incorrectly.
+
+** Presets can define a =:cursor-color=
+:PROPERTIES:
+:CUSTOM_ID: h:4e083edb-dde1-4d3a-905f-fc91d917ad32
+:END:
+
+This is a new attribute which corresponds to the background value of
+the ~cursor~ face.
+
+- When the value is nil or ~unspecified~ (the default), Cursory does
+ not modify the ~cursor~ face.
+
+- When the value is a hexadecimal RGB color value, like =#123456= it
+ is used as-is. Same if it is a named color among those produced by
+ the command ~list-colors-display~.
+
+- When the value is the symbol of a face (unquoted), then the
+ foreground of that face is used for the ~cursor~ face, falling back
+ to ~default~.
+
+Concretely, users can have something like this in their configuration:
+
+#+begin_src emacs-lisp
+(setq cursory-presets
+ '((box
+ :cursor-color "#21439f"
+ :blink-cursor-interval 1.2)
+ (baring
+ :cursor-type (bar . 2)
+ :cursor-color error ; the `error' face will typically be red (see
`list-faces-display')
+ :blink-cursor-interval 0.8)
+ (underscore
+ :cursor-color "green" ; see `list-colors-display'
+ :cursor-type (hbar . 1)
+ :blink-cursor-interval 0.3
+ :blink-cursor-blinks 50)
+ (t ; the default values
+ :cursor-color unspecified ; use the theme's original
+ :cursor-type box
+ :cursor-in-non-selected-windows hollow
+ :blink-cursor-mode 1
+ :blink-cursor-blinks 10
+ :blink-cursor-interval 0.2
+ :blink-cursor-delay 0.2)))
+#+end_src
+
+Remember to read the documentation of ~cursory-presets~ for all the rest.
+
+** The ~cursory-mode~ persists the =:cursor-color= while changing themes
+:PROPERTIES:
+:CUSTOM_ID: h:b425ae98-bb25-4af5-9f1d-0a6299cf6856
+:END:
+
+Before, the ~cursory-mode~ would only take care to save the last
+selected preset and to persist it across Emacs sessions. In addition
+to that, it now also ensures that loading a new theme does not
+override the =:cursor-color=.
+
+** The ~cursory-set-preset~ prompt is smarter about its default value
+:PROPERTIES:
+:CUSTOM_ID: h:1a1e4447-a6ee-4f6c-9ef5-4a9546338644
+:END:
+
+When the ~cursory-set-preset~ is called interactively, it uses the
+minibuffer to prompt for a preset among the ~cursory-presets~.
+
+In the past, its default value would simply be the last selected
+preset. Cursory would not check whether that symbol was still a member
+of the ~cursory-presets~. This had the potential to set the wrong
+configurations.
+
+Now the prompt only uses as its default value the last selected and
+existing preset among those found in the history of selections. It
+will not provide a default if it cannot find any.
+
+Note that the "default value" in the context of the minibuffer refers
+to the input that will normally be provided if the user types =RET=
+without writing anything into the minibuffer.
+
* Version 1.1.0 on 2024-09-14
:PROPERTIES:
:CUSTOM_ID: h:475f025a-fa3d-4709-884f-bd0b32dc78cc
diff --git a/README.org b/README.org
index c6a0b75951..b9ede76111 100644
--- a/README.org
+++ b/README.org
@@ -4,9 +4,9 @@
#+language: en
#+options: ':t toc:nil author:t email:t num:t
#+startup: content
-#+macro: stable-version 1.1.0
-#+macro: release-date 2024-09-14
-#+macro: development-version 1.2.0-dev
+#+macro: stable-version 1.2.0
+#+macro: release-date 2025-07-22
+#+macro: development-version 1.3.0-dev
#+macro: file @@texinfo:@file{@@$1@@texinfo:}@@
#+macro: space @@texinfo:@: @@
#+macro: kbd @@texinfo:@kbd{@@$1@@texinfo:}@@
@@ -240,8 +240,7 @@ face. When the value is nil or ~unspecified~, no changes to
the
value, like =#123456= it is used as-is. Same if it is a named color
among those produced by the command ~list-colors-display~. When the
value is the symbol of a face (unquoted), then the foreground of that
-face is used for the ~cursor~ face, falling back to ~default~. [ The
-=:cursor-color= is part of {{{development-version}}}. ]
+face is used for the ~cursor~ face, falling back to ~default~.
A property of =:blink-cursor-mode= is also available. It is a numeric
value of either =1= or =-1= and is given to the function
@@ -336,12 +335,12 @@ enable the ~cursory-mode~. It arranges to track the
latest preset each
time after using ~cursory-set-preset~ or Emacs is closed. The mode
will also persist the =:cursor-color= attribute, if set, when
switching to another theme. Otherwise, the theme's style will take
-precedence. [ The =:cursor-color= is part of {{{development-version}}}. ]
+precedence.
#+findex: cursory-set-last-or-fallback
The function ~cursory-set-last-or-fallback~ can be added to the user
configuration to automatically set the last known Cursory preset or
-some known fallback values. [ This function is part of
{{{development-version}}}. ]
+some known fallback values.
** Example hooks after setting a preset
:PROPERTIES:
diff --git a/cursory.el b/cursory.el
index dca236f903..5ef4b95f61 100644
--- a/cursory.el
+++ b/cursory.el
@@ -5,7 +5,7 @@
;; Author: Protesilaos Stavrou <i...@protesilaos.com>
;; Maintainer: Protesilaos Stavrou <i...@protesilaos.com>
;; URL: https://github.com/protesilaos/cursory
-;; Version: 1.1.0
+;; Version: 1.2.0
;; Package-Requires: ((emacs "29.1"))
;; Keywords: convenience, cursor
