Coherent UI for .NET  2.5.3
A modern user interface library for games
 All Classes Namespaces Functions Variables Enumerations Enumerator Properties Events Pages
.NET Controls (Windows.Forms, WPF, GTK#)

There are three types of Coherent UI user controls available for .NET.
These are the Windows.Forms, WPF and GTK# BrowserViewControl controls. The first two are available for Windows(Visual Studio) only, and the GTK# is for Linux(Mono).

The general usage pattern for these controls is to drag the control from the toolbox to your form area. Then (almost) everything is automagically working!

There are a few points that are worth noting:

  • The control's property UsesOwnUISystem defines whether the control uses an UI System initialized with the default arguments.
    If set to true, you must call the control's static method SetCoherentKey to set the license key for Coherent UI. This must be done before initializing the controls. All samples have controls with this property set to true. What happens behind the scenes is that a single UI System is initialized and all controls with this property set to true use it. You can check each sample's code to see the proper place for calling the method.
    If the property is false, you must create a UISystemHelper and then initialize the control by calling its InitializeWithHelper method. Generally, using an own UI System should suffice, unless you need some custom behavior, such as setting up custom log file.
  • The UI System must be updated regularly. The default update interval is 33ms. You can modify that interval for controls using own UI Systems with the SetUpdateInterval method.
    For controls not using own UI Systems this interval is specified in the UISystemHelper constructor.
  • The user controls have overloads for key/mouse events. This means that when the control is focused, all input is automatically forwarded to Coherent UI.
    If the control is not be focused, but the user still wants to forward events, this can be done using the public methods ProcessXXX(XXXEvent e), where XXX is some event, e.g. MouseUp.
    If automatic forwarding is undesirable, the user should make a derived control and override the OnXXX methods.

The samples using the Coherent UI controls represent a very basic browser. Basically, there is a navigation textbox and a single BrowserViewControl, displaying HTML pages.

Windows.Forms

The BrowserViewControl is in the Coherent.UI.Windows.Forms namespace.

There's just a couple of lines of code in Form1.cs that handle pressing Enter in the navigation textbox and set the focus to the control when the mouse is over it. Everything else works automatically as described above (the control has the UsesOwnUISystem property set to true). Note that during re-sizes the control has to re-draw the whole page. If the user re-sizes the control continuously this might lead to some flicker. The control itself tries to minimize this and by default re-sizes its content less often than it receives the events themselves. This ususally leads to a smooth mix of scaling and subsequent proper resizing of the content. However the user can opt to disable the automatic content resizing by setting the AutoResize property to false. In this way the user is now responsible for resizing the content. A good strategy to avoid any stretching and flickering is to remove any anchoring of the control with the Form and resize is manually when the ResizeEnd event is triggered by the Form. In this way the control will remain unchanged during the re-size operation and then set its new size as soon as the user has finished re-sizing the Form. The WPF sample bundled shows a good strategy to implement re-size.

WPF

The BrowserViewControl is in the Coherent.UI.Windows.Controls namespace.

To add the control we define the coui namespace in MainWindow.xaml as follows: xmlns:coui="clr-namespace:Coherent.UI.Windows.Controls;assembly=CoherentUINET". Then, we define the control instance by using <coui:BrowserViewControl ...properties... />.
The code in MainWindow.xaml.cs defines the event handlers for hovering above the control and pressing Enter in the textbox.

GTK#

The BrowserViewControl is in the Coherent.UI.Mono.Gtk namespace.

The main source file is MainWindow.cs. There are handlers for setting focus to the BrowserViewControl when the mouse is over it, and an activation handler(the user pressed Enter) for the entry widget.

In the constructor we explicitly set the DisplayMode property, since it may not show in the designer window in Mono. As stated in the code, Stretched mode causes a performance penalty and using Unscaled is recommended.

Custom view contexts in WinForms

There are 2 ways of having a custom context in the WinForms controls.

  • The first way is to create one as a static resource. Open the Toolbox and find the BrowserViewContext control, then drag it into your form. The control should appear at the bottom of the form editor, since it's non-renderable. If you select the control and open the Properties window you will see the available context settings that you can modify. When you're done configuring the context, select a view control and open its properties. The context you created will appear in the Context dropdown so you can select it.

Here's what the context settings look like:

dotnet_winforms_context_properties.png
WinForms context settings

These are the view control's properties and the context selection through the Properties pane:

dotnet_winforms_context_selection.png
WinForms context selection
  • The second way is to dynamically add a context with code. This is example code that will create a new context and new view control. You can place it in a method of the form (e.g. some event handler). It also adds an event handler for MouseEnter and focuses the control when it's fired. Finally, the control is added to the form.
var context = new BrowserViewContext();
context.AllowCookies = true;
var control = new BrowserViewControl();
control.Context = context;
control.MouseEnter += (s, args) =>
{
control.Focus();
};
control.Location = new Point(10, 40);
control.Size = new Size(1024, 300);
this.Controls.Add(control);

This is what the modified sample looks like after you add a new window and try to login in both forms:

dotnet_winforms_different_contexts.png
WinForms Sample context with cookies

Custom view contexts in WPF

There are 2 ways of having a custom context in the WPF controls.

  • The first way is to create one as a static resource. Add this code to the XAML file:
<Window.Resources>
<coui:BrowserViewContext x:Key="ctxWithCookies" AllowCookies="True"/>
</Window.Resources>

and then set the Context of the BrowserViewControl in the Properties windows. Note that the resource in the XAML code must be declared as StaticResource (and not DynamicResource for example) since the Context property is not a DependencyProperty.

An example XAML file may look like: