Control

Far Manager

previous page next page

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):

Command	Description
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. 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. 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.