Difference between revisions of "Creating our first button in CS"

From Ribbon Commander Documentation
Jump to: navigation, search
(→‎Code Analysis)
(→‎Creating a button)
 
(17 intermediate revisions by the same user not shown)
Line 3: Line 3:
 
== Prerequisites ==
 
== Prerequisites ==
 
We recommend you go through [[A 'hello world' CS program|A 'hello world' C# program]] 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.
−
 
  
 
== Creating a button ==
 
== Creating a button ==
−
* Add a new class to [[Creating a new project in CSharp|your project]] and name it MyCustomUI.
+
* Add a new class to [[Creating a new project in CSharp|your project]] and name it MyCustomUI2
 
* Add the following code to your class
 
* Add the following code to your class
  
 
<syntaxhighlight lang="csharp" line>
 
<syntaxhighlight lang="csharp" line>
−
// Namespaces of the two Dynamic RibbonX assemblies  
+
// Namespaces of the two Ribbon Commander assemblies  
−
using LogismiX.Interop.DynamicRibbonX;
+
using IlydaUK.Interop.RibbonCommander;
−
using LogismiX.DynamicRibbonX.Core;
+
using IlydaUK.RibbonCommander.Core;
  
−
namespace DynamicRibbonXAddin
+
namespace RibbonCommanderAddin
 
{
 
{
 
     class MyCustomUI2
 
     class MyCustomUI2
Line 49: Line 48:
 
* Modify class ThisAddin in ThisAddin.cs as follows
 
* Modify class ThisAddin in ThisAddin.cs as follows
 
<syntaxhighlight lang="csharp" line>
 
<syntaxhighlight lang="csharp" line>
−
namespace DynamicRibbonXAddin
+
namespace RibbonCommanderAddin
 
{
 
{
 
     public partial class ThisAddIn
 
     public partial class ThisAddIn
Line 71: Line 70:
 
*: [[image: CSFirstButton.png|link=]]
 
*: [[image: CSFirstButton.png|link=]]
  
−
== Code Analysis ==
+
== Code Analysis I ==
 
<syntaxhighlight lang="csharp" line start="22">
 
<syntaxhighlight lang="csharp" line start="22">
 
// Add a new group to the tab and label it
 
// Add a new group to the tab and label it
Line 79: Line 78:
 
Each [[rxTab]] object has a collection of rxGroup objects (accessible through its ''groups'' property). Here we add a new group to our tab's groups and label it 'My C# Group'
 
Each [[rxTab]] object has a collection of rxGroup objects (accessible through its ''groups'' property). Here we add a new group to our tab's groups and label it 'My C# Group'
  
−
<syntaxhighlight lang="csharp" line start="17">
+
 
 +
<syntaxhighlight lang="csharp" line start="26">
 +
// Add a new button to the group and label it
 +
rxButton myButton = myGroup.buttons.add(new rxButton());
 +
myButton.label = "Click Me!";
 
</syntaxhighlight>
 
</syntaxhighlight>
 +
Each [[rxGroup]] object has a collection of [[rxButton]] objects (accessible through its ''buttons'' property). Here we add a new button to our group and label it 'Click Me!'
  
−
== Remarks ==
 
−
* [[rxCustomUI]] contexts are identified by their unique context ids (e.g. 'my_test_cs_ctx' above). When an rxCustomUI is [[Method create|created]] with a ''contextId'' that doesn't correspond to an existing context, the context gets created. Otherwise the [[rxCustomUI]] joins the context and shares its state with other [[rxCustomUI]]s in it.
 
−
* You can use ''rxCustomUI.clear'' to clear a context's state
 
  
 +
== Subscribing to the button's events ==
 +
At the moment the new button isn't of much use  as it does nothing when clicked. In this section we will subscribe to the button's ''onAction'' event and display a message box when clicked.
  
−
== Making our code more compact ==
+
* Update the class as follows.
−
The Dynamic RibbonX API is composable, which we can take advantage to make our code more compact:
+
<syntaxhighlight lang="csharp" line highlight="24">
−
<syntaxhighlight lang="csharp" line>
+
class MyCustomUI2
−
namespace DynamicRibbonXAddin
+
 
{
 
{
−
     class MyCustomUI2
+
     private rxCustomUI _customUI;
 +
    private rxButton _myButton;
 +
 
 +
    public MyCustomUI2()
 
     {
 
     {
−
         private rxCustomUI _customUI;
+
         // Instantiate a new rxCustomUI in a new context with id 'my_test_cs_ctx'
 +
        _customUI = rxCustomUI.create("my_test_cs_ctx", "Test C# Context");
  
−
         public MyCustomUI2()
+
         _customUI.clear();
−
        {
+
−
            // Instantiate a new rxCustomUI in a new context with id 'my_test_cs_ctx'
+
−
            _customUI = rxCustomUI.create("my_test_cs_ctx", "Test C# Context");
+
  
−
            // Add a new tab and label it
+
        // Add a new tab and label it
−
            _customUI.ribbon.tabs.add(new rxTab
+
        rxTab myTab = _customUI.ribbon.tabs.add(new rxTab());
−
            {
+
        myTab.label = "My C# Tab";
−
                label = "My First 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 button to the group and label it
 +
        _myButton = myGroup.buttons.add(new rxButton());
 +
        _myButton.label = "Click Me!";
 +
        _myButton.OnActionEvent += _myButton_OnActionEvent;
 +
              
 +
        // Render the UI
 +
        _customUI.refresh();
  
−
            // Render the UI
+
    }
−
            _customUI.refresh();
+
 
−
         }
+
    void _myButton_OnActionEvent(IRibbonControl control)
 +
    {
 +
         MessageBox.Show("Hello from C#!");
 
     }
 
     }
 
}
 
}
 
</syntaxhighlight>
 
</syntaxhighlight>
 +
* Notice that we need to make the button a member of our class in order to subscribe to its events
 +
* The .NET framework makes it easy to [[Inserting Events Stubs in CS|insert event stubs]]:
 +
*# type <code>_myButton.OnActionEvent +=</code>
 +
*# intellisense picks up and prompts you to press tab to insert the stub:
 +
*#: [[image:InsertingEventStubCS.png|border|link=]]
 +
*# Press tab twice to insert the delegate stub and change it to display the message box as above
 +
* If everything went according to plan the button will now display the following message when clicked:
 +
*: [[image: FristButtonCSMsgBox.png|link=]]
 +
 +
== Code Analysis II ==
 +
<syntaxhighlight lang="csharp" line start="24">
 +
_myButton.OnActionEvent += _myButton_OnActionEvent;
 +
</syntaxhighlight>
 +
[[rxButton]] has a number of [[rxButton#Events|events]] you can subscribe to. Here we subscribed to the button's 'onAction' event which fires when the button is clicked.
 +
 +
== Remarks ==

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.

Creating a button

  • Add a new class to your project and name it MyCustomUI2
  • 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 MyCustomUI2
  8.     {
  9.         private rxCustomUI _customUI;
  10.  
  11.         public MyCustomUI2()
  12.         {
  13.             // Instantiate a new rxCustomUI in a new context with id 'my_test_cs_ctx'
  14.             _customUI = rxCustomUI.create("my_test_cs_ctx", "Test C# Context");
  15.  
  16.             _customUI.clear();
  17.  
  18.             // Add a new tab and label it
  19.             rxTab myTab = _customUI.ribbon.tabs.add(new rxTab());
  20.             myTab.label = "My C# Tab";
  21.  
  22.             // Add a new group to the tab and label it
  23.             rxGroup myGroup = myTab.groups.add(new rxGroup());
  24.             myGroup.label = "My C# Group";
  25.  
  26.             // Add a new button to the group and label it
  27.             rxButton myButton = myGroup.buttons.add(new rxButton());
  28.             myButton.label = "Click Me!";
  29.  
  30.             // Render the UI
  31.             _customUI.refresh();
  32.  
  33.         }
  34.     }
  35. }
  • Modify class ThisAddin in ThisAddin.cs as follows
  1. namespace RibbonCommanderAddin
  2. {
  3.     public partial class ThisAddIn
  4.     {
  5.         private MyCustomUI2 _myCustomUI;
  6.  
  7.         private void ThisAddIn_Startup(object sender, System.EventArgs e)
  8.         {
  9.             // Show the custom ribbon
  10.             _myCustomUI2 = new MyCustomUI();
  11.         }
  12.  
  13.         private void ThisAddIn_Shutdown(object sender, System.EventArgs e)
  14.         {
  15.         }
  16.     }
  17. }
  • Run the add-in. If everything went according to plan a new tab labeled 'My C# Tab' will appear when the application starts and it will contain a button labeled 'Click Me!' in a group labeled 'My C# Group':
    CSFirstButton.png

Code Analysis I

  1. // Add a new group to the tab and label it
  2. rxGroup myGroup = myTab.groups.add(new rxGroup());
  3. myGroup.label = "My C# Group";

Each rxTab object has a collection of rxGroup objects (accessible through its groups property). Here we add a new group to our tab's groups and label it 'My C# Group' 


  1. // Add a new button to the group and label it
  2. rxButton myButton = myGroup.buttons.add(new rxButton());
  3. myButton.label = "Click Me!";

Each rxGroup object has a collection of rxButton objects (accessible through its buttons property). Here we add a new button to our group and label it 'Click Me!'


Subscribing to the button's events

At the moment the new button isn't of much use as it does nothing when clicked. In this section we will subscribe to the button's onAction event and display a message box when clicked.

  • Update the class as follows.
  1. class MyCustomUI2
  2. {
  3.     private rxCustomUI _customUI;
  4.     private rxButton _myButton;
  5.  
  6.     public MyCustomUI2()
  7.     {
  8.         // Instantiate a new rxCustomUI in a new context with id 'my_test_cs_ctx'
  9.         _customUI = rxCustomUI.create("my_test_cs_ctx", "Test C# Context");
  10.  
  11.         _customUI.clear();
  12.  
  13.         // Add a new tab and label it
  14.         rxTab myTab = _customUI.ribbon.tabs.add(new rxTab());
  15.         myTab.label = "My C# Tab";
  16.  
  17.         // Add a new group to the tab and label it
  18.         rxGroup myGroup = myTab.groups.add(new rxGroup());
  19.         myGroup.label = "My C# Group";
  20.  
  21.         // Add a new button to the group and label it
  22.         _myButton = myGroup.buttons.add(new rxButton());
  23.         _myButton.label = "Click Me!";
  24.         _myButton.OnActionEvent += _myButton_OnActionEvent;
  25.  
  26.         // Render the UI
  27.         _customUI.refresh();
  28.  
  29.     }
  30.  
  31.     void _myButton_OnActionEvent(IRibbonControl control)
  32.     {
  33.         MessageBox.Show("Hello from C#!");
  34.     }
  35. }
  • Notice that we need to make the button a member of our class in order to subscribe to its events
  • The .NET framework makes it easy to insert event stubs:
    1. type _myButton.OnActionEvent +=
    2. intellisense picks up and prompts you to press tab to insert the stub:
      InsertingEventStubCS.png
    3. Press tab twice to insert the delegate stub and change it to display the message box as above
  • If everything went according to plan the button will now display the following message when clicked:
    FristButtonCSMsgBox.png

Code Analysis II

  1. _myButton.OnActionEvent += _myButton_OnActionEvent;

rxButton has a number of events you can subscribe to. Here we subscribed to the button's 'onAction' event which fires when the button is clicked.

Remarks

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