Package com.mouseviator.fsuipc.helpers

# Class MacroHelper

java.lang.Object
com.mouseviator.fsuipc.helpers.MacroHelper

    public class MacroHelper
    extends java.lang.Object

This class implements a helper to execute FSUIPC macros using FSUIPC.

Executing FSUIPC macro requires 2 data requests, because it works with 2 offsets. Many functions in this class return both of them in an instance of `MacroHelper.MacroResult`. The main offset in use is 0D70, in which you write a string telling FSUIPC macro from what macro file to execute. I call it here a "macro execute request" and it is the `MacroHelper.MacroResult.getMacroExecuteRequest()`. The next offset is 0D6C and I reference it as "parameter request" here. Because it is the parameter for the macro. You will find this request in the result object as `MacroHelper.MacroResult.getParamRequest()`.

There are various functions for executing FSUIPC macros using FSUIPC. They differ in the amount of parameters - in the way you supply the name of the macro file, the name of the macro and the parameter (if any). Some functions also accepts an instance of `FSUIPC` class and a boolean parameter. These functions will also register the generated requests with given FSUIPC instance for one-time or continual processing (based on that boolean parameter)

## Running a macro example

The code below uses helper function that will build both the required request. Then they are registered for one-time processing and then they are processed. Whether it worked or not needs to be looked in the sim. Did the Pause mode toggled? (also, the macro must be correct).

     //
     // Running macro
     //
     MacroHelper macroHelper = new MacroHelper();

     System.out.println("Trying to execute macro: \"fsuipctest:PauseToggle\" which should toggle the pause in the sim.");
     MacroHelper.MacroResult macroreq = macroHelper.executeMacro("fsuipctest", "PauseToggle");
     fsuipc.addOneTimeRequest(macroreq.getParamRequest());
     fsuipc.addOneTimeRequest(macroreq.getMacroExecuteRequest());

     if (fsuipc.processRequestsOnce() == FSUIPC.PROCESS_RESULT_OK) {
         System.out.println("The macro: \"fsuipctest:PauseToggle\" should have execute. The sim pause should toggle.");
     }

### Running a macro with parameter example

The code below uses helper function to build requests to set the parking brake on using a macro. Then they are registered for one-time processing and then they are processed. Whether it worked or not needs to be looked in the sim. Is the parking brake set? (also, the macro must be correct). This example also uses another variant of the function which accepts the name of the macro file and name of the macro as one string.

     MacroHelper macroHelper = new MacroHelper();

     System.out.println("Trying to execute macro: \"fsuipctest:ParkBrake\" with param 1, which should set parking brake.");
     macroreq = macroHelper.executeMacro("fsuipctest:ParkBrake", 1);
     fsuipc.addOneTimeRequest(macroreq.getParamRequest());
     fsuipc.addOneTimeRequest(macroreq.getMacroExecuteRequest());

     if (fsuipc.processRequestsOnce() == FSUIPC.PROCESS_RESULT_OK) {
        System.out.println("The macro: \"fsuipctest:ParkBrake\" should have execute. The parking brake should be set.");
     }

### Running a macro with parameter example 2

The code below uses helper function to build requests to set the parking brake on using a macro. But this time we use the function that accepts also an instance of `FSUIPC` as parameter, so it will also register the requests for processing. Then we only tell FSUIPC to process the requests. Whether it worked or not needs to be looked in the sim. Is the parking brake unset? (also, the macro must be correct). This example also uses another variant of the function which accepts the name of the macro file and name of the macro as one string.

     MacroHelper macroHelper = new MacroHelper();

     System.out.println("Trying to execute macro: \"fsuipctest:ParkBrake\" with param 0, which should unset parking brake.");
     macroreq = macroHelper.executeMacro("fsuipctest:ParkBrake", 0, fsuipc, false);

     if (fsuipc.processRequestsOnce() == FSUIPC.PROCESS_RESULT_OK) {
       System.out.println("The macro: \"fsuipctest:ParkBrake\" should have execute. The parking brake should be unset.");
     }

If you use the function that registers the requests with FSUIPC, you may not need the resulting object at all. Unless you registered them for continual processing and need to remove them from processing later on.

If you will be registering the requests yourself, make sure that you register them in this order

- 1. Parameter request (`MacroHelper.MacroResult.getParamRequest()`)
- 2. Execute request (`MacroHelper.MacroResult.getMacroExecuteRequest()`)

You can also just use the request and other supporting classes defined in this helper class and write the "functions" by yourself.

Author:
  Mouseviator

- ## Nested Class Summary

  Nested Classes
  Modifier and Type | Class | Description
  --- | --- | ---
  `static class` | `MacroHelper.MacroExecuteRequest` | This class implements macro execute request.
  `static class` | `MacroHelper.MacroParamRequest` | This class implements macro parameter request.
  `static class` | `MacroHelper.MacroResult` | A class representing a result fo macro execute helper functions in the class `MacroHelper`.

- ## Field Summary

  Fields
  Modifier and Type | Field | Description
  --- | --- | ---
  `static int` | `CONTROL_OFFSET` | Offset to tell FSUIPC what to do with lua script, LVar or Macro
  `static int` | `PARAMETER_OFFSET` | Offset for parameter passing for the control offset below

- ## Constructor Summary

  Constructors
  Constructor | Description
  --- | ---
  `MacroHelper()` |

- ## Method Summary

  Modifier and Type | Method | Description
  --- | --- | ---
  `MacroHelper.MacroResult` | `executeMacro​(java.lang.String macro)` | This function will create requests required to execute a macro by FSUIPC.
  `MacroHelper.MacroResult` | `executeMacro​(java.lang.String macro, int macroParam)` | This function will create requests required to execute a macro by FSUIPC.Executing a macro requires 2 requests.
  `MacroHelper.MacroResult` | `executeMacro​(java.lang.String macro, int macroParam, FSUIPC fsuipc, boolean continual)` | This function will create requests required to execute a macro by FSUIPC.Executing a macro requires 2 requests.One is the macro parameter request - integer value written at offset 0x0D6C.The other is the macro execute request - written at offset 0x0D70 and it contains the String in the format "macro file:macro name".
  `MacroHelper.MacroResult` | `executeMacro​(java.lang.String macro, FSUIPC fsuipc, boolean continual)` | This function will create requests required to execute a macro by FSUIPC.
  `MacroHelper.MacroResult` | `executeMacro​(java.lang.String macroFile, java.lang.String macroName)` | This function will create requests required to execute a macro by FSUIPC.Executing a macro requires 2 requests.
  `MacroHelper.MacroResult` | `executeMacro​(java.lang.String macroFile, java.lang.String macroName, int macroParam)` | This function will create requests required to execute a macro by FSUIPC.Executing a macro requires 2 requests.One is the macro parameter request - integer value written at offset 0x0D6C.
  `MacroHelper.MacroResult` | `executeMacro​(java.lang.String macroFile, java.lang.String macroName, int macroParam, FSUIPC fsuipc, boolean continual)` | This function will create requests required to execute a macro by FSUIPC.Executing a macro requires 2 requests.One is the macro parameter request - integer value written at offset 0x0D6C.
  `MacroHelper.MacroResult` | `executeMacro​(java.lang.String macroFile, java.lang.String macroName, FSUIPC fsuipc, boolean continual)` | This function will create requests required to execute a macro by FSUIPC.Executing a macro requires 2 requests.

  ### Methods inherited from class java.lang.Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## Field Details

  - ### PARAMETER_OFFSET

    public static final int PARAMETER_OFFSET
    Offset for parameter passing for the control offset below
    See Also:
      Constant Field Values

  - ### CONTROL_OFFSET

    public static final int CONTROL_OFFSET
    Offset to tell FSUIPC what to do with lua script, LVar or Macro
    See Also:
      Constant Field Values

- ## Constructor Details

  - ### MacroHelper

    public MacroHelper()

- ## Method Details

  - ### executeMacro

    public MacroHelper.MacroResult executeMacro​(java.lang.String macro)
    This function will create requests required to execute a macro by FSUIPC. Executing a macro requires 2 requests. One is the macro parameter request - integer value written at offset 0x0D6C. The other is the macro execute request - written at offset 0x0D70 and it contains the String in the format "macro file:macro name". The "macro file" is the name of the macro file without the .mcro extension. The "macro name" is name of the macro within that macro file. Both parts can be up to 16 chars long. This function will generate parameter data request with value 0.
    Parameters:
      `macro` - The macro to execute. In the format: "macro file:macro name"
    Returns:
      Will return an instance of `MacroHelper.MacroResult` when both required data requests are successfully created. The creation of execute request may fail if the `macro` violates the format or either macro file or macro name parts exceeds length of 16 bytes... In that case, null will be returned.

  - ### executeMacro

    public MacroHelper.MacroResult executeMacro​(java.lang.String macro, FSUIPC fsuipc, boolean continual)
    This function will create requests required to execute a macro by FSUIPC. Executing a macro requires 2 requests. One is the macro parameter request - integer value written at offset 0x0D6C. The other is the macro execute request - written at offset 0x0D70 and it contains the String in the format "macro file:macro name". The "macro file" is the name of the macro file without the .mcro extension. The "macro name" is name of the macro within that macro file. Both parts can be up to 16 chars long. This function will generate parameter data request with value 0 and will register the generated requests for continual or one-time processing.
    Parameters:
      `macro` - The macro to execute. In the format: "macro file:macro name"
      `fsuipc` - An instance of `FSUIPC` to register requests with.
      `continual` - Whether to register requests for continual processing or one-time processing. True for continual.
    Returns:
      Will return an instance of `MacroHelper.MacroResult` when both required data requests are successfully created. The creation of execute request may fail if the `macro` violates the format or either macro file or macro name parts exceeds length of 16 bytes... In that case, null will be returned. Null will be returned also if `fsuipc` is null.

  - ### executeMacro

    public MacroHelper.MacroResult executeMacro​(java.lang.String macro, int macroParam)
    This function will create requests required to execute a macro by FSUIPC.Executing a macro requires 2 requests. One is the macro parameter request - integer value written at offset 0x0D6C. The other is the macro execute request - written at offset 0x0D70 and it contains the String in the format "macro file:macro name". The "macro file" is the name of the macro file without the .mcro extension. The "macro name" is name of the macro within that macro file. Both parts can be up to 16 chars long.
    Parameters:
      `macro` - The macro to execute. In the format: "macro file:macro name"
      `macroParam` - The parameter for the macro.
    Returns:
      Will return an instance of `MacroHelper.MacroResult` when both required data requests are successfully created. The creation of execute request may fail if the `macro` violates the format or either macro file or macro name parts exceeds length of 16 bytes... In that case, null will be returned.

  - ### executeMacro

    public MacroHelper.MacroResult executeMacro​(java.lang.String macro, int macroParam, FSUIPC fsuipc, boolean continual)
    This function will create requests required to execute a macro by FSUIPC.Executing a macro requires 2 requests.One is the macro parameter request - integer value written at offset 0x0D6C.The other is the macro execute request - written at offset 0x0D70 and it contains the String in the format "macro file:macro name". The "macro file" is the name of the macro file without the .mcro extension. The "macro name" is name of the macro within that macro file. Both parts can be up to 16 chars long. This function and will register the generated requests for continual or one-time processing.
    Parameters:
      `macro` - The macro to execute. In the format: "macro file:macro name"
      `macroParam` - The parameter for the macro.
      `fsuipc` - An instance of `FSUIPC` to register requests with.
      `continual` - Whether to register requests for continual processing or one-time processing. True for continual.
    Returns:
      Will return an instance of `MacroHelper.MacroResult` when both required data requests are successfully created. The creation of execute request may fail if the `macro` violates the format or either macro file or macro name parts exceeds length of 16 bytes... In that case, null will be returned. Null will be returned also if `fsuipc` is null.

  - ### executeMacro

    public MacroHelper.MacroResult executeMacro​(java.lang.String macroFile, java.lang.String macroName)
    This function will create requests required to execute a macro by FSUIPC.Executing a macro requires 2 requests. One is the macro parameter request - integer value written at offset 0x0D6C. The other is the macro execute request - written at offset 0x0D70 and it contains the String in the format "macro file:macro name". The "macro file" is the name of the macro file without the .mcro extension. The "macro name" is name of the macro within that macro file. Both parts can be up to 16 chars long. This function will generate parameter data request with value 0. This function accepts macro file and macro name separately.
    Parameters:
      `macroFile` - The name of the macro file.
      `macroName` - The name of the macro within the macro file.
    Returns:
      Will return an instance of `MacroHelper.MacroResult` when both required data requests are successfully created. The creation of execute request may fail if the `macro` violates the format or either macro file or macro name parts exceeds length of 16 bytes... In that case, null will be returned.

  - ### executeMacro

    public MacroHelper.MacroResult executeMacro​(java.lang.String macroFile, java.lang.String macroName, FSUIPC fsuipc, boolean continual)
    This function will create requests required to execute a macro by FSUIPC.Executing a macro requires 2 requests. One is the macro parameter request - integer value written at offset 0x0D6C. The other is the macro execute request - written at offset 0x0D70 and it contains the String in the format "macro file:macro name". The "macro file" is the name of the macro file without the .mcro extension. The "macro name" is name of the macro within that macro file. Both parts can be up to 16 chars long. This function will generate parameter data request with value 0. This function accepts macro file and macro name separately and will register the generated requests for continual or one-time processing.
    Parameters:
      `macroFile` - The name of the macro file.
      `macroName` - The name of the macro within the macro file.
      `fsuipc` - An instance of `FSUIPC` to register requests with.
      `continual` - Whether to register requests for continual processing or one-time processing. True for continual.
    Returns:
      Will return an instance of `MacroHelper.MacroResult` when both required data requests are successfully created. The creation of execute request may fail if the `macro` violates the format or either macro file or macro name parts exceeds length of 16 bytes... In that case, null will be returned. Null will be returned also if `fsuipc` is null.

  - ### executeMacro

    public MacroHelper.MacroResult executeMacro​(java.lang.String macroFile, java.lang.String macroName, int macroParam)
    This function will create requests required to execute a macro by FSUIPC.Executing a macro requires 2 requests.One is the macro parameter request - integer value written at offset 0x0D6C. The other is the macro execute request - written at offset 0x0D70 and it contains the String in the format "macro file:macro name". The "macro file" is the name of the macro file without the .mcro extension. The "macro name" is name of the macro within that macro file. Both parts can be up to 16 chars long. This function accepts macro file and macro name separately.
    Parameters:
      `macroFile` - The name of the macro file.
      `macroName` - The name of the macro within the macro file.
      `macroParam` - The parameter for the macro.
    Returns:
      Will return an instance of `MacroHelper.MacroResult` when both required data requests are successfully created. The creation of execute request may fail if the `macro` violates the format or either macro file or macro name parts exceeds length of 16 bytes... In that case, null will be returned.

  - ### executeMacro

    public MacroHelper.MacroResult executeMacro​(java.lang.String macroFile, java.lang.String macroName, int macroParam, FSUIPC fsuipc, boolean continual)
    This function will create requests required to execute a macro by FSUIPC.Executing a macro requires 2 requests.One is the macro parameter request - integer value written at offset 0x0D6C. The other is the macro execute request - written at offset 0x0D70 and it contains the String in the format "macro file:macro name". The "macro file" is the name of the macro file without the .mcro extension. The "macro name" is name of the macro within that macro file. Both parts can be up to 16 chars long. This function accepts macro file and macro name separately and will register the generated requests for continual or one-time processing.
    Parameters:
      `macroFile` - The name of the macro file.
      `macroName` - The name of the macro within the macro file.
      `macroParam` - The parameter for the macro.
      `fsuipc` - An instance of `FSUIPC` to register requests with.
      `continual` - Whether to register requests for continual processing or one-time processing. True for continual.
    Returns:
      Will return an instance of `MacroHelper.MacroResult` when both required data requests are successfully created. The creation of execute request may fail if the `macro` violates the format or either macro file or macro name parts exceeds length of 16 bytes... In that case, null will be returned. Null will be returned also if `fsuipc` is null.