Multi-panel plug-in for FAR Manager, Technical information

Please note, that some information mentioned here might not be absolutely
correct. This might be caused by misunderstanding of the API documentation,
by some other mistakes, or simply because there is a newer version of the
API already available. We appreciate any corrections to this document.

1! FAR HACK: There is no PanelInfo ID

In the current FAR API version there is no way to distinguish between the
two native File panels. This is needed in order to detect which one of them
is selected when the plugin is reentered, so that to pop the correct
location up to the top of the LRU. There is an identifier for an Editor
screen instance (see the EditorID field in the EditorInfo structure), but
there is nothing like this in the PanelInfo structure. This means that a
plugin cannot generally make sure it is accessing the File panel it wants.
Currently, a hack is used, to distinguish File panels by the PanelRect field
in the PanelInfo structure. It is relying on the fact, that coordinates of
the File panels can be used to distinguish between the left and the right
panel. This helps, but only until the panels are swapped (using the standard
FAR's CtrlU) odd number of times, or the panels are both in the fullscreen
mode, and the Tab was used odd number of time. The panel indices will not be
updated correctly in those cases, unless the plugin's macro for CtrlU is used
(see *.reg files). To fix that, the plugin would have to intercept CtrlU and
Tab/ShiftTab. Unfortunately, this would not only be ugly, but unreliable too.
The main concern is that the user can call Swap panels from the F9 menu, and
this could not be intercepted by the plugin anymore. Luckily, it seems that
not many users would do this, but the issue remains. Working around those
problems would be just too cumbersome and frustrating for a simple plugin :-)
This issue would be much easier to fix in the FAR API. Hopefully, it will be
addressed in the nearest FAR versions, and there will be a way to uniquely
identify each one of the two native File panels.

2. FAR BUG: The "Colors / Dialog / Disabled list" setting is misplaced

The current FAR version uses the "Menu / Disabled text" interface color
setting, where the "Dialog / Disabled list" setting should be used. This
is a relatively new color setting in FAR, and not many plugins are
currently using it, but Multi-panel does. (On the other hand, it is not
quite clear, why to distinguish the color settings for menus and dialogs.)
Anyway, please be aware of this bug in FAR, when seing wierd coloring of
the disabled items in the panel list dialog, and trying to fix it by tuning
the FAR color settings. Just make sure you are tuning the wrong one :-)

3. FAR LIMITATION: Cannot handle CtrlEsc

The current FAR version does not let the plugin to intercept the key
combinations, processed by Win32 by default, like CtrlEsc. The plugin
could use CtrlEsc to gracefully cancel the panel list dialog called
in the "quick" mode. Unfortunately, this is not possible right now,
and the user have to press F10, to cancel the dialog while Ctrl is
held. This restricts the flexibility of not only this plugin, but
also limits the selection of keyboard macros the user can define.
For example, in the earlier FAR versions it was possible to have an
AltSpace macro, but not anymore. A reasonable solution on the FAR API
side would be to let the plugin process the key first, and only after
this, is the plugin's handler returns FALSE, pass it to the default
Win32 handler. Hopefully, this issue will be addressed in the nearest
FAR versions.

4. FAR BUG: DialogEx crashes for correct values of Y1

The current FAR version crashes when trying to specify a dialog height,
in the DialogEx call, larger than some number, even when the resulting
dialog fits the screen. The plugin can use a workaround, by changing
the dialog size to the desired later, by sending the DM_MOVEDIALOG
dialog message on the DN_INITDIALOG dialog event.

5. FAR LIMITATION: Other plugin's panel support is limited

In the current FAR version, the plugin panel support is limited, and Multi
panel cannot work with the panels of other plugins, like Temporary panel,
Network panel, FTP panel, etc. Luckily, such panels are used much less often
than the File panels, and usually during a shorter period of time. The
limitation might be resolved in the future FAR versions, or might be not.

6. FAR LIMITATION: The Tree/Info/QView panel support is limited

In the current FAR version, plugin cannot initiate switch to a Tree/Info/QView
panel, so the Multi-panel plugin does not support them very well. These panels
are rarely used by the authors of the plugin.

7. FAR BUG: PanelInfo.CurDir is not always set for QView panel

In the current FAR version, for QView panel, PanelInfo.CurDir is not set when
the panel is first activated, and does not always get updated when moving
between files in the other panel (File or Tree panel), so the plugin cannot
show the correct data about this panel. The plugin menu does not show the
Multi-panel plugin entry after the QView panel has just been activated. But
the QView panel itself is always updated and drawn correctly. The QView panel
is rarely used by the authors of the Multi-panel plugin, so there has not been
any research done for whether any workarounds available.

8. FAR BUG: Automatic dialog positioning is inconsistent

In the current FAR version, for odd dialog widths and/or heights, automatic
dialog positioning produces different result for DialogEx and DM_MOVEDIALOG.
Workaround - use only even dialog widths and heights, or send DM_MOVEDIALOG
also on DN_INITDIALOG. Thus, this rather a very minor, cosmetic ussie.

9. FAR LIMITATION: Cannot output to the screen from plugin while in panels

One of the most often seen requests from the users of Multi-panel is the
desire to always see, on the screen, the index of the currently displayed
panel, and the total amount of panels open. Just like FAR always displays
the number of the open screens. Unfortunately, in the current version of
FAR a plugin cannot control the panel screen at real-time. Hopefully, this
will become possible in the future FAR version.

10. FAR LIMITATION: DN_KEY inconsistencies

In the current FAR version, the DN_KEY event is supposed to be sent to the
plugin only on a key press. First off, this is limiting, and the plugin has
to use the GetAsyncKeyState Win32 API call, to track key releases. While the
DN_KEY event is limiting, it is also inconsistent. For some keys, the event,
corresponding to the key press, is delayed, and sent on another (or this) key
release. An example would be this key sequence: +RCtrl -RCtrl. Another example
is: +LCtrl +~ (DN_KEY press is sent) -~ +RCtrl -LCtrl (DN_KEY press is sent).
Key polling via GetAsyncKeyState can, again, be used as a workaround, but only
when there is an appropriate place for polling available (a common problem of
every polling scheme).

11. PLUGIN RESERVED: C:\ is used instead of an empty panel

Right now, the New panel function, as well as the check for unavailable panel
locations (e.g. if a directory has been removed, but some panels still refer
to it), use the C:\ directory as the starting panel location. In the future,
an empty panel might be implemented in the plugin, and those features will
use it, as they are supposed to.

12. FAR BUG? Early DN_ENTERIDLE is sent

In the current FAR version, the DN_ENTERIDLE message is sent to the plugin
when there are still other unprocessed messages in the message queue. This
FAR behavior has been noticed in the case of quick switching between slow
media locations, thus causing issues of how the keyboard input is processed
by the plugin. More specifically, the plugin might think is has been called
in the "normal" mode, instead of the "quick" mode. This is a minor issue,
and a workaround can be proposed in the future versions of the plugin, in
case it is not fixed in FAR by that point.

13. FAR BUG: Panels are redrawn incorrectly after FCTL_SETSELECTION

In the current FAR version, the FCTL_SETSELECTION command seems to affect
how the file cursor is positioned in the panel after FCTL_REDRAWPANEL,
even a PanelRedrawInfo is passed to FCTL_REDRAWPANEL. Another additional
command, like FCTL_SETSORTORDER, issued after FCTL_REDRAWPANEL, seems to
redraw the file cursor correctly, how it was set in PanelRedrawInfo.

14! FAR LIMITATION: Plugins cannot set some panel properties

In the current FAR version, plugins can read all panel settings, but cannot
set some of them: PluginInfo.ShortNames, PanelInfo.Visible, Use sort groups,
and Show selected first. This creates minor issues, and hopefully will be
addressed in the nearest FAR versions. Also, plugin cannot set active panel.
As a result, the plugin cannot restore the active panel on panel set loading.

15. FAR LIMITATION: Cannot restrict macros to specific plugin's dialogs

Every macro currently works in all FAR dialogs. A user currently cannot
redefine the keys in the dialogs of a specific plugin. A workaround will be
provided in a future version of the plugin. Currently the command keys are
hardcoded in the plugin, and it also relies on certain key macros to be
defined (see *.reg files). If some other keys are mapped to the plugin
functions, they will not work as expected if pressed repeatedly, because
the panel list dialog will still be using the hardcoded plugin keys.

16! FAR BUG: ExitFAR, Control, no "Run before FAR exit" macro flag

When ExitFAR gets called, the file panels are already destroyed by FAR, so
there is no way for a plugin to automatically save their state on FAR exit.
However, FAR itself saves some panel information on exit, like active panel,
panel visibility flag, etc. All of this, together with TECHINFO 14, creates
minor issues with panel saving restoring between FAR sessions. According
to the FAR authors, this behavior is unlikely to change in the future FAR
versions. A good alternative solution would be to add "Run before FAR exit"
macro flag (symmetrical to "Run after FAR start") to FAR. Important, that
such a macro must be executed always, even if FAR gets closed with the
window cross button! Then a macro could be written to invoke the plugin
once more on FAR exit, to save the panels. Right now a macro for F10 is
used, which would not work if FAR is closed with the window cross button.

17= PLUGIN LIMITATION: Limitations of plugin's macro commands

(Plugin's macros is a way to work around TECHINFO 15.) If a plugin's macro
closes the plugin's dialog, the remaining part of the currently active
plugin's macro is cancelled, and is not inserted into FAR's input queue,
to be processed by the next FAR activity.

18. FAR LIMITATION: Current key queue is cancelled on ACTL_POSTKEYSEQUENCE

If there are keys in the FAR key queue when plugin calls ACTL_POSTKEYSEQUENCE,
they will be discarded by FAR. This affects plugin's macros in a subtle way,
so that if a plugin's macro closes the plugin dialog and leaves some keys
to FAR, the currently active FAR macro will be cancelled. This is just a side
note, because this does not interfere with the plugin in a negative way.

19. FAR BUG: KSFLAGS_DISABLEOUTPUT ignored on ACTL_POSTKEYSEQUENCE

Self-describing. If a plugin's macro exits the dialog, then the process of
execution of the remaining of its output will be visible.

20. WINDOWS BUG: Get[Async]KeyState does not work earlier than in Win2k

For this reason, the "quick" dialog mode currently does not work in the older
Windows versions. This might be worked around in the plugin in the future.

21. FAR EXTENSION: Executing FAR startup command line by plugins

TBD

Legend:
. open
! priority
+ fixed
= expired
