WinStudio

Creating a User Control and a User Control Component

This topic gives a simple example of building a .NET WinForms user control and hosting it as a user control component on a WinStudio form. The example illustrates types of communication from a control to WinStudio and from WinStudio to a control. Specifically,

Creating a Simple UserControl Component for the Windows Smart Client

  1. In Visual Studio, create a Windows Forms control library project. Specify a name for the control (in this example, use TestWinStudioUserControl).
  2. In the Visual Studio designer, add a push button, label and text box control.
  3. Add references to MGScriptMgr.dll and WSXRuntime.dll:
    1. In the Solution Explorer, right-click References > Add Reference.
    2. On the Browse tab, browse to the framework installation directory.
    3. Select MGScriptMgr.dll, and click OK.
    4. Repeat steps a and b, select WSXRuntime.dll, and click OK.
  4. Double-click the button and create a handler in the code editor for the button's click event.
  5. At the top of the code, add a "using" line: 
    using Mongoose.WinStudio.Runtime;
  6. Change your class to derive from WinStudio's WSUserControlBase: 
    public partial class UserControl1 : WSUserControlBase
  7. Implement the Invoke method of the IWinStudioUserControl interface with this code. (This example lets you explicitly design which WinStudio events are passed to your control. Alternatively, you can set the property ImplementsGeneralEventIntercept to true in your control, and then WinStudio calls your implementation of the GeneralEventIntercept method for all events generated in the form.) 
    public override bool Invoke( string args )
{
   bool success = true;
   if ( args.Substring( 0, 8 ) == "SETTEXT " )
      this.textBox1.Text = args.Substring( 8, args.Length-8 );
   return success;
}
  8. Inside the button click event handler, use the WinStudio API to generate an event: 
    ThisForm.Variables("UserControlValue").Value = textBox1.Text;
    

ThisForm.GenerateEvent("UserControlClicked");
    (Note that IntelliSense is available for the WinStudio API, as it is when writing client WinStudio scripts.)
  9. Save and build the control.
  10. Copy the resulting .dll file to your framework directory.
  11. In WinStudio, open or create a form that has a collection on it and that you want to use for this test. Create a UserControl component. In the miscellaneous section of its properties, use the ellipses on UserControlName to browse to your user control dll.
  12. Create a Button component that generates the event SetUserControlText.
  13. Create an event handler of type UserControlInvoke. Click into the parameters and specify your UserControl component, with the parameters 
    "SETTEXT P(propname)"
    specifying the name of a property on the form.
  14. Create an event handler of type SetValues for the event UserControlClicked. Click into the parameters, and set a property on your form with the value 
    V(UserControlValue): SETPROPVALUES(propname=V(UserControlValue))

    The result should be that you can type in a component bound to the property you used on your form and click the button, to display the property's value in your user control, and click on the user control's button to move the text from your user control into the property you used.

NOTE: The steps to create a WinStudio-hostable user control from a specific existing user control are very similar. Rather than derive a new class from WSUserControlBase and IWinStudioUserControl, you add a reference to the existing specific user control and derive from that class and the IWinStudioUserControl interface.

Creating a Simple UserControl Component for the Web

These steps implement the same functionality as in the Windows control above, and assume that you are working in the same form, creating a UserControl component that works both in Windows and the Web.

NOTE: The Web user control should be a project created using .NET 4/Visual Studio 2010.

  1. Create a .Net class library project named TestWebUserControl, adding references to the framework assemblies IDOProtocol, MGScriptMgr, MGShared, and MGWebEngine. Add a using statement for Mongoose.WinStudio.Runtime.
  2. Derive your class from the WSUserControlBase class.
  3. Implement the Invoke and/or GeneralEventIntercept methods as described above. In this example, we will implement the Invoke method. In the Web case, the Invoke method is called both when a WinStudio InvokeUserControl event handler executes and also when your Web content calls the javascript API WSUserControl.generateServerEvent. Use this code: 
    {
   Public Overrides Function Invoke(ByVal args As String) As Boolean
      If args = "READY" Then
         Me.QueueClientResponse("SETTEXT Server link established.")
      ElseIf args.Substring(0, 8) = "SETTEXT " Then
         Me.QueueClientResponse(args)
      ElseIf args.Substring(0, 8) = "FROMWEB " Then
         ThisForm.Variables("UserControlValue").Value =
         args.Substring(8, args.Length - 8)
         ThisForm.GenerateEvent("UserControlClicked")
      End If
      Return True
   End Function
}
  4. Save and build your assembly.
  5. Copy the resulting .dll file to your Web Client application folder, for example, C:\inetpub\wwwroot\WSWebClient\Application\MySL, where MySL is the application ID specified in the Configuration Manager.

    If the assembly must be available to all applications, copy it instead to the Application folder, for example, C:\inetpub\wwwroot\WSWebClient\Application\. If the file exists in both places, the first folder specified above takes precedence.

  6. Create a Web page that contains the user interface portion of your "user control." You can use any Web technology to do this; however, our simple example uses html/javascript, saved in the Web server under the name TestWebUserControl.htm. Note that you must include the javascript WSUserControl.js, register a callback as shown below, and use the WSUserControl.queueServerEvent function to call back to your hosted assembly. The HTML file looks like this: 
    <html>
<head>
   
   <title>Simple User Control
   <script type="text/javascript" src="Scripts/WSUserControl.js">
   <script type="text/javascript">
      function handleResponse(msg) {
         // callback from WinStudioRuntime hosting the server portion of the usercontrol
         // Button on parent Form was clicked.  Update a field on the Control using passed in values.
         // stripping off the leading "SETTEXT "
         var newValue = msg.split(" ").slice(1).join(" ");
         document.getElementById("MainContent_TextBox").value = newValue;
      }
      // Clicking link on UserControl fires an event that is passed to the hosted assembly's Invoke
      function linkClicked() {
         // this will call back into the hosted UserControl assembly's Invoke method
         var newValue = document.getElementById("MainContent_TextBox").value;
         WSUserControl.generateServerEvent("FROMWEB " + newValue);
      }
      function pageInit() {
         // Register Callback - Parent Form will call this method for all data being passed
         WSUserControl.registerCallback(handleResponse);
         
         // When communication has been established, send READY message to server
         WSUserControl.onReady(function() {
            WSUserControl.generateServerEvent("READY");
         });
      }
   </script>
</head>
<body onload="pageInit()">
   <p>
      <a href="#" onclick="linkClicked()">To Form
   </p>
   <p>
      Content from Form
      <input type="text" id="MainContent_TextBox" />
   </p>
</body>
</html>
  7. Open the same form used in the Windows example. Edit your UserControl component and drill into the UserControlName. Use the ellipses to specify your Web assembly and the URL to your Web page.
  8. Save the form and test in both Web rendering and in WinStudio.

Related Topics

Invoke User Control Response Type