Hello everyone!
The attached patch defines and implements a few new faces for the
agenda. Quoting from the commit message:
These new faces are designed to improve the ability of themes/users to
control the presentation of agenda views. They inherit from existing
faces in order to remain backward-compatible.
+ The 'org-imminent-deadline' is useful to disambiguate generic
warnings from deadlines. For example, a warning could be rendered
in a yellow colored text and have a bold weight, whereas a deadline
might be red and styled with italics.
+ The 'org-agenda-structure-filter' applies to all tag/term filters
in agenda views that search for keywords or patterns. It is
designed to inherit from 'org-agenda-structure' in addition to the
'org-warning' face that was present before (and removes the
generic 'warning' face from one place). This offers the benefit
of consistency, as, say, an increase in font height or a change in
font family in 'org-agenda-structure' will propagate to the filter
as well. The whole header line thus looks part of a singular
design.
+ The 'org-agenda-structure-secondary' complements the above for those
same views where a description follows the header. For instance, the
tags view provides information to "Press N r" to filter by a
numbered tag. Themes/users may prefer to disambiguate this line
from the header above it, such as by using a less intense color or by
reducing its height relative to the 'org-agenda-structure'.
+ The 'org-agenda-date-weekend-today' provides the option to
differentiate the current date on a weekend from the current date on
weekdays.
Some more words about the motivation behind this patch, which are not
included in the commit message:
+ The 'org-warning' is a generic face that should always convey a clear
warning sign. It does that well. Deadlines also got styled with this
by default, which meant that they could not be toned down a bit, or
otherwise tweaked to meet the requirements of the agenda, without
compromising the intended purpose of a prominent warning. Ultimately
this is about choice: users/themes may not want to use intense styles
for deadlines by default.
- For some prior work on applying a bespoke face instead of
'org-warning', refer to commit 7ebb2d562 in org.git.
+ The 'org-agenda-date-weekend-today' complements the existing faces for
differentiating weekdays from weekends. So the "current day" can now
be adapted to this distinction, depending on the user's particular
needs.
What do you think? Is there something you would like to see done
differently?
I include Gustavo Barros in Cc, with whom we identified the potential
for these changes and who helped me think about their design and test
their implementation. This is done for communication purposes: any
errors are exclusively my own.
I have already assigned copyright to the FSF and have made such
contributions before.
All the best,
Protesilaos or "Prot"
--
Protesilaos Stavrou
https://protesilaos.com
>From b47af2b79c5ecfe0954dfd0bbe1bedd531b81417 Mon Sep 17 00:00:00 2001
Message-Id: <b47af2b79c5ecfe0954dfd0bbe1bedd531b81417.1622753459.git.i...@protesilaos.com>
From: Protesilaos Stavrou <i...@protesilaos.com>
Date: Wed, 2 Jun 2021 12:51:07 +0300
Subject: [PATCH] Add faces to improve contextuality of agenda views
* lisp/org-agenda.el (org-search-view)
(org-agenda-propertize-selected-todo-keywords, org-todo-list)
(org-tags-view): Implement new org-agenda-structure-filter and
org-agenda-structure-secondary faces.
(org-agenda-get-day-face): Add condition for rendering the current
date heading in org-agenda-date-weekend-today.
* lisp/org-faces.el (org-agenda-structure-secondary)
(org-agenda-date-weekend-today, org-agenda-structure-filter)
(org-imminent-deadline): Add new faces.
(org-agenda-deadline-faces): Use the 'org-imminent-deadline' for
current deadlines instead of the generic 'org-warning'.
-----
These new faces are designed to improve the ability of themes/users to
control the presentation of agenda views. They inherit from existing
faces in order to remain backward-compatible.
+ The 'org-imminent-deadline' is useful to disambiguate generic
warnings from deadlines. For example, a warning could be rendered
in a yellow colored text and have a bold weight, whereas a deadline
might be red and styled with italics.
+ The 'org-agenda-structure-filter' applies to all tag/term filters in
agenda views that search for keywords or patterns. It is designed to
inherit from 'org-agenda-structure' in addition to the 'org-warning'
face that was present before (and removes the generic 'warning' face
from one place). This offers the benefit of consistency, as, say, an
increase in font height or a change in font family in
'org-agenda-structure' will propagate to the filter as well. The
whole header line thus looks part of a singular design.
+ The 'org-agenda-structure-secondary' complements the above for those
same views where a description follows the header. For instance, the
tags view provides information to "Press N r" to filter by a
numbered tag. Themes/users may prefer to disambiguate this line
from the header above it, such as by using a less intense color or by
reducing its height relative to the 'org-agenda-structure'.
+ The 'org-agenda-date-weekend-today' provides the option to
differentiate the current date on a weekend from the current date on
weekdays.
---
lisp/org-agenda.el | 17 ++++++++++-------
lisp/org-faces.el | 21 ++++++++++++++++++++-
2 files changed, 30 insertions(+), 8 deletions(-)
diff --git a/lisp/org-agenda.el b/lisp/org-agenda.el
index f49a24f88..97f0bab85 100644
--- a/lisp/org-agenda.el
+++ b/lisp/org-agenda.el
@@ -4264,6 +4264,9 @@ (defun org-agenda-get-day-face (date)
"Return the face DATE should be displayed with."
(cond ((and (functionp org-agenda-day-face-function)
(funcall org-agenda-day-face-function date)))
+ ((and (org-agenda-today-p date)
+ (memq (calendar-day-of-week date) org-agenda-weekend-days))
+ 'org-agenda-date-weekend-today)
((org-agenda-today-p date) 'org-agenda-date-today)
((memq (calendar-day-of-week date) org-agenda-weekend-days)
'org-agenda-date-weekend)
@@ -4802,7 +4805,7 @@ (defun org-search-view (&optional todo-only string edit-at)
(list 'face 'org-agenda-structure))
(setq pos (point))
(insert string "\n")
- (add-text-properties pos (1- (point)) (list 'face 'org-warning))
+ (add-text-properties pos (1- (point)) (list 'face 'org-agenda-structure-filter))
(setq pos (point))
(unless org-agenda-multi
(insert (substitute-command-keys "\\<org-agenda-mode-map>\
@@ -4812,7 +4815,7 @@ (defun org-search-view (&optional todo-only string edit-at)
`\\[org-agenda-manipulate-query-subtract-re]' to add/sub regexp, \
`\\[universal-argument] \\[org-agenda-redo]' for a fresh search\n"))
(add-text-properties pos (1- (point))
- (list 'face 'org-agenda-structure)))
+ (list 'face 'org-agenda-structure-secondary)))
(buffer-string)))
(org-agenda-mark-header-line (point-min))
(when rtnall
@@ -4833,10 +4836,10 @@ (defun org-agenda-propertize-selected-todo-keywords (keywords)
"Use `org-todo-keyword-faces' for the selected todo KEYWORDS."
(concat
(if (or (equal keywords "ALL") (not keywords))
- (propertize "ALL" 'face 'warning)
+ (propertize "ALL" 'face 'org-agenda-structure-filter)
(mapconcat
(lambda (kw)
- (propertize kw 'face (org-get-todo-face kw)))
+ (propertize kw 'face (list (org-get-todo-face kw) 'org-agenda-structure)))
(org-split-string keywords "|")
"|"))
"\n"))
@@ -4921,7 +4924,7 @@ (defun org-todo-list (&optional arg)
(insert "\n "))
(insert " " s))))
(insert "\n"))
- (add-text-properties pos (1- (point)) (list 'face 'org-agenda-structure))
+ (add-text-properties pos (1- (point)) (list 'face 'org-agenda-structure-secondary))
(buffer-string)))
(org-agenda-mark-header-line (point-min))
(when rtnall
@@ -5012,7 +5015,7 @@ (defun org-tags-view (&optional todo-only match)
(concat "Match: " match)))
(setq pos (point))
(insert match "\n")
- (add-text-properties pos (1- (point)) (list 'face 'org-warning))
+ (add-text-properties pos (1- (point)) (list 'face 'org-agenda-structure-filter))
(setq pos (point))
(unless org-agenda-multi
(insert (substitute-command-keys
@@ -5020,7 +5023,7 @@ (defun org-tags-view (&optional todo-only match)
\\<org-agenda-mode-map>`\\[universal-argument] \\[org-agenda-redo]' \
to search again\n")))
(add-text-properties pos (1- (point))
- (list 'face 'org-agenda-structure))
+ (list 'face 'org-agenda-structure-secondary))
(buffer-string)))
(org-agenda-mark-header-line (point-min))
(when rtnall
diff --git a/lisp/org-faces.el b/lisp/org-faces.el
index 937c2d6f2..ecb957290 100644
--- a/lisp/org-faces.el
+++ b/lisp/org-faces.el
@@ -499,6 +499,16 @@ (defface org-agenda-structure ;Copied from `font-lock-function-name-face'
"Face used in agenda for captions and dates."
:group 'org-faces)
+(defface org-agenda-structure-secondary '((t (:inherit org-agenda-structure)))
+ "Face used for secondary information in agenda block headers."
+ :group 'org-faces)
+
+(defface org-agenda-structure-filter '((t (:inherit (org-warning org-agenda-structure))))
+ "Face used for the current type of task filter in the agenda.
+It inherits from `org-agenda-structure' so it can adapt to
+it (e.g. if that is assigned a diffent font height or family)."
+ :group 'org-faces)
+
(defface org-agenda-date '((t (:inherit org-agenda-structure)))
"Face used in agenda for normal days."
:group 'org-faces)
@@ -508,6 +518,10 @@ (defface org-agenda-date-today
"Face used in agenda for today."
:group 'org-faces)
+(defface org-agenda-date-weekend-today '((t (:inherit org-agenda-date-today)))
+ "Face used in agenda for today during weekends."
+ :group 'org-faces)
+
(defface org-agenda-clocking '((t (:inherit secondary-selection)))
"Face marking the current clock item in the agenda."
:group 'org-faces)
@@ -550,6 +564,11 @@ (defface org-scheduled-previously
"Face for items scheduled previously, and not yet done."
:group 'org-faces)
+(defface org-imminent-deadline '((t :inherit org-warning))
+ "Face for current deadlines in the agenda.
+See also `org-agenda-deadline-faces'."
+ :group 'org-faces)
+
(defface org-upcoming-deadline
'((((class color) (min-colors 88) (background light)) (:foreground "Firebrick"))
(((class color) (min-colors 88) (background dark)) (:foreground "chocolate1"))
@@ -565,7 +584,7 @@ (defface org-upcoming-distant-deadline '((t :inherit org-default))
See also `org-agenda-deadline-faces'.")
(defcustom org-agenda-deadline-faces
- '((1.0 . org-warning)
+ '((1.0 . org-imminent-deadline)
(0.5 . org-upcoming-deadline)
(0.0 . org-upcoming-distant-deadline))
"Faces for showing deadlines in the agenda.
--
2.31.1
