Difference between revisions of "Using events in CS"

From Ribbon Commander Documentation
Jump to: navigation, search
(→‎Background)
(→‎Example)
 
(12 intermediate revisions by the same user not shown)
Line 1: Line 1:
−
{{DISPLAYTITLE:Unsing Events in C#}}
+
{{DISPLAYTITLE:Using Events in C#}}
 
== Prerequisites ==
 
== Prerequisites ==
−
We recommend you go through [[Creating our first button in CS|Creating our first button in C#]] before going into this example.
+
We recommend you go through [[A 'hello world' CS program|A 'hello world' C# program]] before going into this example.
  
 
== Background ==
 
== Background ==
−
You can subscribe to events of [[controls|Dynamic RibbonX controls]] by using .NET events or .NET delegates. Here, we show how it can be done by using .NET events.
+
You can subscribe to events of [[controls|Ribbon Commander controls]] by using .NET events or [[Using_delegates_in_CS|.NET delegates]]. Here, we show how it can be done by using .NET events.
 
In general you need to take the following steps:
 
In general you need to take the following steps:
 
* Declare a member variable of the events source control type (e.g. [[rxCheckBox]])
 
* Declare a member variable of the events source control type (e.g. [[rxCheckBox]])
 
* Assign the member variable to an object of the type (e.g. instantiate a new variable)
 
* Assign the member variable to an object of the type (e.g. instantiate a new variable)
−
* Use the standard operator += to add an event handler to events you are interested in. Intellisense allows you to insert event stubs automatically.
+
* Use the ''standard operator +='' to add event handlers to events you are interested need to subscribe to. Intellisense allows you to insert event stubs automatically.
 +
 
 +
== Example ==
 +
In this example we will set up a UI that contains an [[rxCheckBox]] control and subscribe to all its [[rxCheckBox#Events|events]].
 +
* Add a new class to [[Creating a new project in CSharp|your project]] and name it CheckBoxEventsUI
 +
* Add the following code to your class
 +
<syntaxhighlight lang="csharp" line>
 +
// Namespaces of the two Ribbon Commander assemblies
 +
using IlydaUK.Interop.RibbonCommander;
 +
using IlydaUK.RibbonCommander.Core;
 +
 
 +
namespace RibbonCommanderAddin
 +
{
 +
    class CheckBoxEventsUI
 +
    {
 +
        private rxCustomUI _customUI;
 +
        private rxCheckBox _myCheckBox;
 +
 
 +
        public CheckBoxEventsUI()
 +
        {
 +
            // Instantiate a new rxCustomUI in a new context with id 'my_test_cs_ctx'
 +
            _customUI = rxCustomUI.create("my_test_cs_ctx", "Test C# Context");
 +
 
 +
            _customUI.clear();
 +
 
 +
            // Add a new tab and label it
 +
            rxTab myTab = _customUI.ribbon.tabs.add(new rxTab());
 +
            myTab.label = "My C# Tab";
 +
 
 +
            // Add a new group to the tab and label it
 +
            rxGroup myGroup = myTab.groups.add(new rxGroup());
 +
            myGroup.label = "My C# Group";
 +
 
 +
            // Add a new checkbox to the group and subscribe to all its events
 +
            _myCheckBox = myGroup.checkBoxes.add(new rxCheckBox());
 +
            _myCheckBox.OnActionEvent += _myCheckBox_OnActionEvent;
 +
            _myCheckBox.OnGetDescription += _myCheckBox_OnGetDescription;
 +
            _myCheckBox.OnGetEnabled += _myCheckBox_OnGetEnabled;
 +
            _myCheckBox.OnGetKeytip += _myCheckBox_OnGetKeytip;
 +
            _myCheckBox.OnGetLabel += _myCheckBox_OnGetLabel;
 +
            _myCheckBox.OnGetPressed += _myCheckBox_OnGetPressed;
 +
            _myCheckBox.OnGetScreentip += _myCheckBox_OnGetScreentip;
 +
            _myCheckBox.OnGetSupertip += _myCheckBox_OnGetSupertip;
 +
            _myCheckBox.OnGetVisible += _myCheckBox_OnGetVisible;
 +
 
 +
            // Render the UI
 +
            _customUI.refresh();
 +
 
 +
        }
 +
 
 +
        void _myCheckBox_OnGetVisible(IRibbonControl control, out bool visible)
 +
        {
 +
            System.Diagnostics.Debug.Print("_myCheckBox_OnGetVisible called...");
 +
 
 +
            visible = true;
 +
        }
 +
 
 +
        void _myCheckBox_OnGetSupertip(IRibbonControl control, out string supertip)
 +
        {
 +
            System.Diagnostics.Debug.Print("_myCheckBox_OnGetSupertip called...");
 +
 
 +
            supertip = "My CheckBox Supertip";
 +
        }
 +
 
 +
        void _myCheckBox_OnGetScreentip(IRibbonControl control, out string screentip)
 +
        {
 +
            System.Diagnostics.Debug.Print("_myCheckBox_OnGetScreentip called...");
 +
 
 +
            screentip = "My CheckBox Screentip";
 +
        }
 +
 
 +
        void _myCheckBox_OnGetPressed(IRibbonControl control, out bool pressed)
 +
        {
 +
            System.Diagnostics.Debug.Print("_myCheckBox_OnGetPressed called...");
 +
            // The checkbox will not be ticked to begin with
 +
            pressed = false;
 +
        }
 +
 
 +
        void _myCheckBox_OnGetLabel(IRibbonControl control, out string label)
 +
        {
 +
            System.Diagnostics.Debug.Print("_myCheckBox_OnGetLabel called...");
 +
 
 +
            label = "My CheckBox";
 +
        }
 +
 
 +
        void _myCheckBox_OnGetKeytip(IRibbonControl control, out string keytip)
 +
        {
 +
            System.Diagnostics.Debug.Print("_myCheckBox_OnGetKeytip called...");
 +
 
 +
 
 +
            keytip = "K";
 +
        }
 +
 
 +
        void _myCheckBox_OnGetEnabled(IRibbonControl control, out bool enabled)
 +
        {
 +
            System.Diagnostics.Debug.Print("_myCheckBox_OnGetEnabled called...");
 +
 
 +
            enabled = true;
 +
        }
 +
 
 +
        void _myCheckBox_OnGetDescription(IRibbonControl control, out string description)
 +
        {
 +
            System.Diagnostics.Debug.Print("_myCheckBox_OnGetDescription called...");
 +
 
 +
            description = "My CheckBox description";
 +
        }
 +
 
 +
        void _myCheckBox_OnActionEvent(IRibbonControl control, ref bool pressed)
 +
        {
 +
            System.Diagnostics.Debug.Print("_myCheckBox_OnActionEvent called...");
 +
 
 +
            MessageBox.Show("Checkbox " + (pressed ? "clicked" : "un-clicked"));
 +
        }
 +
    }
 +
 
 +
}
 +
</syntaxhighlight>
 +
 
 +
* Modify class ThisAddin in ThisAddin.cs as follows
 +
<syntaxhighlight lang="csharp" line>
 +
namespace RibbonCommanderAddin
 +
{
 +
    public partial class ThisAddIn
 +
    {
 +
        private CheckBoxEventsUI _myCustomUI;
 +
 
 +
        private void ThisAddIn_Startup(object sender, System.EventArgs e)
 +
        {
 +
            // Show the custom ribbon
 +
            _myCustomUI2 = new CheckBoxEventsUI();
 +
        }
 +
 
 +
        private void ThisAddIn_Shutdown(object sender, System.EventArgs e)
 +
        {
 +
        }
 +
    }
 +
}
 +
</syntaxhighlight>
 +
 
 +
== Remarks ==
 +
See [[Inserting Events Stubs in CS|Inserting Events Stubs in C#]] for instructions on how to leverage Visual Studio to insert event stubs automatically.

Latest revision as of 10:35, 21 October 2013

Prerequisites

We recommend you go through A 'hello world' C# program before going into this example.

Background

You can subscribe to events of Ribbon Commander controls by using .NET events or .NET delegates. Here, we show how it can be done by using .NET events. In general you need to take the following steps:

  • Declare a member variable of the events source control type (e.g. rxCheckBox)
  • Assign the member variable to an object of the type (e.g. instantiate a new variable)
  • Use the standard operator += to add event handlers to events you are interested need to subscribe to. Intellisense allows you to insert event stubs automatically.

Example

In this example we will set up a UI that contains an rxCheckBox control and subscribe to all its events.

  • Add a new class to your project and name it CheckBoxEventsUI
  • Add the following code to your class
  1. // Namespaces of the two Ribbon Commander assemblies 
  2. using IlydaUK.Interop.RibbonCommander;
  3. using IlydaUK.RibbonCommander.Core;
  4.  
  5. namespace RibbonCommanderAddin
  6. {
  7.     class CheckBoxEventsUI
  8.     {
  9.         private rxCustomUI _customUI;
  10.         private rxCheckBox _myCheckBox;
  11.  
  12.         public CheckBoxEventsUI()
  13.         {
  14.             // Instantiate a new rxCustomUI in a new context with id 'my_test_cs_ctx'
  15.             _customUI = rxCustomUI.create("my_test_cs_ctx", "Test C# Context");
  16.  
  17.             _customUI.clear();
  18.  
  19.             // Add a new tab and label it
  20.             rxTab myTab = _customUI.ribbon.tabs.add(new rxTab());
  21.             myTab.label = "My C# Tab";
  22.  
  23.             // Add a new group to the tab and label it
  24.             rxGroup myGroup = myTab.groups.add(new rxGroup());
  25.             myGroup.label = "My C# Group";
  26.  
  27.             // Add a new checkbox to the group and subscribe to all its events
  28.             _myCheckBox = myGroup.checkBoxes.add(new rxCheckBox());
  29.             _myCheckBox.OnActionEvent += _myCheckBox_OnActionEvent;
  30.             _myCheckBox.OnGetDescription += _myCheckBox_OnGetDescription;
  31.             _myCheckBox.OnGetEnabled += _myCheckBox_OnGetEnabled;
  32.             _myCheckBox.OnGetKeytip += _myCheckBox_OnGetKeytip;
  33.             _myCheckBox.OnGetLabel += _myCheckBox_OnGetLabel;
  34.             _myCheckBox.OnGetPressed += _myCheckBox_OnGetPressed;
  35.             _myCheckBox.OnGetScreentip += _myCheckBox_OnGetScreentip;
  36.             _myCheckBox.OnGetSupertip += _myCheckBox_OnGetSupertip;
  37.             _myCheckBox.OnGetVisible += _myCheckBox_OnGetVisible;
  38.  
  39.             // Render the UI
  40.             _customUI.refresh();
  41.  
  42.         }
  43.  
  44.         void _myCheckBox_OnGetVisible(IRibbonControl control, out bool visible)
  45.         {
  46.             System.Diagnostics.Debug.Print("_myCheckBox_OnGetVisible called...");
  47.  
  48.             visible = true;
  49.         }
  50.  
  51.         void _myCheckBox_OnGetSupertip(IRibbonControl control, out string supertip)
  52.         {
  53.             System.Diagnostics.Debug.Print("_myCheckBox_OnGetSupertip called...");
  54.  
  55.             supertip = "My CheckBox Supertip";
  56.         }
  57.  
  58.         void _myCheckBox_OnGetScreentip(IRibbonControl control, out string screentip)
  59.         {
  60.             System.Diagnostics.Debug.Print("_myCheckBox_OnGetScreentip called...");
  61.  
  62.             screentip = "My CheckBox Screentip";
  63.         }
  64.  
  65.         void _myCheckBox_OnGetPressed(IRibbonControl control, out bool pressed)
  66.         {
  67.             System.Diagnostics.Debug.Print("_myCheckBox_OnGetPressed called...");
  68.             // The checkbox will not be ticked to begin with
  69.             pressed = false;
  70.         }
  71.  
  72.         void _myCheckBox_OnGetLabel(IRibbonControl control, out string label)
  73.         {
  74.             System.Diagnostics.Debug.Print("_myCheckBox_OnGetLabel called...");
  75.  
  76.             label = "My CheckBox";
  77.         }
  78.  
  79.         void _myCheckBox_OnGetKeytip(IRibbonControl control, out string keytip)
  80.         {
  81.             System.Diagnostics.Debug.Print("_myCheckBox_OnGetKeytip called...");
  82.  
  83.  
  84.             keytip = "K";
  85.         }
  86.  
  87.         void _myCheckBox_OnGetEnabled(IRibbonControl control, out bool enabled)
  88.         {
  89.             System.Diagnostics.Debug.Print("_myCheckBox_OnGetEnabled called...");
  90.  
  91.             enabled = true;
  92.         }
  93.  
  94.         void _myCheckBox_OnGetDescription(IRibbonControl control, out string description)
  95.         {
  96.             System.Diagnostics.Debug.Print("_myCheckBox_OnGetDescription called...");
  97.  
  98.             description = "My CheckBox description";
  99.         }
  100.  
  101.         void _myCheckBox_OnActionEvent(IRibbonControl control, ref bool pressed)
  102.         {
  103.             System.Diagnostics.Debug.Print("_myCheckBox_OnActionEvent called...");
  104.  
  105.             MessageBox.Show("Checkbox " + (pressed ? "clicked" : "un-clicked"));
  106.         }
  107.     }
  108.  
  109. }
  • Modify class ThisAddin in ThisAddin.cs as follows
  1. namespace RibbonCommanderAddin
  2. {
  3.     public partial class ThisAddIn
  4.     {
  5.         private CheckBoxEventsUI _myCustomUI;
  6.  
  7.         private void ThisAddIn_Startup(object sender, System.EventArgs e)
  8.         {
  9.             // Show the custom ribbon
  10.             _myCustomUI2 = new CheckBoxEventsUI();
  11.         }
  12.  
  13.         private void ThisAddIn_Shutdown(object sender, System.EventArgs e)
  14.         {
  15.         }
  16.     }
  17. }

Remarks

See Inserting Events Stubs in C# for instructions on how to leverage Visual Studio to insert event stubs automatically.

Retrieved from ‘https://documentation.ribboncommander.com/index.php?title=Using_events_in_CS&oldid=3191’