gh-802: Macro API to report VMenu alignment state. Part 2: Plumbing and Lua API.

[MKadaner]

Summary

Surfacing the state maintained by vmenu_horizontal_tracker to Lua macro.

References

• Toggle alignment of all matching entries in Find all results #802
• gh-802: Macro API to report VMenu alignment state. Part 1: Backend implementation. #895

Checklist

• I have followed the contributing guidelines.
• I have discussed this with project maintainers:
  
  If not checked, I accept that this work might be rejected in favor of a different great big ineffable plan.
  

Details

The following macro seems to work as expected:

Macro {
  area="Menu";
  key="AltT";
  action = function()
    far.Message(Menu.HorizontalAlignment, "Horizontal Alignment")
  end;
}

@rohitab, may I ask you to give this new property a try? Does it suite your purpose? Do you need something more?

[shmuz]

@MKadaner , with regards to macro API:

1. As I can see there are 4 possible return values: -1, 1, 2 and 4. Why the latter is 4 rather than 3 ?
2. Despite the macro section in Far Encyclopedia is outdated it would be desirable to add the description of Menu.HorisontalAlignment to enc\enc_rus\meta\macro\macrocmd\prop_func\menus.html.
3. There are also 3 files enc\enc_lua\macroapi_manual.??.tsi that I can update myself after the PR is merged.

[alabuzhev]

what is the right / simplest way to build Far with plugins locally for testing?

@MKadaner, _build\vc\all.sln

[MKadaner]

@shmuz:

Why the latter is 4 rather than 3 ?

It is related to @HamRusTal's comment. If we want to add an enumeration, Center should have value 3, and Annotation should be 4. Even if the enumeration is not needed, it makes sense to reserve 3 for a possible future use.

Of course, I am not strong on either of these. Please let me know how to proceed.

I also noticed that the Menu.Id property in Encyclopedia and code comments is spelled as Menu.Info.Id. Do you want me to fix it?

Please have a look at Encyclopedia and Lua Manual.

[johnd0e]

I also noticed that the Menu.Id property in Encyclopedia and code comments is spelled as Menu.Info.Id. Do you want me to fix it?

No sense, as Encyclopedia (in Macro section) is in either case severely outdated.
So I do not see any point in touching it at all.
@shmuz

[shmuz]

@MKadaner
@johnd0e
I agree that we shouldn't fix anything there (until somebody volunteers to fix it all).
But with regards to the new property Menu.HorizontalAlignment I think it is worth to add.

[johnd0e]

But there are a lot of things missing already.

E.g.

• Area: Current, ShellAutoCompletion, DialogAutoCompletion
• Panel: CustomSortMenu, LoadCustomSortMode, SetCustomSortMode
• Dlg: Owner
• Far: GetConfig
• Mouse: LastCtrlState
• Object: Height, Width
• Plugin.SyncCall
• mf: acall, AddExitHandler, deserialize/serialize, EnumScripts, GetMacroCopy, postmacro, printconsole, usermenu

[shmuz]

@johnd0e
I want Menu.HorizontalAlignment there. Period.

[MKadaner]

I did my best. Ready for review.

I did not touch Menu.Info.Id, mostly because I was not sure I fully understand things like this:

#_1. `Menu.Info.Id -> Menu.Id`

[sonarqubecloud]

Quality Gate passed

Issues
2 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[shmuz]

@MKadaner
Menu.Info.Id -> Menu.Id means that after changing from the old macro language to Lua one should use Menu.Id instead of Menu.Info.Id.
These TSI-files are sources for the corresponding CHM-files found in the %FARHOME%\Encyclopedia directory.

[MKadaner]

@shmuz, thanks. It means that somewhere there is still some code which parses the string Menu.Info.Id and invokes VMProcess, right? If so, no changes to the documentation are required in this regard.

Let's merge this PR?

[shmuz]

It means that somewhere there is still some code which parses the string Menu.Info.Id and invokes VMProcess, right?

1. No there isn't such code in current Far3.
   That article ("API changes in comparison to the macro language") was written in year 2012 to ease the transition from old macro language to Lua. The old constructs like Menu.Info.Id won't work in any Far3 build since 3.0.2851 (Sep 30 2012).
2. The Macro part in Far Encyclopedia is not updated since then. There is a big warning in red about that.
3. With regards to merging this PR - let's @alabuzhev decide. I have no objections for merging it.

[alabuzhev]

Thank you

[MKadaner]

Thank you all!