Welcome to MonoGame.Forms!

MonoGame.Forms is the easiest way of integrating a MonoGame render window into your Windows Forms project. It should make your life much easier, when you want to create your own editor environment.

Building

The MonoGame.Forms.DX project uses a modified version of the MonoGame.Framework. It's called MonoGame.Framework.WindowsDX.9000 (created by nkast), which is faster, memory optimized, bugfixed and supports full mouse & keyboard input within WindowsForms. You can also update MonoGame.Forms to a new MonoGame version very easily - just by updating the MonoGame.Framework.WindowsDX.9000 nuget package!
MonoGame.Forms.GL - DEPRECATED! - faster alternative: MonoGame.Template.Gtk.CSharp (created by harry-cpp).

Tips & Tricks / Dos & Don'ts

Never use DoubleBuffering on a custom control. It will cause flickering and slow downs.
If you experience scaling issues with your drawn content, then you might want to set the right AutoScaleMode of a Form containing a MonoGameControl: AutoScaleMode = System.Windows.Forms.AutoScaleMode.None;. If you want to turn off scaling of your whole application, then you need to add a Manifest-File. NEW: Now you can also directly install the Visual Studio templates.

How-To

Setup MonoGame.Forms

First you need to make your MonoGame.Forms library ready to use. This step is very easy; you just need to compile the MonoGame.Forms.DX library from source and then just add the compiled DLL's to your project.

↳ This is the prefered route, when you want to make you own custom changes to the library or extend it.

Another option is to install the library with the NuGet package manager:

↳ This is the prefered and easiest route to be automatically up to date.

Tutorial

Creating a simple MonoGameControl

Let's start using the MonoGame.Forms library by creating a simple control to render stuff!

(it's assumed that you already have created a new Windows Forms project with the installed library)

Create a new class and name it DrawTest
Inherit from MonoGame.Forms.Controls.MonoGameControl
Override its Initialize(), Update() and Draw() method
Save your solution
Build your solution
Double Click on Form1.cs so that the designer opens
Open the Toolbox
Drag & Drop the newly created control onto the Form1 control
Open the Properties of the new control and set the Dock option to Fill

This is how it should look now:

Now run the solution and see the classical CornflowerBlue-Screen you are (surly) familiar with! ;-)

And yes, as you can see: it is realy THAT EASY!

Now I bet you wonder how to draw something to this control, right? I bet you think that this is now the difficult part, right? Well... it's not!

More than that it's basically the same like you are used to do in the MonoGame.Framework. Just with a small difference (no it's still not difficult!)

In MonoGame you could draw someting to the screen with the SpriteBatch. In MonoGame.Forms you will do the same but you need to use the GFXService for this.

In the MonoGameControl class this service is called Editor. To draw something to the SpriteBatch you need to do this:

Editor.spriteBatch.DrawString();

Do you see? Easy! :)

The GFXService class contains some MonoGame specific stuff like a ContentManager. Examine everything calmly. I just want to explain a little how MonoGame.Forms works under the hood!

To sum things up, let's take a look at the final DrawTest class:

using Microsoft.Xna.Framework;
using MonoGame.Forms.Controls;

namespace nugetTest
{
    public class DrawTest : MonoGameControl
    {
        string WelcomeMessage = "Hello MonoGame.Forms!";

        protected override void Initialize()
        {
            base.Initialize();
        }
        
        protected override void Update(GameTime gameTime)
        {
            base.Update(gameTime);
        }

        protected override void Draw()
        {
            base.Draw();

            Editor.spriteBatch.Begin();

            Editor.spriteBatch.DrawString(Editor.Font, WelcomeMessage, new Vector2(
                (Editor.graphics.Viewport.Width / 2) - (Editor.Font.MeasureString(WelcomeMessage).X / 2),
                (Editor.graphics.Viewport.Height / 2) - (Editor.FontHeight / 2)),
                Color.White);

            Editor.spriteBatch.End();
        }
    }
}

Result:

It's pretty much like in the MonoGame.Framework!

I just want to refer to the nice MonoGame.Forms.Test-Project, which is part of this repo. Take a look at it and learn from its samples.

BTW: did you notice the BackColor and ForeColor property? Changing these values makes it possible to style your controls to something like this:

Do it to keep the overview and feel of your custom editor project!

Note: The MonoGame logo is placed automatically inside a newly created control (during design-time) to make it clear, that it is a render control with MonoGame functionality!

Creating a simple InvalidationControl

This specific control class doesn't need to override the Update() method, because it gets manually invalidated (by you!).

If you are changing the drawn contents of the SpriteBatch when your editor project is running (not during design time), then you simply need to call Invalidate() on a custom control for every change you want to see on your control. This command commits those changes and after that your control does not consume CPU power anymore. This process is great when creating preview controls for textures and similar things!