Toggle alignment of all matching entries in Find all results

[rohitab]

A new feature was recently added to Far, that allows you to vertically align all the matching entries using Ctrl+Numpad5/Ctrl+Clear key. See PR #789 by @MKadaner for details.

This discussion is to weigh the pros and cons of using Ctrl+Numpad5 to toggle between center-aligned and left-aligned.

Current Design

When you press Ctrl+Numpad5, the matching entries are center-aligned. Pressing Ctrl+Numpad5 again has no effect. You can press Alt+Home to restore the default left-alignment, and Alt+End to right-align the items. You can also use a number of other keys like Alt+Shift+Left to manually align the items.

Proposed Design

When you press Ctrl+Numpad5, the matching entries are center-aligned. Pressing Ctrl+Numpad5 again would align the items to the left (default alignment). Pressing it again would center-align the items. So, Ctrl+Numpad5 would work as a toggle between center and left alignment.

This would allow you to quickly switch between center and left-alignment, without having to use a different key combination. It has some other benefits like being able to quickly check line numbers that may be hidden when the items are center-aligned.

Please see the original discussion starting from #789 (comment) for more information.

Macro for Testing Proposed Design

I have written a Lua macro that implements the proposed design. You can download it from Editor.FindAll.ToggleAlignment.lua.zip. Once you install the macro, Ctrl+Numpad5 will toggle the matching entries (annotation) alignment from center to left and vice-versa.

Macro Installation Instructions

1. Extract Editor.FindAll.ToggleAlignment.lua from the attached archive Editor.FindAll.ToggleAlignment.lua.zip
2. Copy Editor.FindAll.ToggleAlignment.lua to %FARPROFILE%\Macros\scripts
3. Run macro:load to reload macros, or restart Far.

Macro Source Code

--[[
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Toggle Annotation Alignment in Editor.
(c) 2024 Rohitab Batra <rohitab@rohitab.com>
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Toggle vertical alignment of annotations (found text) in Find all results.

Pressing Ctrl+Clear (Ctrl+Numpad5) will toggle alignment as follows:
  * If the annotations are center-aligned, they will be left-aligned
  * If the annotations are not center-aligned, they will be center-aligned.

You can change this behavior by setting ALWAYS_TOGGLE to true. See below.

--]]


-- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-- USER CONFIGURATION - Make changes if required.
-- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

-- If true, alignment is always toggled, regardless of the current state.
-- For example, if the user presses Ctrl+Clear to center-align the annotations,
-- then manually changes the alignment, pressing Ctrl+Clear again would:
--   * Left-align the annotations if ALWAYS_TOGGLE is true.
--   * Center-align the annotations if ALWAYS_TOGGLE is false.
local ALWAYS_TOGGLE = false


-- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-- DO NOT make any changes after this, unless you know what you're doing.
-- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

-- Initialization
local F = far.Flags

-- Dialog UUIDs
local EDITOR_FIND_ALL_LIST_UUID = win.Uuid(far.Guids.EditorFindAllListId)

-- Global variables
local Globals = {
    annotationsAligned = false,  -- True, if annotations are center-aligned.
}


-- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-- Toggle annotation alignment in Find all results.
-- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Macro {
    area = "Menu";
    key = "CtrlClear";
    id = "ABAC55B4-8EAC-4ECD-9F9D-C32036CF34F1";
    description = "Toggle annotation alignment in Find all results";
    condition = function()
        return Menu.Id == far.Guids.EditorFindAllListId
    end;
    action = function()
        -- Toggle alignment and update state.
        Keys(Globals.annotationsAligned and "AltHome" or "CtrlClear")
        Globals.annotationsAligned = not Globals.annotationsAligned
    end;
}


-- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-- Detect alignment change in Find all results dialog, if ALWAYS_TOGGLE is false.
-- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
if not ALWAYS_TOGGLE then
    Macro {
        area = "Menu";
        key = [[/(([LR]Ctrl)(([LR]Alt)|(Shift))(Left|Right|Num4|Num6))]]..
              [[|([LR]Alt(Shift)?(Home|End|Left|Right|Num7|Num1|Num4|Num6))]]..
              [[|(([LR]Ctrl)?(MsWheelLeft|MsWheelRight))/]];
        id = "ABAC55B4-8EAC-4ECD-9F9D-C32036CF34F2";
        description = "Detect alignment change in Find all results";
        condition = function()
            return Menu.Id == far.Guids.EditorFindAllListId and Globals.annotationsAligned
        end;
        action = function()
            Keys(akey(1, 1))
            -- User changed alignment manually, so we'll assume they are no longer aligned.
            Globals.annotationsAligned = false
        end;
    }
end


-- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-- Initialize annotation alignment when the Find all results dialog is opened.
-- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Event {
    group = "DialogEvent";
    id = "ABAC55B4-8EAC-4ECD-9F9D-C32036CF34F3";
    description = "Initialize annotation alignment in Find all results";
    condition = function(Event, FarDialogEvent)
        return Event == F.DE_DLGPROCINIT and FarDialogEvent.Msg == F.DN_INITDIALOG
    end;
    action = function(Event, FarDialogEvent)
        local dialog = FarDialogEvent.hDlg
        local info = dialog:send(F.DM_GETDIALOGINFO)
        if info and info.Id == EDITOR_FIND_ALL_LIST_UUID then
            -- Annotations are not aligned when the dialog is initially opened.
            Globals.annotationsAligned = false
        end
    end;
}

The macro has a flag ALWAYS_TOGGLE. You can set it to true to test the behavior discussed in the first paragraph of #789 (comment). My preference is the default behavior with this flag set to false.

Attached Files

• Editor.FindAll.ToggleAlignment.lua.zip

[rohitab]

MKadaner commented here

Did you notice that if the pattern is found on the same line more than once, currently Far inserts so many items in the "Find all" list, each with its unique position number (next to the line number). I actually hate this behavior.
...
As such, I want to change the UX and show in the list one item for each matching line with all found occurrences highlighted.

I disliked it as well, originally. But now I have gotten very used to it. In fact, I have scripts that use the line/column position of the matching entries. So, if you decide to change this behavior, please have an option where the original behavior can be restored, or some other way to retrieve the line/column position of all matching entries. Maybe this needs its own discussion too 😟

[MKadaner]

Noted. Since it's a serious UX change, this feature will surely need more consideration. Let's discuss it separately when I get to it. Something as simple as a far:config flag is an option. I like the idea of "some other way to retrieve the line/column position of all matching entries." I can think of a Plugin API which returns this information to a macro. However, my understanding of overall style of Far Plugin API is very vague. If you can suggest what should reasonably be exposed to Lua and how, it might help. I can think of a generic API which provides access to VMenu items, including annotations, but I need help with how to expose this to in a natural way.

[rohitab]

I agree. Once you make a decision on how to implement it, we can come up with an API. It would definitely require input from more experienced users.

[alabuzhev]

Did you notice that if the pattern is found on the same line more than once, currently Far inserts so many items in the "Find all" list, each with its unique position number (next to the line number). I actually hate this behavior.

FYI this behavior is completely intentional.
Strings can be long. Occurrences can be numerous.
I have better things to do than scrolling and thoroughly inspecting each menu item manually.

[MKadaner]

With a way to quickly jump between multiple occurrences, the UX may be better than just scrolling the long item left and right. I regularly work with many long items having multiple occurrences. I have better things to do than scrolling menu up and down to get to the next matching line. 🙂 But I hear you as well. Probably the best would be to be able to quickly toggle these modes, but with the current implementation it may be tricky.

Anyway, this is not something I am going to plunge into right away. Let all of us think of it in background.

[MKadaner]

Wow! So, it can all be done in a macro. Maybe we will just go this way and close this discussion? 😀

Joking aside, I thought about toggling alignment, and decided that I would not like it. Thus, a macro implementation makes perfect sense to me. You will use it, and I will not. Everyone is happy.

Your macro, as it is, has one minor issue. The keys which shift individual items, like Alt+Shif+Arrows, may do nothing if the current item cannot be moved in the required direction. In this case, the Globals.annotationsAligned flag will get out of sync with the actual state of annotation alignment. I believe that it would be very tricky to write a macro which is free of such corner case issues without access to the actual VMenu state.

So, what do you think about a new Plugin API which returns the actual, current state of annotation alignment, effectively, the value of bool IsAligned flag I proposed in my comment. Then your macro will become a one liner:

Keys(IsAligned and "AltHome" or "CtrlClear")

(Well, another line or two will be required to invoke the new API.)

If you like the idea, could you please point me to an existing Lua API which retrieves some kind of state from a UI control? I've never implemented a Lua API, and my usual method of learning is implementing something following an existing pattern.

[rohitab]

Maybe we will just go this way and close this discussion? 😀

Nice try!

Then your macro will become a one liner:

That's how I planned to implement the macro originally, but there was no way to get the alignment state, so I had to go with the current implementation.

I believe that it would be very tricky to write a macro which is free of such corner case issues without access to the actual VMenu state.

That's true. With the current macro, if the user pressed Alt+Shift+Left followed by Alt+Shift+Right, the items would be back to the original alignment, but Globals.annotationsAligned is reset, so pressing Ctrl+Numpad5 will do nothing.

So, what do you think about a new Plugin API which returns the actual, current state of annotation alignment, effectively, the value of bool IsAligned flag I proposed in my comment.

That will definitely make the macro simpler. But would you keep this flag synchronized with the alignment? If the user pressed Ctrl+Numpad5, then pressed Alt+Shift+Left, would you return isAligned == false, and if the user then pressed Alt+Shift+Right, would you then return isAligned == true? It doesn't seem to be worth the effort, especially if other people aren't interested in this feature.

could you please point me to an existing Lua API which retrieves some kind of state from a UI control?

You can look at editor_GetTitle which, once added to editor_funcs can be called by Lua macros using editor.GetTitle(...) function.

Note that there are two API's in Lua - the LuaFAR API and the Macro API. The above editor.GetTitle(...) is LuaFAR. The below Menu.Id is Macro API. I believe the Macro API is old and all new API's are implemented using LuaFAR. But, I could be wrong.

Most of the existing menu functions are implemented using the Macro API. For example, in Lua, the property Menu.Id is retrieved by sending 0x80844, which is MCODE_V_MENUINFOID. This value is then processed and forwarded to VMenu::VMProcess which handles it and returns the Id.

[MKadaner]

Thank you for the thorough explanations. It will help a lot.

But would you keep this flag synchronized with the alignment? ...

This scenario is indeed problematic. However, I have a trick up my sleeve how to track the state without scanning all items every time. We'll see if I can pull it.

I am going to finish and push another minor feature which is already in the pipeline and will get to this new API next.

[HamRusTal]

If adding new APIs to retrieve menu alignment from FAR, please consider it providing more data than a single bool. E.g. Left/Center/Right/Match/None.

[MKadaner]

So far, I thought about Aligned/Not aligned, and if Aligned, the align position. Left/Right sounds like a good idea as well. What do you mean "Center" and "Match"?

@rohitab said:

I believe the Macro API is old and all new API's are implemented using LuaFAR. But, I could be wrong.

Should this API be implemented as Macro API or LuaFAR, or both?

[HamRusTal]

What do you mean "Center" and "Match"?

“(Aligned by) Match” is what you added by #789. “(Align) Center” seems to be not implemented (and not needed) in Far, so please ignore it.

[HamRusTal]

@MKadaner If you happen to add a set of alignment values (e.g. an enumeration) for generic use, please do add Center there as some dialogs FAR exposes via its API (e.g. the one accessed by PluginStartupInfo::Message) center their items horizontally by default, and this can be changed by flags in the function parameters.

[MKadaner]

Noted. However, to be sure everything done correctly, I'll tag you on that PR when I have it out. At least, I'll try to remember.

[BestiaPL]

Current Design

When you press Ctrl+Numpad5, the matching entries are center-aligned. Pressing Ctrl+Numpad5 again has no effect. You can press Alt+Home to restore the default left-alignment, and Alt+End to right-align the items. You can also use a number of other keys like Alt+Shift+Left to manually align the items.

It is good that you described all the shortcuts that are available in the results window.

Now you would still need to add them to the help file in the @FindAllMenu section, and improve the translation of the program window (in Polish, instead of "Grey +" it should say "Szary+"), etc..

BTW - the space between "Grey +" and "Grey -" is a bit confusing, and should be unified everywhere to "Grey+" and "Grey-" - what do you think?

[HamRusTal]

need to add them to the help file in the @FindAllMenu section

Actually, Alt(+Shift)+Home/Left/Right/End are common to all menus and are documented (along with a few others) in the respective Help page (@MenuCmd) linked at the end of the page you're referring to.

[rohitab]

@BestiaPL I agree with using Gray+ instead of Gray + as the space is confusing, especially when the keys are listed together, like in the screenshot you posted.

Since we're using Numpad5, how about using Numpad+ instead of Gray+? A lot of keyboards don't have separate colors for these keys. Just a thought.

[MKadaner]

Apparently, Gray + comes from MKeyAdd in farlang.templ.m4 (and Gray - comes from MKeySubtract). These definitions are used in quite a few places, so we should not change them on a whim. While Gray+ is probably more natural in the "Find all" list, it may appear strange in some other places.

In the (English) help file, these keys are spelled with highlight (e.g., #Gray +#), so they cause less confusion. When these keys are prefixed with Shift or Alt, they are spelled with angle brackets, like this

#Shift+<Gray +># selects, and #Shift+<Gray -># deselects all items.

Maybe we should adopt the same notation in farlang.templ.m4? Once again, keep in mind that this change will affect multiple UI elements.