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

From Ribbon Commander Documentation
Jump to: navigation, search
(→‎Creating a button)
(→‎Creating a button)
 
(19 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 68: Line 67:
 
</syntaxhighlight>
 
</syntaxhighlight>
  
−
* Run the add-in. If everything went according to plan a new tab labeled 'My First Tab' will appear when the application starts
+
* 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':
−
*: [[image: EmptyTab.png|link=]]
+
*: [[image: CSFirstButton.png|link=]]
  
−
== Code Analysis ==
+
== Code Analysis I ==
−
<syntaxhighlight lang="csharp" line start="14">
+
<syntaxhighlight lang="csharp" line start="22">
−
// Instantiate a new rxCustomUI in a new context with id 'my_test_cs_ctx'
+
// Add a new group to the tab and label it
−
_customUI = rxCustomUI.create("my_test_cs_ctx", "Test C# Context");
+
rxGroup myGroup = myTab.groups.add(new rxGroup());
 +
myGroup.label = "My C# Group";
 
</syntaxhighlight>
 
</syntaxhighlight>
−
[[rxCustomUI]] is at the top of the object model hierarchy. Here we [[Method create|instantiate]] a new [[rxCustomUI]] object in a new context with id 'my_text_cs_ctx' with description 'Test C# Context'
+
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">
−
// Cache a reference to the custom UI's ribbon
+
// Add a new button to the group and label it
−
rxRibbon myRibbon = _customUI.ribbon;
+
rxButton myButton = myGroup.buttons.add(new rxButton());
 +
myButton.label = "Click Me!";
 
</syntaxhighlight>
 
</syntaxhighlight>
−
Each [[rxCustomUI]] object owns a unique [[rxRibbon]] object. Here, we are caching a reference to the [[rxRibbon]] object of _customUI
+
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!'
  
  
−
<syntaxhighlight lang="csharp" line start="20">
+
== Subscribing to the button's events ==
−
// Create a new tab and label it 'My Tab'
+
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.
−
rxTab myTab = new rxTab();
+
−
myTab.label = "My First Tab";
+
−
</syntaxhighlight>
+
−
Here, we create a new [[rxTab]] object and give it a label
+
  
 +
* Update the class as follows.
 +
<syntaxhighlight lang="csharp" line highlight="24">
 +
class MyCustomUI2
 +
{
 +
    private rxCustomUI _customUI;
 +
    private rxButton _myButton;
  
−
<syntaxhighlight lang="csharp" line start="24">
+
    public MyCustomUI2()
−
// Add the tab to myRibbon's tabs
+
    {
−
myRibbon.tabs.add(myTab);
+
        // Instantiate a new rxCustomUI in a new context with id 'my_test_cs_ctx'
−
</syntaxhighlight>
+
        _customUI = rxCustomUI.create("my_test_cs_ctx", "Test C# Context");
−
Each [[rxRibbon]] object has a {{collection}} of [[rxTab]] objects (accessible through its ''tabs'' property). Here we add the tab we created above to our ribbon's tabs
+
  
−
<syntaxhighlight lang="csharp" line start="27">
+
        _customUI.clear();
−
// Render the UI
+
−
_customUI.refresh();
+
−
</syntaxhighlight>
+
−
To ensure optimal performance, UI updates always take place in two steps:
+
−
# Update the target [[rxCustomUI]] state, which we have done above
+
−
# Render the updated UI, which we are doing here
+
  
 +
        // Add a new tab and label it
 +
        rxTab myTab = _customUI.ribbon.tabs.add(new rxTab());
 +
        myTab.label = "My C# Tab";
  
−
== Remarks ==
+
        // Add a new group to the tab and label it
−
* [[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.
+
        rxGroup myGroup = myTab.groups.add(new rxGroup());
−
* You can use ''rxCustomUI.clear'' to clear a context's state
+
        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();
  
−
== Making our code more compact ==
+
    }
−
The Dynamic RibbonX API is composable, which we can take advantage to make our code more compact:
+
 
−
<syntaxhighlight lang="csharp" line>
+
     void _myButton_OnActionEvent(IRibbonControl control)
−
namespace DynamicRibbonXAddin
+
−
{
+
−
     class MyCustomUI2
+
 
     {
 
     {
−
         private rxCustomUI _customUI;
+
         MessageBox.Show("Hello from C#!");
−
 
+
−
        public MyCustomUI2()
+
−
        {
+
−
            // 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
+
−
            _customUI.ribbon.tabs.add(new rxTab
+
−
            {
+
−
                label = "My First Tab"
+
−
            });
+
−
 
+
−
            // Render the UI
+
−
            _customUI.refresh();
+
−
        }
+
 
     }
 
     }
 
}
 
}
 
</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’