Control

Far Manager

Control

The Control function allows to request misc information and perform various control actions for the panels and the command line.
int WINAPI Control(
  HANDLE hPlugin,
  int Command,
  void *Param
);

Parameters

hPlugin
Current plugin instance handle. To request information about the active panel set this parameter to INVALID_HANDLE_VALUE. This allows to use this function in plugin commands that work without creating new panel. The INVALID_HANDLE_VALUE is also used with none plugin panels.
Command
Control command type. Can be one of the following values (FILE_CONTROL_COMMANDS enum):
CommandDescription
Panel
FCTL_CHECKPANELSEXIST Checks if the file panels exist.
Param must be equal to 0 (unused).
The function returns FALSE if FAR was started with the /e or /v command line arguments (as an external viewer or editor). In this mode the panels are not created.

Remarks for FCTL_CHECKPANELSEXIST Attention!

  • When FAR is started with the /e or /v command line arguments, this function processes only one command - FCTL_CHECKPANELSEXIST.
FCTL_CLOSEPLUGIN Closes the current plugin.
Param points to the name of the directory that will be set in the panel after closing the plugin.
FCTL_GETPANELINFO
FCTL_GETANOTHERPANELINFO
Gets information about a plugin active/passive panel.
Param points to a PanelInfo structure that will receive panel information.
If no items are selected in panel, PanelInfo.SelectedItemsNumber is equal to 1 and PanelInfo.SelectedItems contains data for the item under cursor. In order to verify whether the file is actually selected, check if the PPIF_SELECTED flag is set for that item.

While processing the following request

Info.Control(INVALID_HANDLE_VALUE,
             FCTL_GETPANELINFO,
             &PInfo);
FAR call the GetOpenPluginInfo exported function of the plugin to which the panel belongs. FAR contains a protection against an endless recursion in the case when the plugin, from inside the GetOpenPluginInfo() function, also calls Info.Control(...,FCTL_GETPANELINFO), the secondary call of GetOpenPluginInfo() will not happen.

In some cases (e.g. searching in archives by Alt-F7) the plugin panel is not really created, for that reason you must check the return value of the Control function, as to not crash in the most unfitting moment by working on an none existing panel.

Remarks for FCTL_GET[ANOTHER]PANELINFO Attention!

  • The PanelItems and SelectedItems fields of the PanelInfo structure will have different addresses after each new call of FCTL_GETPANELINFO or FCTL_GETANOTHERPANELINFO.
FCTL_GETPANELSHORTINFO
FCTL_GETANOTHERPANELSHORTINFO
Similar to FCTL_GETPANELINFO/FCTL_GETANOTHERPANELINFO, but the PanelItems and the SelectedItems fields of the PanelInfo structure are not filled and are set to NULL. This command is intended to be used when only the common information about the active/passive panel is needed, without any concrete information on elements in that panel.
FCTL_REDRAWPANEL
FCTL_REDRAWANOTHERPANEL
Redraws the plugin active/passive panel.
Param can be either NULL or the address of a PanelRedrawInfo structure, so you can set a new cursor position and the top element for that panel. If Param is set to NULL, the cursor position and the top element will not be changed.
If hPlugin equals INVALID_HANDLE_VALUE, then the active panel will be redrawn no matter what command was used by the plugin.
The panel will be redrawn only if that panel is visible at the moment.
FCTL_SETNUMERICSORT
FCTL_SETANOTHERNUMERICSORT
Sets numeric sort mode for the active/passive panel.
Param points to an integer value: 0 (turn numeric sort off) or 1 (turn numeric sort on).
Setting Param to NULL is equivalent to setting the numeric sort off.
FCTL_SETPANELDIR
FCTL_SETANOTHERPANELDIR
Sets the current directory of a plugin active/passive panel.
Param points to the directory name. If the plugin supports its own panel, it will be closed after execution of this command.

Note that this function resets the file selection in a directory and makes it impossible to restore by pressing Ctrl-M, even if the directory passed to this function is the same as the current directory.

FCTL_SETSELECTION
FCTL_SETANOTHERSELECTION
Sets active/passive panel items selection.
Param points to the PanelInfo structure filled by a previous FCTL_GETPANELINFO or FCTL_GETANOTHERPANELINFO call. You must not use any other Control functions between FCTL_GETPANELINFO and FCTL_SETSELECTION.

To change selection, set or clear PPIF_SELECTED flag in the items of the array pointed to by the PanelItems member of the PanelInfo structure. Note that FCTL_GETPANELINFO and FCTL_GETANOTHERPANELINFO return PPIF_SELECTED in this array set to its real state.

You need to call FCTL_REDRAWPANEL to show the changes.

FCTL_SETSORTMODE
FCTL_SETANOTHERSORTMODE
Sets the active/passive panel sort mode.
Param points to an integer containing the new sort mode (see "Sort modes").
FCTL_SETSORTORDER
FCTL_SETANOTHERSORTORDER
Sets the active/passive panel sort order.
Param points to an integer value representing the sort order: 0 for normal order or 1 for reverse order.
Setting Param to NULL is equivalent to setting the normal sort order (0).
FCTL_SETVIEWMODE
FCTL_SETANOTHERVIEWMODE
Sets active/passive panel view mode.
Param points to an integer containing the new view mode number, from 0 to 9.
Setting Param to NULL is equivalent to setting mode 0.
FCTL_UPDATEPANEL
FCTL_UPDATEANOTHERPANEL
Updates plugin active/passive panel contents.
If Param is NULL, the file selection will be cleared, otherwise selection is not changed.
Command line
FCTL_GETCMDLINE Gets the command line contents.
Param points to the buffer to receive data (the buffer should not be smaller than 1 Kb).
FCTL_GETCMDLINEPOS Gets the cursor position in the command line.
Param points to a variable of type int that receives the cursor position.
FCTL_GETCMDLINESELECTEDTEXT Retrieves the selected text in the command line.
Param points to the buffer to receive data (the buffer should not be smaller than 1 Kb).
FCTL_GETCMDLINESELECTION Returns the parameters of the text selection in the command line.
Param points to a CmdLineSelect structure.
FCTL_INSERTCMDLINE Inserts text into the command line beginning from the current cursor position.
Param points to a zero terminated string to insert to the command line.
FCTL_SETCMDLINE Sets the command line contents.
Param points to a zero terminated string to copy to the command line.
FCTL_SETCMDLINEPOS Sets the cursor position in the command line.
Param points to a variable of type int that contains the new cursor position.
FCTL_SETCMDLINESELECTION Selects a text fragment in the command line.
Param points to a CmdLineSelect structure.
Other
FCTL_SETUSERSCREEN Copies the current screen contents to the FAR user screen buffer (which is displayed when the panels are switched off).
Param must be NULL.
FCTL_GETUSERSCREEN Outputs the FAR user screen buffer (which is displayed when the panels are switched off) to the screen.
Param must be NULL.
Param
Points to control command parameters. Read the description of the Command parameter for concrete information.

Return value

If the function succeeds, the return value is TRUE. If the function fails, FALSE is returned.

Remarks

Usually you do not need to update or redraw panel and close plugin directly. FAR does this itself, when performing standard operations. These functions can become necessary to implement some non-standard functionality.
See also: