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

Please note, that some information about the FAR API mentioned here might not
be absolutely correct, which, in its turn, might be caused by misunderstanding
of the documentation, or by the authors' own mistakes.

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 re-entered, 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 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. 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_MOVE_DIALOG.
Workaround - use only even dialog widths and heights.

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. 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: PanelInfo.ShortNames is not settable

In the current FAR version, there is no Control function provided for
a plugin to set the ShortNames field for a panel. A workaround is possible,
but it does not seem to be worth the effort, and would probably be much
simpler to fix on the Far side. Thus, changing ShortNames for by the user
(CtrlN) currently affects all the panel on that side of the screen.

Next unique: 15
