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

From Ribbon Commander Documentation
Jump to: navigation, search
(Subscribing to the button's events)
(Subscribing to the button's events)
Line 134: Line 134:
 
*# intellisense picks up and prompts you to press tab to insert the stub:
 
*# intellisense picks up and prompts you to press tab to insert the stub:
 
*#: [[image:InsertingEventStubCS.png|border|link=]]
 
*#: [[image:InsertingEventStubCS.png|border|link=]]
 +
*# Press tab twice to insert the delegate stub and change it to display the message box as above
  
 
== Remarks ==
 
== Remarks ==

Revision as of 13:31, 15 March 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 MyCustomUI.
  • Add the following code to your class
  1. // Namespaces of the two Dynamic RibbonX assemblies 
  2. using LogismiX.Interop.DynamicRibbonX;
  3. using LogismiX.DynamicRibbonX.Core;
  4.  
  5. namespace DynamicRibbonXAddin
  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 DynamicRibbonXAddin
  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

  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 enter 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

Remarks

  • rxCustomUI contexts are identified by their unique context ids (e.g. 'my_test_cs_ctx' above). When an rxCustomUI is 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 rxCustomUIs in it.
  • You can use rxCustomUI.clear to clear a context's state


Making our code more compact

The Dynamic RibbonX API is composable, which we can take advantage to make our code more compact:

  1. namespace DynamicRibbonXAddin
  2. {
  3.     class MyCustomUI2
  4.     {
  5.         private rxCustomUI _customUI;
  6.  
  7.         public MyCustomUI2()
  8.         {
  9.             // Instantiate a new rxCustomUI in a new context with id 'my_test_cs_ctx'
  10.             _customUI = rxCustomUI.create("my_test_cs_ctx", "Test C# Context");
  11.  
  12.             // Add a new tab and label it
  13.             _customUI.ribbon.tabs.add(new rxTab
  14.             {
  15.                 label = "My First Tab"
  16.             });
  17.  
  18.             // Render the UI
  19.             _customUI.refresh();
  20.         }
  21.     }
  22. }