Difference between revisions of "Dice/RollerConfig/ExecuteMacro"

From DiceRoller Documentation
m (Skizzerz moved page API/RollerConfig/ExecuteMacro to Dice/RollerConfig/ExecuteMacro without leaving a redirect)
 
(7 intermediate revisions by the same user not shown)
Line 3: Line 3:
  
 
{{ns}}
 
{{ns}}
 +
 +
== Deprecated ==
 +
{{deprecated}} This API was marked deprecated in version 3.0.0 and removed in version 4.0.0. See [[../MacroRegistry|MacroRegistry]] for an alternative.
  
 
== Syntax ==
 
== Syntax ==
 
<syntaxhighlight lang="C#">
 
<syntaxhighlight lang="C#">
 +
[Obsolete]
 
public MacroCallback ExecuteMacro { get; set; }
 
public MacroCallback ExecuteMacro { get; set; }
 
</syntaxhighlight>
 
</syntaxhighlight>
  
 
=== Property Value ===
 
=== Property Value ===
Type: [[API/Dice/MacroCallback|Dice.MacroCallback]]
+
Type: [[Dice/MacroCallback|Dice.MacroCallback]]
  
 
The callback delegate which is executed whenever a macro is encountered in the dice expression.
 
The callback delegate which is executed whenever a macro is encountered in the dice expression.
  
 
== Remarks ==
 
== Remarks ==
If ExecuteMacro is {{cs|null}}, a [[API/DiceException|DiceException]] will be thrown with the ErrorCode [[API/Dice/DiceErrorCode|DiceErrorCode.InvalidMacro]]. As the MacroCallback type is a delegate, multiple callback functions can be registered, and all of them will be invoked in sequence when a macro is encountered.
+
If ExecuteMacro is not {{cs|null}}, the callbacks will be called for '''every''' macro executed. As the MacroCallback type is a delegate, multiple callback functions can be registered, and all of them will be invoked in sequence when a macro is encountered. Use [[../MacroRegistry|MacroRegistry]] to tie macro callbacks to specific names. Calling {{l|MacroRegistry.RegisterGlobalMacro}} modifies this property.
  
The callback should modify the Value of the passed-in [[API/MacroContext|MacroContext]] to indicate that the macro was run successfully. If the Value field is not modified by any callback, a DiceException will be thrown with ErrorCode DiceErrorCode.InvalidMacro.
+
The callback should modify the Value of the passed-in [[Dice/MacroContext|MacroContext]] to indicate that the macro was run successfully. If the Value field is not modified by any callback, a DiceException will be thrown with ErrorCode DiceErrorCode.InvalidMacro.
  
 
== Examples ==
 
== Examples ==

Latest revision as of 05:02, 23 December 2018

Gets or sets the function used to execute macros.

  • Namespace: Dice
  • Assembly: DiceRoller (in DiceRoller.dll)

Deprecated

This API was marked deprecated in version 3.0.0 and removed in version 4.0.0. See MacroRegistry for an alternative.

Syntax

[Obsolete]
public MacroCallback ExecuteMacro { get; set; }

Property Value

Type: Dice.MacroCallback

The callback delegate which is executed whenever a macro is encountered in the dice expression.

Remarks

If ExecuteMacro is not null, the callbacks will be called for every macro executed. As the MacroCallback type is a delegate, multiple callback functions can be registered, and all of them will be invoked in sequence when a macro is encountered. Use MacroRegistry to tie macro callbacks to specific names. Calling MacroRegistry.RegisterGlobalMacro modifies this property.

The callback should modify the Value of the passed-in MacroContext to indicate that the macro was run successfully. If the Value field is not modified by any callback, a DiceException will be thrown with ErrorCode DiceErrorCode.InvalidMacro.

Examples

The following example registers two callbacks to handle macro executions.

using Dice;

class Sample
{
    public static void Main()
    {
        Roller.DefaultConfig.ExecuteMacro += MacroCallback1;
        Roller.DefaultConfig.ExecuteMacro += MacroCallback2;
        var result1 = Roller.Roll("1d20+[WIS-mod]"); // rolls 1d20+2
        var result2 = Roller.Roll("1d20+[proficiency]"); // throws DiceException with DiceErrorCode.InvalidMacro
    }

    public static void MacroCallback1(MacroContext context)
    {
        switch (context.Param)
        {
            case "STR-mod":
                context.Value = 0;
                break;
            case "DEX-mod":
                context.Value = 3;
                break;
            case "CON-mod":
                context.Value = -1;
                break;
        }
    }

    public static void MacroCallback2(MacroContext context)
    {
        switch (context.Param)
        {
            case "INT-mod":
                context.Value = -1;
                break;
            case "WIS-mod":
                context.Value = 2;
                break;
            case "CHA-mod":
                context.Value = 0;
                break;
        }
    }
}