[This is preliminary documentation and is subject to change.]

Invokes a customCommandKey that will be handled by an Handler.

Namespace:  Firefly.Box
Assembly:  Firefly.Box (in Firefly.Box.dll) Version: 3.4.23.6473 (3.4.23.6473)

Syntax

C#
public void Invoke(
	string customCommandKey,
	params Object[] untypedArgs
)
Visual Basic (Declaration)
Public Sub Invoke ( _
	customCommandKey As String, _
	ParamArray untypedArgs As Object() _
)
Visual C++
public:
void Invoke(
	String^ customCommandKey, 
	... array<Object^>^ untypedArgs
)

Parameters

customCommandKey
Type: System..::.String
The key that will be used to locate the CustomCommand to invoke.
untypedArgs
Type: array< System..::.Object >[]()[]
Arguments to be sent to the Handler that will handle the invoked customCommandKey

Remarks

When the Handler method is called, the framework will iterate the Handlers property collection until it will find an Handler that matches the customCommandKey.
If no matching Handler was found, or if the Handled property was set to true, the framework will iterate the calling task's Handlers property collection and so on.
The deference between Raise and Invoke, is that Raise will queue the customCommandKey, and process it the next time the framework is idle, while Invoke will process it immediately
When invoking a {0} (for example {1}) or a Key Combination, only the relevant Handlers will execute, but the command it self will not. In order to run the command itself use .

Examples

Raising and handling of events in a UI
This example is based on test data. The code for the entities included in this test data can be found in the documentation of Entity
This example uses automatic tools to generate parts of the user interface. Those tools can be found in the example of the documentation of Form
CopyC#
using System.Drawing;
using System.Windows.Forms;
using Firefly.Box;

namespace TestFirefly.Box.Documentation
{
    public class DemoRaiseDelete
    {
        public void RaiseDelete()
        {
            var jobs = new Pubs.Jobs();
            jobs.InitializeWithTestData();

            var uic = new UIController
            {
                From = jobs,
                View = UITools.GenerateFormWithGridFor("Display Jobs",
                                                       "Click the Delete button to delete the current row",
                                                       jobs.Id,
                                                       jobs.Description,
                                                       jobs.MinLevel,
                                                       jobs.MaxLevel)
            };

            var deleteButton = new Button
            {
                Text = "Delete",
            };
            UITools.AddControlsToForm(uic.View, deleteButton);

            //raise the delete command by the button
            deleteButton.Click += (a, b) => uic.Raise(Command.DeleteRow);
            uic.Run();
        }
        public void HandlingDelete()
        {
            var jobs = new Pubs.Jobs();
            jobs.InitializeWithTestData();

            var uic = new UIController
            {
                From = jobs,
                View = UITools.GenerateFormWithGridFor("Display Jobs",
                                                       "Click the delete button, and see how the custom handler for the delete command"+
                                                       " takes affect",
                                                       jobs.Id,
                                                       jobs.Description,
                                                       jobs.MinLevel,
                                                       jobs.MaxLevel)
            };

            var deleteButton = new Button
            {
                Text = "Delete",
            };
            UITools.AddControlsToForm(uic.View, deleteButton);

            //raise the delete command by the button
            deleteButton.Click += (a, b) => uic.Raise(Command.DeleteRow);

            uic.Handlers.Add(Command.DeleteRow).Invokes += e =>
            {
                if (MessageBox.Show(
                        "Are you sure you want to delete this row",
                        "Confirm Delete",
                        MessageBoxButtons.YesNo) == DialogResult.Yes)
                    e.Handled = false;
            };
            uic.Run();
        }
    }
}

Examples

deference between invoke and raise
CopyC#
using System;
using System.Collections.Generic;
using System.Text;

using Firefly.Box;
using Firefly.Box.Testing;

namespace TestFirefly.Box.Documentation
{
    public class DeferenceBetweenRaiseAndInvoke
    {
        public void DemoRaiseAndInvoke()
        {
            var uic = new UIController
            {
                View = new Firefly.Box.UI.Form()
            };
            var myCommand = new CustomCommand();
            var h = uic.Handlers.Add(myCommand);
            h.Invokes += e =>
            {
                e.Handled = false;
                System.Windows.Forms.MessageBox.Show("First Handler");
            };
            var h2 = uic.Handlers.Add(myCommand);
            h2.Invokes += e =>
            {
                e.Handled = false;
                System.Windows.Forms.MessageBox.Show("Second Handler");
            };
            var invokeButton = new Firefly.Box.UI.Button
            {
                Text = "Invoke"
            };
            invokeButton.Click += (a, b) =>
            {
                System.Windows.Forms.MessageBox.Show("Before Invoke");
                uic.Invoke(myCommand);
                System.Windows.Forms.MessageBox.Show("After Invoke");
            };

            uic.View.Controls.Add(invokeButton);

            var raiseButton = new Firefly.Box.UI.Button
            {
                Text = "Raise",
                Top = invokeButton.Bottom + 5
            };
            raiseButton.Click += (a, b) =>
            {
                System.Windows.Forms.MessageBox.Show("Before Raise");
                uic.Raise(myCommand);
                System.Windows.Forms.MessageBox.Show("After Raise");
            };
            uic.View.Controls.Add(raiseButton);
            uic.Run();

        }
    }
}

Examples

The example demonstrates deferent invoke scenarios
This example is in the form of Unit Tests. It references the NUnit framework. This framework can be downloaded from www.NUnit.org. For more information about unit testing visit: www.NUnit.org.
CopyC#
using System;
using System.Collections.Generic;
using System.Text;
using NUnit.Framework;
using Firefly.Box;
using Firefly.Box.Testing;

namespace TestFirefly.Box.Documentation
{
    [TestFixture]
    public class TaskInvoke
    {
        [Test]
        public void UsageOfCustomCommand()
        {
            var bp = new BusinessProcess();
            var command = new CustomCommand();
            bool happened = false;
            bp.Handlers.Add(command).Invokes += e => happened = true;
            bp.ForFirstRow(() =>
            {
                happened.ShouldBe(false);
                bp.Invoke(command);
                happened.ShouldBe(true);
            });
        }
        [Test]
        public void UsageOfCustomCommandAndIdleTiming()
        {
            var bp = new BusinessProcess();
            var command = new CustomCommand();
            bool happened = false;
            bp.Handlers.Add(command).Invokes += e => happened = true;
            bp.ForFirstRow(() =>
            {
                happened.ShouldBe(false);
                bp.Raise(command);
                happened.ShouldBe(false);//The handler doesn't happen immediately,
                //but will be handled the next time the application is idle, 
                //usually in the next active UIController
            });
        }

        [Test]
        public void InvokingACustomCommandByKey()
        {
            var bp = new BusinessProcess();
            var command = new CustomCommand() {Name = "command name", Key = "Key", AllowInvokeByKey = CustomCommandAllowInvokeByKey.Always };
            bool happened = false;
            bp.Handlers.Add(command).Invokes += e => happened = true;
            bp.ForFirstRow(() =>
            {
                happened.ShouldBe(false);
                bp.Invoke("Key");
                happened.ShouldBe(true);
            });
        }


        [Test]
        public void AnInvokedCommandBublesBetweenDeferentTasks()
        {
            var bp = new BusinessProcess();
            var command = new CustomCommand();
            bool happened = false;
            bp.Handlers.Add(command).Invokes += e => happened = true;
            bp.ForFirstRow(() =>
            {
                var childBp = new BusinessProcess();
                childBp.ForFirstRow(() =>
                {
                    childBp.Invoke(command);
                    happened.ShouldBe(true);
                });
            });
        }
    }
}

See Also