# 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.
See also:
AdvControl, EditorControl