GNU bug report logs - #75794
[PATCH] feat(icomplete): markers and vertical alignment

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 75794 in the body.
You can then email your comments to 75794 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Rahul Martim Juliato <rahuljuliato <at> gmail.com>
To: bug-gnu-emacs <at> gnu.org
Subject: [PATCH] feat(icomplete): markers and vertical alignment
Date: Thu, 23 Jan 2025 23:51:06 -0300

[Message part 1 (text/plain, inline)]

Tags: patch

Tags: patch

Dear GNU Emacs Maintainers,

I hope this message finds you well.

I am submitting a patch for icomplete-mode that introduces two
enhancements aimed at improving the user experience with completion
candidates:

Vertical Alignment: When using icomplete-vertical-mode for in-buffer
completion, the candidates will now align vertically with the column
where the cursor was when completion started. This provides a cleaner,
more intuitive visual experience when scrolling through completion
suggestions.

Customizable Markers: I’ve introduced two customizable markers for
icomplete-vertical-mode. The first marker will be applied to the
selected candidate, and the second will apply to the rest of the
list. Both markers are customizable via Emacs faces, allowing users to
tailor the appearance to their preferences.

These enhancements are intended to improve the usability and flexibility
of the icomplete interface. The ability to align the completion
candidates and customize the markers will make the completion process
smoother, especially in environments where visual clarity is essential.

In case you would like to explore the context further, I’ve written two
blog posts discussing in-buffer icomplete and these enhancements:


In-Buffer icomplete
[1] https://www.rahuljuliato.com/posts/in-buffer-icomplete

This post provides an introduction to the improvements made to icomplete
and the reasoning behind the changes.


In-Buffer icomplete – A Follow-up
[2] https://www.rahuljuliato.com/posts/in-buffer-icomplete-2

This second post elaborates on the specific features introduced in the
patch, with images illustrating the differences in the user interface.

The blog posts contain references to the changes and visual examples
that may help clarify the intent of the patch. I believe this will
provide a more comprehensive understanding of the features and their
potential impact.


The patch is attached for review. The modifications have been tested,
and I’m happy to make any adjustments or answer any questions regarding
the implementation.

Thank you for considering this patch, and I look forward to your
feedback.

Best regards,
Rahul Martim Juliato
[rahul.juliato <at> gmail.com]


In GNU Emacs 30.0.91 (build 1, x86_64-pc-linux-gnu, GTK+ Version
 3.24.38, cairo version 1.16.0) of 2024-09-26 built on debian
Repository revision: 9a1c76bf7ff49d886cc8e1a3f360d71e62544802
Repository branch: HEAD
Windowing system distributor 'The X.Org Foundation', version 11.0.12101007
System Description: Debian GNU/Linux 12 (bookworm)

[0001-feat-icomplete-markers-and-vertical-alignment.patch (text/patch, attachment)]

Message #8 received at 75794 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Rahul Martim Juliato <rahuljuliato <at> gmail.com>
Cc: 75794 <at> debbugs.gnu.org
Subject: Re: bug#75794: [PATCH] feat(icomplete): markers and vertical alignment
Date: Fri, 24 Jan 2025 10:55:27 +0200

> From: Rahul Martim Juliato <rahuljuliato <at> gmail.com>
> Date: Thu, 23 Jan 2025 23:51:06 -0300
> 
> I am submitting a patch for icomplete-mode that introduces two
> enhancements aimed at improving the user experience with completion
> candidates:
> 
> Vertical Alignment: When using icomplete-vertical-mode for in-buffer
> completion, the candidates will now align vertically with the column
> where the cursor was when completion started. This provides a cleaner,
> more intuitive visual experience when scrolling through completion
> suggestions.
> 
> Customizable Markers: I’ve introduced two customizable markers for
> icomplete-vertical-mode. The first marker will be applied to the
> selected candidate, and the second will apply to the rest of the
> list. Both markers are customizable via Emacs faces, allowing users to
> tailor the appearance to their preferences.
> 
> These enhancements are intended to improve the usability and flexibility
> of the icomplete interface. The ability to align the completion
> candidates and customize the markers will make the completion process
> smoother, especially in environments where visual clarity is essential.
> 
> In case you would like to explore the context further, I’ve written two
> blog posts discussing in-buffer icomplete and these enhancements:

Thanks, please see some comments below.

> Add two enhancements to icomplete-mode:
> 
> - Vertical alignment when using icomplete-vertical-mode with
>   in-buffer completion, so candidates are aligned with
>   the column where the cursor was when completion started.
> 
> - Customizable markers to icomplete-vertical-mode, providing
>   each candidate a prefix if currently selected and another
>   prefix for the rest of the list. Faces can also be customized.

This commit log should include a ChangeLog-style descriptions of
added/modified variables and functions.  See CONTRIBUTE for the
details.

> +(defface icomplete-vertical-selected-prefix-face
> +  '((t :inherit font-lock-keyword-face :weight bold :foreground "cyan"))
> +  "Face used for the prefix set by `icomplete-vertical-selected-prefix-marker'."
> +  :group 'icomplete
> +  :version "31")
> +
> +(defface icomplete-vertical-unselected-prefix-face
> +  '((t :inherit font-lock-keyword-face :weight normal :foreground "gray"))
> +  "Face used for the prefix set by `icomplete-vertical-unselected-prefix-marker'."
> +  :group 'icomplete
> +  :version "31")
              ^^^^
This should be "31.1" (here and elsewhere in the patch.

> +(defcustom icomplete-vertical-in-buffer-adjust-list t
> +  "Control whether in-buffer completion should align the cursor position.

Is it necessary to turn the new behavior ON by default?  Would people
be surprised or annoyed by this behavior change?

> +(defcustom icomplete-vertical-render-prefix-marker t
> +  "Control whether a marker is added as a prefix to each candidate.

I think you are talking about some indication, not a marker.  "Marker"
in Emacs has special meaning, not what you mean by that here.  So I
suggest to reword this (and other) doc string(s) accordingly.

> +(defcustom icomplete-vertical-selected-prefix-marker "» "
> +  "Prefix string used to mark the selected completion candidate.
> +If `icomplete-vertical-render-prefix-marker' is t, the string
> +setted here is used as a prefix of the currently selected entry in the
   ^^^^^^
"defined", not "setted".

> +(defcustom icomplete-vertical-unselected-prefix-marker "  "
> +  "Prefix string used on the unselected completion candidates.
> +If `icomplete-vertical-render-prefix-marker' is t, the string
> +setted here is used as a prefix for all unselected entries in the list.
   ^^^^^^
Same.

> +(defun icomplete-vertical--adjust-lines-for-column (lines buffer data)
> +  "Adjust the LINES to align with the column in BUFFER based on DATA."
> +  (if icomplete-vertical-in-buffer-adjust-list
> +      (let ((column
> +             (with-current-buffer buffer
> +               (save-excursion
> +                 (goto-char (car data))
> +                 (current-column)))))
> +        (dolist (l lines)
> +          (add-text-properties
> +           0 1 `(display ,(concat (make-string column ?\s) (substring l 0 1)))
> +           l))
> +        lines)
> +    lines))

Did you test this with a window horizontally scrolled (when
truncate-lines is non-nil)?  What about continuation lines?  In both
these cases, current-column is different from the visual column on the
screen, counted from the left edge of the window.

Message #11 received at 75794 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: rahuljuliato <at> gmail.com
Cc: 75794 <at> debbugs.gnu.org
Subject: Re: bug#75794: [PATCH] feat(icomplete): markers and vertical alignment
Date: Fri, 24 Jan 2025 11:00:18 +0200

> Cc: 75794 <at> debbugs.gnu.org
> Date: Fri, 24 Jan 2025 10:55:27 +0200
> From: Eli Zaretskii <eliz <at> gnu.org>
> 
> > From: Rahul Martim Juliato <rahuljuliato <at> gmail.com>
> > Date: Thu, 23 Jan 2025 23:51:06 -0300
> > 
> > I am submitting a patch for icomplete-mode that introduces two
> > enhancements aimed at improving the user experience with completion
> > candidates:
> > 
> > Vertical Alignment: When using icomplete-vertical-mode for in-buffer
> > completion, the candidates will now align vertically with the column
> > where the cursor was when completion started. This provides a cleaner,
> > more intuitive visual experience when scrolling through completion
> > suggestions.
> > 
> > Customizable Markers: I’ve introduced two customizable markers for
> > icomplete-vertical-mode. The first marker will be applied to the
> > selected candidate, and the second will apply to the rest of the
> > list. Both markers are customizable via Emacs faces, allowing users to
> > tailor the appearance to their preferences.
> > 
> > These enhancements are intended to improve the usability and flexibility
> > of the icomplete interface. The ability to align the completion
> > candidates and customize the markers will make the completion process
> > smoother, especially in environments where visual clarity is essential.
> > 
> > In case you would like to explore the context further, I’ve written two
> > blog posts discussing in-buffer icomplete and these enhancements:
> 
> Thanks, please see some comments below.

And one other comment: these are user-visible changes, so I think they
warrant a NEWS entry.

Message #14 received at 75794 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: rahuljuliato <at> gmail.com
Cc: 75794 <at> debbugs.gnu.org
Subject: Re: bug#75794: [PATCH] feat(icomplete): markers and vertical alignment
Date: Sat, 08 Feb 2025 11:24:11 +0200

Ping!  Rahul, would you please submit an improved version of the patch
with my comments addressed, so that we could proceed to installing
this?

> Cc: 75794 <at> debbugs.gnu.org
> Date: Fri, 24 Jan 2025 10:55:27 +0200
> From: Eli Zaretskii <eliz <at> gnu.org>
> 
> > From: Rahul Martim Juliato <rahuljuliato <at> gmail.com>
> > Date: Thu, 23 Jan 2025 23:51:06 -0300
> > 
> > I am submitting a patch for icomplete-mode that introduces two
> > enhancements aimed at improving the user experience with completion
> > candidates:
> > 
> > Vertical Alignment: When using icomplete-vertical-mode for in-buffer
> > completion, the candidates will now align vertically with the column
> > where the cursor was when completion started. This provides a cleaner,
> > more intuitive visual experience when scrolling through completion
> > suggestions.
> > 
> > Customizable Markers: I’ve introduced two customizable markers for
> > icomplete-vertical-mode. The first marker will be applied to the
> > selected candidate, and the second will apply to the rest of the
> > list. Both markers are customizable via Emacs faces, allowing users to
> > tailor the appearance to their preferences.
> > 
> > These enhancements are intended to improve the usability and flexibility
> > of the icomplete interface. The ability to align the completion
> > candidates and customize the markers will make the completion process
> > smoother, especially in environments where visual clarity is essential.
> > 
> > In case you would like to explore the context further, I’ve written two
> > blog posts discussing in-buffer icomplete and these enhancements:
> 
> Thanks, please see some comments below.
> 
> > Add two enhancements to icomplete-mode:
> > 
> > - Vertical alignment when using icomplete-vertical-mode with
> >   in-buffer completion, so candidates are aligned with
> >   the column where the cursor was when completion started.
> > 
> > - Customizable markers to icomplete-vertical-mode, providing
> >   each candidate a prefix if currently selected and another
> >   prefix for the rest of the list. Faces can also be customized.
> 
> This commit log should include a ChangeLog-style descriptions of
> added/modified variables and functions.  See CONTRIBUTE for the
> details.
> 
> > +(defface icomplete-vertical-selected-prefix-face
> > +  '((t :inherit font-lock-keyword-face :weight bold :foreground "cyan"))
> > +  "Face used for the prefix set by `icomplete-vertical-selected-prefix-marker'."
> > +  :group 'icomplete
> > +  :version "31")
> > +
> > +(defface icomplete-vertical-unselected-prefix-face
> > +  '((t :inherit font-lock-keyword-face :weight normal :foreground "gray"))
> > +  "Face used for the prefix set by `icomplete-vertical-unselected-prefix-marker'."
> > +  :group 'icomplete
> > +  :version "31")
>               ^^^^
> This should be "31.1" (here and elsewhere in the patch.
> 
> > +(defcustom icomplete-vertical-in-buffer-adjust-list t
> > +  "Control whether in-buffer completion should align the cursor position.
> 
> Is it necessary to turn the new behavior ON by default?  Would people
> be surprised or annoyed by this behavior change?
> 
> > +(defcustom icomplete-vertical-render-prefix-marker t
> > +  "Control whether a marker is added as a prefix to each candidate.
> 
> I think you are talking about some indication, not a marker.  "Marker"
> in Emacs has special meaning, not what you mean by that here.  So I
> suggest to reword this (and other) doc string(s) accordingly.
> 
> > +(defcustom icomplete-vertical-selected-prefix-marker "» "
> > +  "Prefix string used to mark the selected completion candidate.
> > +If `icomplete-vertical-render-prefix-marker' is t, the string
> > +setted here is used as a prefix of the currently selected entry in the
>    ^^^^^^
> "defined", not "setted".
> 
> > +(defcustom icomplete-vertical-unselected-prefix-marker "  "
> > +  "Prefix string used on the unselected completion candidates.
> > +If `icomplete-vertical-render-prefix-marker' is t, the string
> > +setted here is used as a prefix for all unselected entries in the list.
>    ^^^^^^
> Same.
> 
> > +(defun icomplete-vertical--adjust-lines-for-column (lines buffer data)
> > +  "Adjust the LINES to align with the column in BUFFER based on DATA."
> > +  (if icomplete-vertical-in-buffer-adjust-list
> > +      (let ((column
> > +             (with-current-buffer buffer
> > +               (save-excursion
> > +                 (goto-char (car data))
> > +                 (current-column)))))
> > +        (dolist (l lines)
> > +          (add-text-properties
> > +           0 1 `(display ,(concat (make-string column ?\s) (substring l 0 1)))
> > +           l))
> > +        lines)
> > +    lines))
> 
> Did you test this with a window horizontally scrolled (when
> truncate-lines is non-nil)?  What about continuation lines?  In both
> these cases, current-column is different from the visual column on the
> screen, counted from the left edge of the window.
> 
> 
> 
> 
> And one other comment: these are user-visible changes, so I think they
> warrant a NEWS entry.

Message #17 received at 75794 <at> debbugs.gnu.org (full text, mbox):

From: Rahul Martim Juliato <rahuljuliato <at> gmail.com>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 75794 <at> debbugs.gnu.org
Subject: Re: bug#75794: [PATCH] feat(icomplete): markers and vertical alignment
Date: Sun, 09 Feb 2025 20:08:56 -0300

[Message part 1 (text/plain, inline)]

Pong! Sorry for the delayed follow up.

Please find attached a new version of the patch, Below my
considerations: 

> Ping!  Rahul, would you please submit an improved version of the patch
> with my comments addressed, so that we could proceed to installing
> this?
>
>> Cc: 75794 <at> debbugs.gnu.org
>> Date: Fri, 24 Jan 2025 10:55:27 +0200
>> From: Eli Zaretskii <eliz <at> gnu.org>
>> 
>> > From: Rahul Martim Juliato <rahuljuliato <at> gmail.com>
>> > Date: Thu, 23 Jan 2025 23:51:06 -0300
>> > 
>> > I am submitting a patch for icomplete-mode that introduces two
>> > enhancements aimed at improving the user experience with completion
>> > candidates:
>> > 
>> > Vertical Alignment: When using icomplete-vertical-mode for in-buffer
>> > completion, the candidates will now align vertically with the column
>> > where the cursor was when completion started. This provides a cleaner,
>> > more intuitive visual experience when scrolling through completion
>> > suggestions.
>> > 
>> > Customizable Markers: I’ve introduced two customizable markers for
>> > icomplete-vertical-mode. The first marker will be applied to the
>> > selected candidate, and the second will apply to the rest of the
>> > list. Both markers are customizable via Emacs faces, allowing users to
>> > tailor the appearance to their preferences.
>> > 
>> > These enhancements are intended to improve the usability and flexibility
>> > of the icomplete interface. The ability to align the completion
>> > candidates and customize the markers will make the completion process
>> > smoother, especially in environments where visual clarity is essential.
>> > 
>> > In case you would like to explore the context further, I’ve written two
>> > blog posts discussing in-buffer icomplete and these enhancements:
>> 
>> Thanks, please see some comments below.
>> 
>> > Add two enhancements to icomplete-mode:
>> > 
>> > - Vertical alignment when using icomplete-vertical-mode with
>> >   in-buffer completion, so candidates are aligned with
>> >   the column where the cursor was when completion started.
>> > 
>> > - Customizable markers to icomplete-vertical-mode, providing
>> >   each candidate a prefix if currently selected and another
>> >   prefix for the rest of the list. Faces can also be customized.
>> 
>> This commit log should include a ChangeLog-style descriptions of
>> added/modified variables and functions.  See CONTRIBUTE for the
>> details.
>> 

Done, please let me know if this OK or if I need to change something.

>> > +(defface icomplete-vertical-selected-prefix-face
>> > +  '((t :inherit font-lock-keyword-face :weight bold :foreground "cyan"))
>> > +  "Face used for the prefix set by `icomplete-vertical-selected-prefix-marker'."
>> > +  :group 'icomplete
>> > +  :version "31")
>> > +
>> > +(defface icomplete-vertical-unselected-prefix-face
>> > +  '((t :inherit font-lock-keyword-face :weight normal :foreground "gray"))
>> > +  "Face used for the prefix set by `icomplete-vertical-unselected-prefix-marker'."
>> > +  :group 'icomplete
>> > +  :version "31")
>>               ^^^^
>> This should be "31.1" (here and elsewhere in the patch.
>> 

Done.

>> > +(defcustom icomplete-vertical-in-buffer-adjust-list t
>> > +  "Control whether in-buffer completion should align the cursor position.
>> 
>> Is it necessary to turn the new behavior ON by default?  Would people
>> be surprised or annoyed by this behavior change?
>> 

I agree with you, it was ON for testing purposes only. Changed the
default to nil.

>> > +(defcustom icomplete-vertical-render-prefix-marker t
>> > +  "Control whether a marker is added as a prefix to each candidate.
>> 
>> I think you are talking about some indication, not a marker.  "Marker"
>> in Emacs has special meaning, not what you mean by that here.  So I
>> suggest to reword this (and other) doc string(s) accordingly.
>> 

Nice, in all functions and doc-strings this is now an 'indicator'.

>> > +(defcustom icomplete-vertical-selected-prefix-marker "» "
>> > +  "Prefix string used to mark the selected completion candidate.
>> > +If `icomplete-vertical-render-prefix-marker' is t, the string
>> > +setted here is used as a prefix of the currently selected entry in the
>>    ^^^^^^
>> "defined", not "setted".
>> 

Done.

>> > +(defcustom icomplete-vertical-unselected-prefix-marker "  "
>> > +  "Prefix string used on the unselected completion candidates.
>> > +If `icomplete-vertical-render-prefix-marker' is t, the string
>> > +setted here is used as a prefix for all unselected entries in the list.
>>    ^^^^^^
>> Same.
>> 

Done.

>> > +(defun icomplete-vertical--adjust-lines-for-column (lines buffer data)
>> > +  "Adjust the LINES to align with the column in BUFFER based on DATA."
>> > +  (if icomplete-vertical-in-buffer-adjust-list
>> > +      (let ((column
>> > +             (with-current-buffer buffer
>> > +               (save-excursion
>> > +                 (goto-char (car data))
>> > +                 (current-column)))))
>> > +        (dolist (l lines)
>> > +          (add-text-properties
>> > +           0 1 `(display ,(concat (make-string column ?\s) (substring l 0 1)))
>> > +           l))
>> > +        lines)
>> > +    lines))
>> 
>> Did you test this with a window horizontally scrolled (when
>> truncate-lines is non-nil)?  What about continuation lines?  In both
>> these cases, current-column is different from the visual column on the
>> screen, counted from the left edge of the window.
>> 

I think you meant when `truncate-lines' is `nil'. When it is 't, no
problems. When it is nil and we're dealing with wrapped lines, this
"works" with the annoying addition of a 'blank wrapped line' between
candidates.

I could not figure out how to fix it properly. Any tips?

For now, I annotated the doc-string informing this is a feature
limitation.

>> 
>> 
>> 
>> And one other comment: these are user-visible changes, so I think they
>> warrant a NEWS entry.

Done. Please tell me if we need to add/remove something to it.

-- 

Rahul Martim Juliato

[0001-Enhance-icomplete-vertical-mode-with-new-user-option.patch (text/x-diff, attachment)]

Message #22 received at 75794 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Rahul Martim Juliato <rahuljuliato <at> gmail.com>
Cc: 75794 <at> debbugs.gnu.org
Subject: Re: bug#75794: [PATCH] feat(icomplete): markers and vertical alignment
Date: Sat, 15 Feb 2025 13:55:27 +0200

> From: Rahul Martim Juliato <rahuljuliato <at> gmail.com>
> Cc: 75794 <at> debbugs.gnu.org
> Date: Sun, 09 Feb 2025 20:08:56 -0300
> 
> >> > +(defun icomplete-vertical--adjust-lines-for-column (lines buffer data)
> >> > +  "Adjust the LINES to align with the column in BUFFER based on DATA."
> >> > +  (if icomplete-vertical-in-buffer-adjust-list
> >> > +      (let ((column
> >> > +             (with-current-buffer buffer
> >> > +               (save-excursion
> >> > +                 (goto-char (car data))
> >> > +                 (current-column)))))
> >> > +        (dolist (l lines)
> >> > +          (add-text-properties
> >> > +           0 1 `(display ,(concat (make-string column ?\s) (substring l 0 1)))
> >> > +           l))
> >> > +        lines)
> >> > +    lines))
> >> 
> >> Did you test this with a window horizontally scrolled (when
> >> truncate-lines is non-nil)?  What about continuation lines?  In both
> >> these cases, current-column is different from the visual column on the
> >> screen, counted from the left edge of the window.
> >> 
> 
> I think you meant when `truncate-lines' is `nil'. When it is 't, no
> problems.

Including when the window is horizontally scrolled?

> When it is nil and we're dealing with wrapped lines, this
> "works" with the annoying addition of a 'blank wrapped line' between
> candidates.
> 
> I could not figure out how to fix it properly. Any tips?

If you need to know whether a line is continued or not, you can use
the function display--line-is-continued-p.  If that's not what you
need, please tell more details.

Message #25 received at 75794 <at> debbugs.gnu.org (full text, mbox):

From: Rahul Martim Juliato <rahuljuliato <at> gmail.com>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 75794 <at> debbugs.gnu.org
Subject: Re: bug#75794: [PATCH] feat(icomplete): markers and vertical alignment
Date: Tue, 18 Feb 2025 17:17:07 -0300

>> >> Did you test this with a window horizontally scrolled (when
>> >> truncate-lines is non-nil)?  What about continuation lines?  In both
>> >> these cases, current-column is different from the visual column on the
>> >> screen, counted from the left edge of the window.
>> >> 
>> 
>> I think you meant when `truncate-lines' is `nil'. When it is 't, no
>> problems.
>
> Including when the window is horizontally scrolled?

If I understood what you meant, yes, more below:

>> When it is nil and we're dealing with wrapped lines, this
>> "works" with the annoying addition of a 'blank wrapped line' between
>> candidates.
>> 
>> I could not figure out how to fix it properly. Any tips?
>
> If you need to know whether a line is continued or not, you can use
> the function display--line-is-continued-p.  If that's not what you
> need, please tell more details.

Thanks! More details below:

--

Let me add some images so we're on the same page:

With the latest patch, here’s what we currently have in "normal" usage:

1 - Normal usage
https://0x0.st/8bOz.png

2 - In the middle of the buffer:
https://0x0.st/8bOH.png

3 - At the end of the buffer:
https://0x0.st/8bOX.png

4 - With scrolling:
https://0x0.st/8bO8.png

Now after `toogle-truncate-lines`:

5 - In the middle of the buffer:
https://0x0.st/8bO8.png

6 - At the end of the buffer:
https://0x0.st/8bOP.png

7 - In the middle of a wrapped line:
https://0x0.st/8bOZ.png


As you see this is not yet very good with 'wrapped' lines. But the
overall idea is that anyone could easily override the
`icomplete-vertical--adjust-lines-for-column' function to make its own
implementation. 


Given current `icomplete-vertical--adjust-lines-for-column', I think we
could fix:

- 3) maybe with some "align to the right". Is there a any helper
  function that would take some content and print it fitting
  right-aligned or I'd have to implement it myself?

- 6, 7) Here I think the trick is having a way to check current column position,
  vs. visual total columns (I mean the total columns of any line wrapped
  or not fitting the current window), if current column is greater than
  the later, we subtract the visual total columns, so it is aligned.
  Again, are there helper functions to make this positioning of the
  cursor and window,column,width querying easier?

Thanks!

-- 

Rahul Martim Juliato

Message #28 received at 75794 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Rahul Martim Juliato <rahuljuliato <at> gmail.com>
Cc: 75794 <at> debbugs.gnu.org
Subject: Re: bug#75794: [PATCH] feat(icomplete): markers and vertical alignment
Date: Sat, 22 Feb 2025 12:12:22 +0200

> From: Rahul Martim Juliato <rahuljuliato <at> gmail.com>
> Cc: 75794 <at> debbugs.gnu.org
> Date: Tue, 18 Feb 2025 17:17:07 -0300
> 
> Given current `icomplete-vertical--adjust-lines-for-column', I think we
> could fix:
> 
> - 3) maybe with some "align to the right". Is there a any helper
>   function that would take some content and print it fitting
>   right-aligned or I'd have to implement it myself?
> 
> - 6, 7) Here I think the trick is having a way to check current column position,
>   vs. visual total columns (I mean the total columns of any line wrapped
>   or not fitting the current window), if current column is greater than
>   the later, we subtract the visual total columns, so it is aligned.
>   Again, are there helper functions to make this positioning of the
>   cursor and window,column,width querying easier?

I'm not sure I understand what helper functions you are looking for.
The function window-hscroll will tell you by how many columns the
current window is scrolled horizontally -- is that what you are
looking for?

Message #31 received at 75794 <at> debbugs.gnu.org (full text, mbox):

From: Rahul Martim Juliato <rahuljuliato <at> gmail.com>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 75794 <at> debbugs.gnu.org
Subject: Re: bug#75794: [PATCH] feat(icomplete): markers and vertical alignment
Date: Tue, 25 Feb 2025 22:24:15 -0300

Eli Zaretskii <eliz <at> gnu.org> writes:

>> From: Rahul Martim Juliato <rahuljuliato <at> gmail.com>
>> Cc: 75794 <at> debbugs.gnu.org
>> Date: Tue, 18 Feb 2025 17:17:07 -0300
>> 
>> Given current `icomplete-vertical--adjust-lines-for-column', I think we
>> could fix:
>> 
>> - 3) maybe with some "align to the right". Is there a any helper
>>   function that would take some content and print it fitting
>>   right-aligned or I'd have to implement it myself?
>> 
>> - 6, 7) Here I think the trick is having a way to check current column position,
>>   vs. visual total columns (I mean the total columns of any line wrapped
>>   or not fitting the current window), if current column is greater than
>>   the later, we subtract the visual total columns, so it is aligned.
>>   Again, are there helper functions to make this positioning of the
>>   cursor and window,column,width querying easier?
>
> I'm not sure I understand what helper functions you are looking for.
> The function window-hscroll will tell you by how many columns the
> current window is scrolled horizontally -- is that what you are
> looking for?

Hello there Eli!

Thanks for your help! This function indeed helps, but I went another
direction with something alike.

I know I am a slow contributtor, I'm steady and slowing evolving on this
matter (don't give up on me :D).

Just so I don't leave you in the dark, I'm working in a version that
already works on non truncated lines (aka lines that are shown wrapped).

Given this test case:

https://0x0.st/8AE1.png

We can start completion from whathever point of the line:

https://0x0.st/8AEj.png

https://0x0.st/8AEQ.png

https://0x0.st/8AE2.png


I'll shave some more edge cases before submitting a new patch.

-- 

Rahul Martim Juliato

Message #34 received at 75794 <at> debbugs.gnu.org (full text, mbox):

From: Rahul Martim Juliato <rahuljuliato <at> gmail.com>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 75794 <at> debbugs.gnu.org
Subject: Re: bug#75794: [PATCH] feat(icomplete): markers and vertical alignment
Date: Tue, 04 Mar 2025 11:03:52 -0300

[Message part 1 (text/plain, inline)]

Great news Eli!!!


It took me a while, but I believe I’ve figured it out!


I made a video comparing the behavior before and after applying this
patch. I think a visual demonstration is more effective than words
alone, as it highlights the many visual improvements.


Here’s the video link: https://www.youtube.com/watch?v=ni0l6PruJEs


This patch introduces two new features that improve
icomplete-vertical-mode, which are explained below:


1.) Improve feature provided by `icomplete-in-buffer'.
    If user, besides setting `icomplete-in-buffer' to t, also set the
    new `icomplete-vertical-in-buffer-adjust-list' to t, the following are fixed/ improved:

Without the new `icomplete-vertical-in-buffer-adjust-list':

* wrapped lines   - completion candidates on different columns always shows candidates at column 0
* wrapped lines   - completion candidates on different lines always shows candidates at column 0
* wrapped lines   - completion candidates close to the end of buffer won't be printed
* truncated lines - completion candidates on different columns always shows candidates at column 0
* truncated lines - completion candidates on horizontally scrolled windows won't appear on buffer
                        as they're on column 0
* truncated lines - completion candidates close to the end of buffer wont be shown


With the new `icomplete-vertical-in-buffer-adjust-list':

* wrapped lines   - fix    : completion candidates on different columns will always be printed
                                 under the cursor
* wrapped lines   - feature: completion candidates on different columns close to the end
                                 of the buffer will adjust so they stay visible
* wrapped lines   - fix:   : completion candidates on different lines always be printed under
                                 the cursor
* wrapped lines   - fix    : if icomplete-prospects-height won't fit from current line to the
                                 end of vertical space, our window will be scrolled so we have at
                                 least this amount of lines. This ensures our candidates list is
                                 always visible
* truncated lines - fix    : completion candidates on different columns will always be printed
                                 under the cursor
* truncated lines - feature: completion candidates on different columns close to the end
                                 of the buffer will adjust so they stay visible even when we scroll
                                 horizontally
* truncated lines - feature: completion candidates on horizontally scrolled windows will be
                                 printed under the cursor
* wrapped lines   - feature: if icomplete-prospects-height won't fit from current line to the
                                 end of vertical space, our window will be scrolled so we have at
                                 least this amount of lines. This ensures our candidates list is
                                 always visible
* from wrapped    - feature: if we are on wrapped lines and manually horiontal scroll, the lines
      to truncated               will become automatically truncated, in this case, all the features
                                 above still works from either mode (wrapped or truncated).



Attached is the latest (and hopefully final) version of this patch.

[0001-Enhance-icomplete-vertical-mode.patch (text/x-patch, inline)]

From 22fc5e56cd57c5e23b39f6de91831e73ae648515 Mon Sep 17 00:00:00 2001
From: Rahul Martim Juliato <rahul.juliato <at> gmail.com>
Date: Tue, 4 Mar 2025 01:35:32 -0300
Subject: [PATCH] Enhance 'icomplete-vertical-mode'

New user options have been added to enhance 'icomplete-vertical-mode':

 + 'icomplete-vertical-in-buffer-adjust-list': Aligns in-buffer
completion to the original cursor column.
 + 'icomplete-vertical-render-prefix-indicator': When enabled, adds a
prefix indicator to completion candidates.
 + 'icomplete-vertical-selected-prefix-indicator': Specifies the prefix
string for the selected candidate.
 + 'icomplete-vertical-unselected-prefix-indicator': Specifies the prefix
string for unselected candidates.

New faces introduced:

 + 'icomplete-vertical-selected-prefix-indicator-face': Controls the
appearance of the selected candidate prefix.
 + 'icomplete-vertical-unselected-prefix-indicator-face': Controls the
appearance of unselected candidate prefixes.

* etc/NEWS: Document the new user options and faces.
* lisp/icomplete.el(icomplete-vertical-mode): Implement the new options
---
 etc/NEWS          |  19 ++++++++
 lisp/icomplete.el | 121 ++++++++++++++++++++++++++++++++++++++++++++--
 2 files changed, 137 insertions(+), 3 deletions(-)

diff --git a/etc/NEWS b/etc/NEWS
index 67f9ed84bdf..7d180b5b04d 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -268,6 +268,25 @@ return value windows whose buffers share their text with BUFFER-OR-NAME.
 With such an entry, 'display-buffer-reuse-window' may also choose a
 window whose buffer shares text with the buffer to display.
 
++++
+*** New user options for 'icomplete-vertical-mode'.
+New user options have been added to enhance 'icomplete-vertical-mode':
+
+ - 'icomplete-vertical-in-buffer-adjust-list': Aligns in-buffer
+    completion to the original cursor column.
+ - 'icomplete-vertical-render-prefix-indicator': When enabled, adds a
+    prefix indicator to completion candidates.
+ - 'icomplete-vertical-selected-prefix-indicator': Specifies the prefix
+    string for the selected candidate.
+ - 'icomplete-vertical-unselected-prefix-indicator': Specifies the prefix
+    string for unselected candidates.
+
+New faces:
+
+ - 'icomplete-vertical-selected-prefix-indicator-face': Controls the
+    appearance of the selected candidate prefix.
+ - 'icomplete-vertical-unselected-prefix-indicator-face': Controls the
+    appearance of unselected candidate prefixes.
 
 ** Frames
 
diff --git a/lisp/icomplete.el b/lisp/icomplete.el
index c58bffbb36b..246da70a8ba 100644
--- a/lisp/icomplete.el
+++ b/lisp/icomplete.el
@@ -115,6 +115,18 @@ Otherwise this should be a list of the completion tables (e.g.,
   "Face used by `icomplete-vertical-mode' for the section title."
   :version "28.1")
 
+(defface icomplete-vertical-selected-prefix-indicator-face
+  '((t :inherit font-lock-keyword-face :weight bold :foreground "cyan"))
+  "Face used for the prefix set by `icomplete-vertical-selected-prefix-indicator'."
+  :group 'icomplete
+  :version "31.1")
+
+(defface icomplete-vertical-unselected-prefix-indicator-face
+  '((t :inherit font-lock-keyword-face :weight normal :foreground "gray"))
+  "Face used for the prefix set by `icomplete-vertical-unselected-prefix-indicator'."
+  :group 'icomplete
+  :version "31.1")
+
 ;;;_* User Customization variables
 (defcustom icomplete-prospects-height 2
   ;; We used to compute how many lines 100 characters would take in
@@ -166,6 +178,46 @@ will constrain Emacs to a maximum minibuffer height of 3 lines when
 icompletion is occurring."
   :type 'hook)
 
+(defcustom icomplete-vertical-in-buffer-adjust-list nil
+  "Control whether in-buffer completion should align the cursor position.
+If this is t and `icomplete-in-buffer' is t, and `icomplete-vertical-mode'
+is activated, the in-buffer vertical completions are shown aligned to the
+cursor position when the completion started, not on the first column, as
+the default behaviour."
+  :type 'boolean
+  :group 'icomplete
+  :version "31.1")
+
+(defcustom icomplete-vertical-render-prefix-indicator nil
+  "Control whether a indicator is added as a prefix to each candidate.
+If this is t and `icomplete-vertical-mode' is activated, a indicator,
+controlled by `icomplete-vertical-selected-prefix-indicator' is shown
+as a prefix to the current under selection candidate, while the
+remaining of the candidates will receive the indicator controlled
+by `icomplete-vertical-unselected-prefix-indicator'."
+  :type 'boolean
+  :group 'icomplete
+  :version "31.1")
+
+(defcustom icomplete-vertical-selected-prefix-indicator "» "
+  "Prefix string used to mark the selected completion candidate.
+If `icomplete-vertical-render-prefix-indicator' is t, the string
+defined here is used as a prefix of the currently selected entry in the
+list.  It can be further customized by the face
+`icomplete-vertical-selected-prefix-indicator-face'."
+  :type 'string
+  :group 'icomplete
+  :version "31.1")
+
+(defcustom icomplete-vertical-unselected-prefix-indicator "  "
+  "Prefix string used on the unselected completion candidates.
+If `icomplete-vertical-render-prefix-indicator' is t, the string
+defined here is used as a prefix for all unselected entries in the list.
+list.  It can be further customized by the face
+`icomplete-vertical-unselected-prefix-indicator-face'."
+  :type 'string
+  :group 'icomplete
+  :version "31.1")
 
 ;;;_* Initialization
 
@@ -828,6 +880,60 @@ by `group-function''s second \"transformation\" protocol."
                  else collect (list tr prefix suffix ))
       annotated)))
 
+(defun icomplete-vertical--adjust-lines-for-column (lines buffer data)
+  "Adjust the LINES to align with the column in BUFFER based on DATA."
+  (if icomplete-vertical-in-buffer-adjust-list
+      (let* ((column (current-column))
+             (prefix-indicator-width
+              (if icomplete-vertical-render-prefix-indicator
+                  (max (length icomplete-vertical-selected-prefix-indicator)
+                       (length icomplete-vertical-unselected-prefix-indicator))
+                0))
+             (wrapped-line (with-current-buffer buffer
+                             (save-excursion
+                               (goto-char (car data))
+                               (beginning-of-line)
+                               (count-screen-lines (point) (car data)))))
+             (window-width (+ (window-hscroll) (window-body-width)))
+             (longest-line-width (apply #'max (mapcar #'length lines)))
+             (spaces-to-add
+              (if (> wrapped-line 1)
+                  (- column (* (- wrapped-line 1) (- window-width 5)))
+                column))
+             (spaces-to-add-avoiding-scrolling
+              (if (>= (+ spaces-to-add longest-line-width prefix-indicator-width) window-width)
+                  (- spaces-to-add longest-line-width)
+                spaces-to-add)))
+
+        (dolist (l lines)
+          (add-text-properties
+           0 1 `(display ,(concat (make-string spaces-to-add-avoiding-scrolling ?\s) (substring l 0 1)))
+           l))
+        lines)
+    lines))
+
+(defun icomplete-vertical--ensure-visible-lines-inside-buffer ()
+  "Ensure the completion list is visible in regular buffers only.
+Scrolls the screen to be at least `icomplete-prospects-height' real lines
+away from the bottom.  Counts wrapped lines as real lines."
+  (unless (minibufferp)
+    (let* ((window-height (window-body-height))
+           (current-line (count-screen-lines (window-start) (point)))
+           (lines-to-bottom (- window-height current-line)))
+      (when (< lines-to-bottom icomplete-prospects-height)
+        (scroll-up (- icomplete-prospects-height lines-to-bottom))))))
+
+(defun icomplete-vertical--add-indicator-to-selected (comp)
+  "Add indicators to the selected/unselected COMP completions."
+  (if (and icomplete-vertical-render-prefix-indicator
+           (get-text-property 0 'icomplete-selected comp))
+      (concat (propertize icomplete-vertical-selected-prefix-indicator
+                          'face 'icomplete-vertical-selected-prefix-indicator-face)
+              comp)
+    (concat (propertize icomplete-vertical-unselected-prefix-indicator
+                        'face 'icomplete-vertical-unselected-prefix-indicator-face)
+            comp)))
+
 (cl-defun icomplete--render-vertical
     (comps md &aux scroll-above scroll-below
            (total-space ; number of mini-window lines available
@@ -843,12 +949,17 @@ by `group-function''s second \"transformation\" protocol."
   ;; - both nil, there is no manual scroll;
   ;; - both non-nil, there is a healthy manual scroll that doesn't need
   ;;   to be readjusted (user just moved around the minibuffer, for
-  ;;   example)l
+  ;;   example);
   ;; - non-nil and nil, respectively, a refiltering took place and we
   ;;   may need to readjust them to the new filtered `comps'.
+  (when (and icomplete-scroll
+             (not icomplete--scrolled-completions)
+             (not icomplete--scrolled-past))
+    (icomplete-vertical--ensure-visible-lines-inside-buffer))
   (when (and icomplete-scroll
              icomplete--scrolled-completions
              (null icomplete--scrolled-past))
+    (icomplete-vertical--ensure-visible-lines-inside-buffer)
     (cl-loop with preds
              for (comp . rest) on comps
              when (equal comp (car icomplete--scrolled-completions))
@@ -903,13 +1014,14 @@ by `group-function''s second \"transformation\" protocol."
      when section
      collect (propertize section 'face 'icomplete-section) into lines-aux
      and count 1 into nsections-aux
+     for comp = (icomplete-vertical--add-indicator-to-selected comp)
      when (get-text-property 0 'icomplete-selected comp)
      do (add-face-text-property 0 (length comp)
                                 'icomplete-selected-match 'append comp)
      collect (concat prefix
-                     (make-string (- max-prefix-len (length prefix)) ? )
+                     (make-string (max 0 (- max-prefix-len (length prefix))) ? )
                      (completion-lazy-hilit comp)
-                     (make-string (- max-comp-len (length comp)) ? )
+                     (make-string (max 0 (- max-comp-len (length comp))) ? )
                      suffix)
      into lines-aux
      finally (setq lines lines-aux
@@ -924,6 +1036,9 @@ by `group-function''s second \"transformation\" protocol."
                  ((> (length scroll-above) (length scroll-below)) nsections)
                  (t (min (ceiling nsections 2) (length scroll-above))))
            lines))
+    (when icomplete--in-region-buffer
+      (setq lines (icomplete-vertical--adjust-lines-for-column
+                   lines icomplete--in-region-buffer completion-in-region--data)))
     ;; At long last, render final string return value.  This may still
     ;; kick out lines at the end.
     (concat " \n"
-- 
2.48.1

[Message part 3 (text/plain, inline)]

-- 

Rahul Martim Juliato

Message #37 received at submit <at> debbugs.gnu.org (full text, mbox):

From: jixiuf <jixiuf <at> qq.com>
To: bug-gnu-emacs <at> gnu.org
Subject: Re: bug#75794: [PATCH] feat(icomplete): markers and vertical alignment
Date: Wed, 05 Mar 2025 22:28:09 +0800

Rahul Martim Juliato <rahuljuliato <at> gmail.com> writes:

>
> This patch introduces two new features that improve
> icomplete-vertical-mode, which are explained below:
>

I tried the patch, and found the face is weired when show-paren-mode
is on

Message #40 received at 75794 <at> debbugs.gnu.org (full text, mbox):

From: "jxf" <jixiuf <at> qq.com>
To: "rahuljuliato" <rahuljuliato <at> gmail.com>
Cc: 75794 <75794 <at> debbugs.gnu.org>
Subject: Re: bug#75794: [PATCH] feat(icomplete): markers and vertical alignment
Date: Wed, 5 Mar 2025 22:47:23 +0800

[Message part 1 (text/plain, inline)]

Rahul Martim Juliato <rahuljuliato <at> gmail.com&gt; writes:

&gt;
&gt; This patch introduces two new features that improve
&gt; icomplete-vertical-mode, which are explained below:
&gt;

I tried the patch and found that the face was weird when =show-paren-mode= was on.&nbsp;

[Message part 2 (text/html, inline)]

[Screenshot_-2025-03-05-22:26:20.png (application/octet-stream, attachment)]

[Screenshot_-2025-03-05-22:27:51.png (application/octet-stream, attachment)]

Message #43 received at 75794 <at> debbugs.gnu.org (full text, mbox):

From: Rahul Martim Juliato <rahuljuliato <at> gmail.com>
To: "jxf" <jixiuf <at> qq.com>
Cc: 75794 <75794 <at> debbugs.gnu.org>
Subject: Re: bug#75794: [PATCH] feat(icomplete): markers and vertical alignment
Date: Thu, 06 Mar 2025 20:10:04 -0300

"jxf" <jixiuf <at> qq.com> writes:

> I tried the patch and found that the face was weird when
> =show-paren-mode= was on. 
>

Hello there jxf!


Thanks for your interest on testing it and your feedback!


Unfortunately, I could not reproduce this behavior.


Can you reproduce it from `emacs -Q` somehow? Maybe your theme or
other package might be interfering with it? Are we sure icomplete patch
is the cause here?


If you could isolate what happened there it would be easier to check for
bugs :)


In the meantime, I made this .el file you could visit and eval after `emacs -Q`:

https://0x0.st/8uAt.el


This "overrides" the icomplete functions, meaning you can use it in any
Emacs > 30, non patched version and check the behavior.

I could not reproduce it, even changing to any of (the default) themes.


Thanks again!

PS: please ignore the message I wrongly sent just for you,
this adds the debug list on cc.

-- 

Rahul Martim Juliato

Message #46 received at 75794 <at> debbugs.gnu.org (full text, mbox):

From: Rahul Juliato <rahuljuliato <at> gmail.com>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: jxf <jixiuf <at> qq.com>, 75794 <75794 <at> debbugs.gnu.org>
Subject: Re: bug#75794: [PATCH] feat(icomplete): markers and vertical alignment
Date: Thu, 6 Mar 2025 23:00:51 -0300

[Message part 1 (text/plain, inline)]

After my last message I was thinking that anyone coming here might be a
little bit lost reading this thread (indeed, my fault).

Relevant points:

- At this time, this is the latest patch to improve icomplete-vertical:
https://debbugs.gnu.org/cgi/bugreport.cgi?att=1;filename=0001-Enhance-icomplete-vertical-mode.patch;msg=34;bug=75794

- This is a video demo: https://www.youtube.com/watch?v=ni0l6PruJEs

- (new) With the patch applied, eval this file after `emacs -Q` and test
M-x and in-buffer completion (binded to Tab): https://0x0.st/8ua3.el

Attached, some thumbs on default theme and wombat, for comparison.
[image: image.png]

[image: image.png]

[image: image.png]
[image: image.png]

Thanks,
---

Rahul Martim Juliato

[Message part 2 (text/html, inline)]

[image.png (image/png, inline)]

[image.png (image/png, inline)]

[image.png (image/png, inline)]

[image.png (image/png, inline)]

Message #49 received at 75794 <at> debbugs.gnu.org (full text, mbox):

From: jixiuf <jixiuf <at> qq.com>
To: Rahul Juliato <rahuljuliato <at> gmail.com>
Cc: 75794 <at> debbugs.gnu.org
Subject: Re: bug#75794: [PATCH] feat(icomplete): markers and vertical alignment
Date: Fri, 07 Mar 2025 21:08:58 +0800

Rahul Juliato <rahuljuliato <at> gmail.com> writes:

> - At this time, this is the latest patch to improve icomplete-vertical:
> https://debbugs.gnu.org/cgi/bugreport.cgi?att=1;filename=0001-Enhance-icomplete-vertical-mode.patch;msg=34;bug=75794
>
>
> - This is a video demo: https://www.youtube.com/watch?v=ni0l6PruJEs
>
> - (new) With the patch applied, eval this file after `emacs -Q` and test M-x and in-buffer completion (binded to Tab):
> https://0x0.st/8ua3.el
thanks

I could reproduce with:

(setq show-paren-when-point-inside-paren t)

Message #52 received at 75794 <at> debbugs.gnu.org (full text, mbox):

From: Rahul Martim Juliato <rahuljuliato <at> gmail.com>
To: jixiuf <jixiuf <at> qq.com>
Cc: eliz <at> gnu.org, 75794 <at> debbugs.gnu.org
Subject: Re: bug#75794: [PATCH] feat(icomplete): markers and vertical alignment
Date: Wed, 12 Mar 2025 21:09:18 -0300

[Message part 1 (text/plain, inline)]

jixiuf <jixiuf <at> qq.com> writes:

>
> I could reproduce with:
>
> (setq show-paren-when-point-inside-paren t)
>

Thanks for your feedback!

Please find attached a new version of this patch.

Could you try it and tell if this one fixes this bug? For me, it did
fixed it! :)

-- 

Rahul Martim Juliato

[0001-Enhance-icomplete-vertical-mode-2025-03-12.patch (text/x-diff, inline)]

From e6f4d614b79949ecf1799e4cc4dc312fd33a5bbd Mon Sep 17 00:00:00 2001
From: Rahul Martim Juliato <rahul.juliato <at> gmail.com>
Date: Wed, 12 Mar 2025 21:00:27 -0300
Subject: [PATCH] Enhance 'icomplete-vertical-mode'

New user options have been added to enhance 'icomplete-vertical-mode':

 + 'icomplete-vertical-in-buffer-adjust-list': Aligns in-buffer
completion to the original cursor column.
 + 'icomplete-vertical-render-prefix-indicator': When enabled, adds a
prefix indicator to completion candidates.
 + 'icomplete-vertical-selected-prefix-indicator': Specifies the prefix
string for the selected candidate.
 + 'icomplete-vertical-unselected-prefix-indicator': Specifies the prefix
string for unselected candidates.

New faces introduced:

 + 'icomplete-vertical-selected-prefix-indicator-face': Controls the
appearance of the selected candidate prefix.
 + 'icomplete-vertical-unselected-prefix-indicator-face': Controls the
appearance of unselected candidate prefixes.

* etc/NEWS: Document the new user options and faces.
* lisp/icomplete.el(icomplete-vertical-mode): Implement the new options
---
 etc/NEWS          |  19 ++++++++
 lisp/icomplete.el | 119 ++++++++++++++++++++++++++++++++++++++++++++--
 2 files changed, 135 insertions(+), 3 deletions(-)

diff --git a/etc/NEWS b/etc/NEWS
index 258f0dcc4ba..bf4afb8dac0 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -269,6 +269,25 @@ return value windows whose buffers share their text with BUFFER-OR-NAME.
 With such an entry, 'display-buffer-reuse-window' may also choose a
 window whose buffer shares text with the buffer to display.
 
++++
+*** New user options for 'icomplete-vertical-mode'.
+New user options have been added to enhance 'icomplete-vertical-mode':
+
+ - 'icomplete-vertical-in-buffer-adjust-list': Aligns in-buffer
+    completion to the original cursor column.
+ - 'icomplete-vertical-render-prefix-indicator': When enabled, adds a
+    prefix indicator to completion candidates.
+ - 'icomplete-vertical-selected-prefix-indicator': Specifies the prefix
+    string for the selected candidate.
+ - 'icomplete-vertical-unselected-prefix-indicator': Specifies the prefix
+    string for unselected candidates.
+
+New faces:
+
+ - 'icomplete-vertical-selected-prefix-indicator-face': Controls the
+    appearance of the selected candidate prefix.
+ - 'icomplete-vertical-unselected-prefix-indicator-face': Controls the
+    appearance of unselected candidate prefixes.
 
 ** Frames
 
diff --git a/lisp/icomplete.el b/lisp/icomplete.el
index c58bffbb36b..fca941a09db 100644
--- a/lisp/icomplete.el
+++ b/lisp/icomplete.el
@@ -115,6 +115,18 @@ icomplete-section
   "Face used by `icomplete-vertical-mode' for the section title."
   :version "28.1")
 
+(defface icomplete-vertical-selected-prefix-indicator-face
+  '((t :inherit font-lock-keyword-face :weight bold :foreground "cyan"))
+  "Face used for the prefix set by `icomplete-vertical-selected-prefix-indicator'."
+  :group 'icomplete
+  :version "31.1")
+
+(defface icomplete-vertical-unselected-prefix-indicator-face
+  '((t :inherit font-lock-keyword-face :weight normal :foreground "gray"))
+  "Face used for the prefix set by `icomplete-vertical-unselected-prefix-indicator'."
+  :group 'icomplete
+  :version "31.1")
+
 ;;;_* User Customization variables
 (defcustom icomplete-prospects-height 2
   ;; We used to compute how many lines 100 characters would take in
@@ -166,6 +178,46 @@ icomplete-minibuffer-setup-hook
 icompletion is occurring."
   :type 'hook)
 
+(defcustom icomplete-vertical-in-buffer-adjust-list nil
+  "Control whether in-buffer completion should align the cursor position.
+If this is t and `icomplete-in-buffer' is t, and `icomplete-vertical-mode'
+is activated, the in-buffer vertical completions are shown aligned to the
+cursor position when the completion started, not on the first column, as
+the default behaviour."
+  :type 'boolean
+  :group 'icomplete
+  :version "31.1")
+
+(defcustom icomplete-vertical-render-prefix-indicator nil
+  "Control whether a indicator is added as a prefix to each candidate.
+If this is t and `icomplete-vertical-mode' is activated, a indicator,
+controlled by `icomplete-vertical-selected-prefix-indicator' is shown
+as a prefix to the current under selection candidate, while the
+remaining of the candidates will receive the indicator controlled
+by `icomplete-vertical-unselected-prefix-indicator'."
+  :type 'boolean
+  :group 'icomplete
+  :version "31.1")
+
+(defcustom icomplete-vertical-selected-prefix-indicator "» "
+  "Prefix string used to mark the selected completion candidate.
+If `icomplete-vertical-render-prefix-indicator' is t, the string
+defined here is used as a prefix of the currently selected entry in the
+list.  It can be further customized by the face
+`icomplete-vertical-selected-prefix-indicator-face'."
+  :type 'string
+  :group 'icomplete
+  :version "31.1")
+
+(defcustom icomplete-vertical-unselected-prefix-indicator "  "
+  "Prefix string used on the unselected completion candidates.
+If `icomplete-vertical-render-prefix-indicator' is t, the string
+defined here is used as a prefix for all unselected entries in the list.
+list.  It can be further customized by the face
+`icomplete-vertical-unselected-prefix-indicator-face'."
+  :type 'string
+  :group 'icomplete
+  :version "31.1")
 
 ;;;_* Initialization
 
@@ -828,6 +880,58 @@ icomplete--augment
                  else collect (list tr prefix suffix ))
       annotated)))
 
+(defun icomplete-vertical--adjust-lines-for-column (lines buffer data)
+  "Adjust the LINES to align with the column in BUFFER based on DATA."
+  (if icomplete-vertical-in-buffer-adjust-list
+      (let* ((column (current-column))
+             (prefix-indicator-width
+              (if icomplete-vertical-render-prefix-indicator
+                  (max (length icomplete-vertical-selected-prefix-indicator)
+                       (length icomplete-vertical-unselected-prefix-indicator))
+                0))
+             (wrapped-line (with-current-buffer buffer
+                             (save-excursion
+                               (goto-char (car data))
+                               (beginning-of-line)
+                               (count-screen-lines (point) (car data)))))
+             (window-width (+ (window-hscroll) (window-body-width)))
+             (longest-line-width (apply #'max (mapcar #'length lines)))
+             (spaces-to-add
+              (if (> wrapped-line 1)
+                  (- column (* (- wrapped-line 1) (- window-width 5)))
+                column))
+             (spaces-to-add-avoiding-scrolling
+              (if (>= (+ spaces-to-add longest-line-width prefix-indicator-width) window-width)
+                  (- spaces-to-add longest-line-width)
+                spaces-to-add)))
+
+        (mapcar (lambda (line)
+                  (concat (make-string spaces-to-add-avoiding-scrolling ?\s) line))
+                lines))
+    lines))
+
+(defun icomplete-vertical--ensure-visible-lines-inside-buffer ()
+  "Ensure the completion list is visible in regular buffers only.
+Scrolls the screen to be at least `icomplete-prospects-height' real lines
+away from the bottom.  Counts wrapped lines as real lines."
+  (unless (minibufferp)
+    (let* ((window-height (window-body-height))
+           (current-line (count-screen-lines (window-start) (point)))
+           (lines-to-bottom (- window-height current-line)))
+      (when (< lines-to-bottom icomplete-prospects-height)
+        (scroll-up (- icomplete-prospects-height lines-to-bottom))))))
+
+(defun icomplete-vertical--add-indicator-to-selected (comp)
+  "Add indicators to the selected/unselected COMP completions."
+  (if (and icomplete-vertical-render-prefix-indicator
+           (get-text-property 0 'icomplete-selected comp))
+      (concat (propertize icomplete-vertical-selected-prefix-indicator
+                          'face 'icomplete-vertical-selected-prefix-indicator-face)
+              comp)
+    (concat (propertize icomplete-vertical-unselected-prefix-indicator
+                        'face 'icomplete-vertical-unselected-prefix-indicator-face)
+            comp)))
+
 (cl-defun icomplete--render-vertical
     (comps md &aux scroll-above scroll-below
            (total-space ; number of mini-window lines available
@@ -843,12 +947,17 @@ icomplete--render-vertical
   ;; - both nil, there is no manual scroll;
   ;; - both non-nil, there is a healthy manual scroll that doesn't need
   ;;   to be readjusted (user just moved around the minibuffer, for
-  ;;   example)l
+  ;;   example);
   ;; - non-nil and nil, respectively, a refiltering took place and we
   ;;   may need to readjust them to the new filtered `comps'.
+  (when (and icomplete-scroll
+             (not icomplete--scrolled-completions)
+             (not icomplete--scrolled-past))
+    (icomplete-vertical--ensure-visible-lines-inside-buffer))
   (when (and icomplete-scroll
              icomplete--scrolled-completions
              (null icomplete--scrolled-past))
+    (icomplete-vertical--ensure-visible-lines-inside-buffer)
     (cl-loop with preds
              for (comp . rest) on comps
              when (equal comp (car icomplete--scrolled-completions))
@@ -903,13 +1012,14 @@ icomplete--render-vertical
      when section
      collect (propertize section 'face 'icomplete-section) into lines-aux
      and count 1 into nsections-aux
+     for comp = (icomplete-vertical--add-indicator-to-selected comp)
      when (get-text-property 0 'icomplete-selected comp)
      do (add-face-text-property 0 (length comp)
                                 'icomplete-selected-match 'append comp)
      collect (concat prefix
-                     (make-string (- max-prefix-len (length prefix)) ? )
+                     (make-string (max 0 (- max-prefix-len (length prefix))) ? )
                      (completion-lazy-hilit comp)
-                     (make-string (- max-comp-len (length comp)) ? )
+                     (make-string (max 0 (- max-comp-len (length comp))) ? )
                      suffix)
      into lines-aux
      finally (setq lines lines-aux
@@ -924,6 +1034,9 @@ icomplete--render-vertical
                  ((> (length scroll-above) (length scroll-below)) nsections)
                  (t (min (ceiling nsections 2) (length scroll-above))))
            lines))
+    (when icomplete--in-region-buffer
+      (setq lines (icomplete-vertical--adjust-lines-for-column
+                   lines icomplete--in-region-buffer completion-in-region--data)))
     ;; At long last, render final string return value.  This may still
     ;; kick out lines at the end.
     (concat " \n"
-- 
2.39.5

Message #55 received at 75794 <at> debbugs.gnu.org (full text, mbox):

From: jixiuf <jixiuf <at> qq.com>
To: Rahul Martim Juliato <rahuljuliato <at> gmail.com>
Cc: 75794 <at> debbugs.gnu.org
Subject: Re: bug#75794: [PATCH] feat(icomplete): markers and vertical alignment
Date: Thu, 13 Mar 2025 13:20:27 +0800

> Please find attached a new version of this patch.
>
> Could you try it and tell if this one fixes this bug? For me, it did
> fixed it! :)

Thanks, it is fixed for me too.

Message #58 received at 75794 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Rahul Martim Juliato <rahuljuliato <at> gmail.com>
Cc: jixiuf <at> qq.com, 75794 <at> debbugs.gnu.org
Subject: Re: bug#75794: [PATCH] feat(icomplete): markers and vertical alignment
Date: Sat, 15 Mar 2025 14:10:45 +0200

> From: Rahul Martim Juliato <rahuljuliato <at> gmail.com>
> Cc: eliz <at> gnu.org, 75794 <at> debbugs.gnu.org
> Date: Wed, 12 Mar 2025 21:09:18 -0300
> 
> > I could reproduce with:
> >
> > (setq show-paren-when-point-inside-paren t)
> >
> 
> Thanks for your feedback!
> 
> Please find attached a new version of this patch.
> 
> Could you try it and tell if this one fixes this bug? For me, it did
> fixed it! :)

Thanks, please see a few minor comments below.

> >From e6f4d614b79949ecf1799e4cc4dc312fd33a5bbd Mon Sep 17 00:00:00 2001
> From: Rahul Martim Juliato <rahul.juliato <at> gmail.com>
> Date: Wed, 12 Mar 2025 21:00:27 -0300
> Subject: [PATCH] Enhance 'icomplete-vertical-mode'
> 
> New user options have been added to enhance 'icomplete-vertical-mode':
> 
>  + 'icomplete-vertical-in-buffer-adjust-list': Aligns in-buffer
> completion to the original cursor column.
>  + 'icomplete-vertical-render-prefix-indicator': When enabled, adds a
> prefix indicator to completion candidates.
>  + 'icomplete-vertical-selected-prefix-indicator': Specifies the prefix
> string for the selected candidate.
>  + 'icomplete-vertical-unselected-prefix-indicator': Specifies the prefix
> string for unselected candidates.
> 
> New faces introduced:
> 
>  + 'icomplete-vertical-selected-prefix-indicator-face': Controls the
> appearance of the selected candidate prefix.
>  + 'icomplete-vertical-unselected-prefix-indicator-face': Controls the
> appearance of unselected candidate prefixes.
> 
> * etc/NEWS: Document the new user options and faces.
> * lisp/icomplete.el(icomplete-vertical-mode): Implement the new options

Please format the commit log message according to our conventions.
Specifically:

  . lines not longer than 63 characters
  . changes described with their file names, not separately
  . Each change description a complete sentence ending in a period

> --- a/etc/NEWS
> +++ b/etc/NEWS
> @@ -269,6 +269,25 @@ return value windows whose buffers share their text with BUFFER-OR-NAME.
>  With such an entry, 'display-buffer-reuse-window' may also choose a
>  window whose buffer shares text with the buffer to display.
>  
> ++++
> +*** New user options for 'icomplete-vertical-mode'.
> +New user options have been added to enhance 'icomplete-vertical-mode':
> +
> + - 'icomplete-vertical-in-buffer-adjust-list': Aligns in-buffer
> +    completion to the original cursor column.
> + - 'icomplete-vertical-render-prefix-indicator': When enabled, adds a
> +    prefix indicator to completion candidates.
> + - 'icomplete-vertical-selected-prefix-indicator': Specifies the prefix
> +    string for the selected candidate.
> + - 'icomplete-vertical-unselected-prefix-indicator': Specifies the prefix
> +    string for unselected candidates.
> +
> +New faces:
> +
> + - 'icomplete-vertical-selected-prefix-indicator-face': Controls the
> +    appearance of the selected candidate prefix.
> + - 'icomplete-vertical-unselected-prefix-indicator-face': Controls the
> +    appearance of unselected candidate prefixes.

Please format NEWS entries according to our conventions (it's a
derivative of Outline mode, using "*" for heading line indentations).

Also, since you haven't updated any manuals, the NEWS entries should
not be marked with "+++".

> +(defface icomplete-vertical-unselected-prefix-indicator-face
> +  '((t :inherit font-lock-keyword-face :weight normal :foreground "gray"))
> +  "Face used for the prefix set by `icomplete-vertical-unselected-prefix-indicator'."

This doc string is too long.  Please keep the lines in doc strings
below 80 characters.

> +(defcustom icomplete-vertical-render-prefix-indicator nil
> +  "Control whether a indicator is added as a prefix to each candidate.
                      ^^^^^^^^^^^
"an indicator"

> +If this is t and `icomplete-vertical-mode' is activated, a indicator,
                                                            ^^^^^^^^^^^
Likewise.

> +controlled by `icomplete-vertical-selected-prefix-indicator' is shown
> +as a prefix to the current under selection candidate, while the
> +remaining of the candidates will receive the indicator controlled
> +by `icomplete-vertical-unselected-prefix-indicator'."
> +  :type 'boolean
> +  :group 'icomplete
> +  :version "31.1")
> +
> +(defcustom icomplete-vertical-selected-prefix-indicator "» "

Is it wise to default to a non_ASCII character without checking first
that it's supported by the display?

> +  "Prefix string used to mark the selected completion candidate.
> +If `icomplete-vertical-render-prefix-indicator' is t, the string
> +defined here is used as a prefix of the currently selected entry in the
> +list.  It can be further customized by the face
> +`icomplete-vertical-selected-prefix-indicator-face'."
> +  :type 'string
> +  :group 'icomplete
> +  :version "31.1")

Regardless of the default value, the options should include an ASCII
and a non-ASCII strings.

Message #61 received at 75794 <at> debbugs.gnu.org (full text, mbox):

From: Rahul Juliato <rahuljuliato <at> gmail.com>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: jixiuf <at> qq.com, 75794 <at> debbugs.gnu.org
Subject: Re: bug#75794: [PATCH] feat(icomplete): markers and vertical alignment
Date: Sat, 15 Mar 2025 11:14:04 -0300

Thanks for your review Eli.

I'll fix it in my next 'free time slot' :)

Message #64 received at 75794 <at> debbugs.gnu.org (full text, mbox):

From: Rahul Martim Juliato <rahuljuliato <at> gmail.com>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: Rahul Martim Juliato <rahuljuliato <at> gmail.com>, jixiuf <at> qq.com,
 75794 <at> debbugs.gnu.org
Subject: Re: bug#75794: [PATCH] feat(icomplete): markers and vertical alignment
Date: Wed, 26 Mar 2025 23:29:36 -0300

[Message part 1 (text/plain, inline)]

>
> Please format the commit log message according to our conventions.
> Specifically:
>
>   . lines not longer than 63 characters
>   . changes described with their file names, not separately
>   . Each change description a complete sentence ending in a period
>

I think I did it right this time, if you could please check if this is
nice enough :)

>
> Please format NEWS entries according to our conventions (it's a
> derivative of Outline mode, using "*" for heading line indentations).
>
> Also, since you haven't updated any manuals, the NEWS entries should
> not be marked with "+++".
>

Removed the +++, tried to follow examples from other NEWS.

>> +  "Face used for the prefix set by `icomplete-vertical-unselected-prefix-indicator'."
>
> This doc string is too long.  Please keep the lines in doc strings
> below 80 characters.
>

Done.

>> +(defcustom icomplete-vertical-render-prefix-indicator nil
>> +  "Control whether a indicator is added as a prefix to each candidate.
>                       ^^^^^^^^^^^
> "an indicator"
>

Done.

>> +If this is t and `icomplete-vertical-mode' is activated, a indicator,
>                                                             ^^^^^^^^^^^
> Likewise.
>

Done

>
> Is it wise to default to a non_ASCII character without checking first
> that it's supported by the display?
>

Agreed.  In this version I changed the
`icomplete-vertical-selected-prefix-indicator' default to first check if
the » is displayable, suggesting > otherwise.

> Regardless of the default value, the options should include an ASCII
> and a non-ASCII strings.

Done as state above.

--

Please find attached the latest version of this patch:
`0001-Enhance-icomplete-vertical-mode-2025-03-26.patch'

Sorry for the delayed response.

-- 

Rahul Martim Juliato

[0001-Enhance-icomplete-vertical-mode-2025-03-26.patch (text/x-diff, attachment)]

Message #67 received at 75794 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Rahul Martim Juliato <rahuljuliato <at> gmail.com>
Cc: jixiuf <at> qq.com, 75794 <at> debbugs.gnu.org
Subject: Re: bug#75794: [PATCH] feat(icomplete): markers and vertical alignment
Date: Sat, 29 Mar 2025 13:15:54 +0300

> From: Rahul Martim Juliato <rahuljuliato <at> gmail.com>
> Cc: Rahul Martim Juliato <rahuljuliato <at> gmail.com>,  jixiuf <at> qq.com,
>   75794 <at> debbugs.gnu.org
> Date: Wed, 26 Mar 2025 23:29:36 -0300
> 
> Please find attached the latest version of this patch:
> `0001-Enhance-icomplete-vertical-mode-2025-03-26.patch'

Thanks.  Compiling this produces the following warnings:

    ELC      icomplete.elc

  In icomplete--render-vertical:
  icomplete.el:1015:11: Warning: Unused lexical variable `comp'
  icomplete.el:1019:10: Warning: Unused lexical variable `comp'

Can you fix this, please?

Also, a couple of minor nits:

> --- a/etc/NEWS
> +++ b/etc/NEWS
> @@ -269,6 +269,23 @@ return value windows whose buffers share their text with BUFFER-OR-NAME.
>  With such an entry, 'display-buffer-reuse-window' may also choose a
>  window whose buffer shares text with the buffer to display.
>  
> +*** New user options for 'icomplete-vertical-mode'.
> +New user options have been added to enhance 'icomplete-vertical-mode':
> +- 'icomplete-vertical-in-buffer-adjust-list' aligns in-buffer
> +  completion to the original cursor column.
> +- 'icomplete-vertical-render-prefix-indicator' adds a prefix indicator
> +  to completion candidates.
> +- 'icomplete-vertical-selected-prefix-indicator' specifies the prefix
> +  string for the selected candidate.
> +- 'icomplete-vertical-unselected-prefix-indicator' specifies the prefix
> +  string for unselected candidates.
> +
> +*** New faces for 'icomplete-vertical-mode'.
> +New faces have been added to 'icomplete-vertical-mode':
> +- 'icomplete-vertical-selected-prefix-indicator-face' controls the
> +  appearance of the selected candidate prefix.
> +- 'icomplete-vertical-unselected-prefix-indicator-face' controls the
> +  appearance of unselected candidate prefixes.

These entries should be under "Changes in Specialized Modes and
Packages in Emacs 31.1", in a new sub-section "Icomplete".

> +(defcustom icomplete-vertical-in-buffer-adjust-list nil
> +  "Control whether in-buffer completion should align the cursor position.
> +If this is t and `icomplete-in-buffer' is t, and `icomplete-vertical-mode'
> +is activated, the in-buffer vertical completions are shown aligned to the
> +cursor position when the completion started, not on the first column, as
> +the default behaviour."
               ^^^^^^^^^
We use the US English spelling: "behavior".

Message #70 received at 75794 <at> debbugs.gnu.org (full text, mbox):

From: Rahul Martim Juliato <rahuljuliato <at> gmail.com>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: Rahul Martim Juliato <rahuljuliato <at> gmail.com>, jixiuf <at> qq.com,
 75794 <at> debbugs.gnu.org
Subject: Re: bug#75794: [PATCH] feat(icomplete): markers and vertical alignment
Date: Sat, 29 Mar 2025 13:01:51 -0300

[Message part 1 (text/plain, inline)]

>   In icomplete--render-vertical:
>   icomplete.el:1015:11: Warning: Unused lexical variable `comp'
>   icomplete.el:1019:10: Warning: Unused lexical variable `comp'
>
> Can you fix this, please?

Fixed.

> These entries should be under "Changes in Specialized Modes and
> Packages in Emacs 31.1", in a new sub-section "Icomplete".
>

Moved to the right section.

> We use the US English spelling: "behavior".

Oops, fixed.

--

Please find attached the newest version of this patch.

[0001-Enhance-icomplete-vertical-mode-2025-03-29.patch (text/x-diff, attachment)]

[Message part 3 (text/plain, inline)]

-- 

Rahul Martim Juliato

Message #75 received at 75794-done <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Rahul Martim Juliato <rahuljuliato <at> gmail.com>
Cc: 75794-done <at> debbugs.gnu.org, jixiuf <at> qq.com
Subject: Re: bug#75794: [PATCH] feat(icomplete): markers and vertical alignment
Date: Sat, 29 Mar 2025 19:48:24 +0300

> From: Rahul Martim Juliato <rahuljuliato <at> gmail.com>
> Cc: Rahul Martim Juliato <rahuljuliato <at> gmail.com>,  jixiuf <at> qq.com,
>   75794 <at> debbugs.gnu.org
> Date: Sat, 29 Mar 2025 13:01:51 -0300
> 
> >   In icomplete--render-vertical:
> >   icomplete.el:1015:11: Warning: Unused lexical variable `comp'
> >   icomplete.el:1019:10: Warning: Unused lexical variable `comp'
> >
> > Can you fix this, please?
> 
> Fixed.
> 
> > These entries should be under "Changes in Specialized Modes and
> > Packages in Emacs 31.1", in a new sub-section "Icomplete".
> >
> 
> Moved to the right section.
> 
> > We use the US English spelling: "behavior".
> 
> Oops, fixed.
> 
> --
> 
> Please find attached the newest version of this patch.

Thanks, installed on the master branch, and closing the bug.

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.