How to write a CamBam plugin

[mrbean]

So...  Here goes my plugin writing tutorial.
Obviously 10bulls would be more suited to this, but he's busy, so you got me instead. 

The saying, "The blind leading the blind", comes to mind.

Anyhow....  This plugin is about as basic as it gets.
It hooks it's self into CamBam's plugin menu.
Displays it's User Interface, (GUI).
And just to show some interaction with CamBam, it reads and displays the current "units" setting from CamBam.

The plugin was written in C# using Visual Studio Express Edition, which can be downloaded and used for free. 
http://msdn.microsoft.com/vstudio/express/

You can download the plugin below if you want to try it out.  You must put it in CamBam's plugin folder.
Project files and code will follow shortly.

[mrbean]

The project files are included at the bottom of this post.
I'll put a brief description of the main bits of code here.

This section is the code that adds your plugin to the menu structure in CamBam and displays the plugin window when the menu item is clicked.

Code: [Select]

using System;
using System.Collections.Generic;
using System.Text;
using System.Windows.Forms;
using System.Drawing;
using System.ComponentModel;
using System.Data;
using CamBam.CAD;
using CamBam.Geom;
using CamBam.UI;


namespace Demo_Plugin
{
    public class Demo
    {
        public Demo()
        {
        }

        public static void InitPlugin(CamBamUI ui)
        {
            MenuItem demomi = new MenuItem();
            demomi.Text = "Demo Plugin";
            demomi.Click += new EventHandler(plugin_clicked);
            ui.Menus.mnuPlugins.MenuItems.Add(demomi);
        }

        public static void plugin_clicked(object sender, EventArgs e)
        {
            DemoForm iface = new DemoForm();
            iface.Owner = CamBam.ThisApplication.TopWindow;
            iface.Show();

        }
    }
}

This next section is the part that gets the "Units" information from CamBam:
The actual line that does the business is:
CamBam.UI.CamBamUI.MainUI.CADFile.DrawingUnits.ToString()

Code: [Select]

using System;
using System.Collections.Generic;
using System.ComponentModel;
using System.Data;
using System.Drawing;
using System.Text;
using System.Windows.Forms;

namespace Demo_Plugin
{
    public partial class DemoForm : Form
    {
        public DemoForm()
        {
            InitializeComponent();
            lbl_units.Text="Current Drawing Units are "+(CamBam.UI.CamBamUI.MainUI.CADFile.DrawingUnits.ToString());
        }
    }
}
That's the two main code sections.  Download the project files and extract the archive to Visual Studio's Projects folder.
Most likely this will be located at: (C:\Documents and Settings\username\My Documents\Visual Studio 2005\Projects)

Currently there is no documentation on the internals of CamBam's dll's, but intellisense, and the object browser in Visual Studio should help find your way around. 

To start a plugin from scratch you should choose, New Project > Class Library. Then add references to the CamBam.CAD and CamBam.Geom dll's.  You can Copy/Paste sections from the code above to speed things up a bit, obviously changing names etc as required.

[bigbigblue]

Can plugins be written in Visual Basic, or is C# REQUIRED?

[10bulls]

You should be able to write plugins using Visual Basic .NET (or other .NET supported languages like C++ and Java).

I can't say I have tried this though, so let me know if you run into problems.

[bigbigblue]

Here is the shell code for a Visual Basic Plugin, took me a little bit of fiddling to get it working, but now it does !

Imports CamBam
Imports CamBam.CAD
Imports CamBam.UI
Imports CamBam.Util
Imports CamBam.ThisApplication
Imports System
Imports System.Text
Imports System.Windows.Forms
Public Class MyPlugin
    Public Sub New()

    End Sub
    Public Shared Sub MyPlugin()
    End Sub
    Public Shared Sub InitPlugin(ByRef ui As CamBamUI)
        Dim mi As New MenuItem()
        mi.Text = "My Plugin"
        AddHandler mi.Click, AddressOf plugin_clicked
        ui.Menus.mnuPlugins.MenuItems.Add(mi)
    End Sub


    Public Shared Sub plugin_clicked(ByVal sender As Object, ByVal e As EventArgs)
        Dim version As String
        version = CamBam.UI.CamBamUI.MainUI.GetVersion.ToString
        MsgBox("CamBam Version is : " + version)
    End Sub

End Class

[bigbigblue]

For my plugin. I would like the user to provide 2 points, and I would like it to work in the same way that the "draw a circle" works on the toolbar, ie the user is prompted to set the points with the mouse.

I am pretty sure it must have something to do with CamBam.CAD.EditMode, but for the life of me I can't work out how to use it !

10Bulls, while you are at the documentation, any chance of more info on the plugin interface and scripting With some examples would be nice
Any help with how to do this would be much appreciated.

Thanks
Pete

[10bulls]

For my plugin. I would like the user to provide 2 points, and I would like it to work in the same way that the "draw a circle" works on the toolbar, ie the user is prompted to set the points with the mouse.

I am pretty sure it must have something to do with CamBam.CAD.EditMode, but for the life of me I can't work out how to use it !

Well spotted!  Yes, EditModes are objects that can 'take control' of the user interface and handle user input.
There is a PointSelectEditMode, which is quite handy.  Here is a code snippet...

Code: [Select]

public void StartPointSelect()
{
    PointSelectEditMode em = new PointSelectEditMode(CamBamUI.MainUI.ActiveView);
    em.DefaultValue = null;
    em.OnReturnOK += new EventHandler(PointSelect_OnReturnOK);
    CamBamUI.MainUI.ActiveView.SetEditMode(em);
    CamBamUI.MainUI.ActiveView.RepaintEditMode();
}

void PointSelect_OnReturnOK(object sender, EventArgs e)
{
    if (sender is PointSelectEditMode)
    {
        if (((PointSelectEditMode)sender).ReturnValue is Point3F)       
        {
            Point3F point = (Point3F)((PointSelectEditMode)sender).ReturnValue;
        }
    }
}

Please don't make me convert that to VB ...my 2nd coffee hasn't kicked in yet. 

For more points, you could create a 2nd PointSelectEditMode in the PointSelect_OnReturnOK handler.

I hope that helps.

[10bulls]

Oh, forgot to mention, you can set the EditMode.Prompt too...for example:

em.Prompt = "Select first point...";

[bigbigblue]

Andy,
That's great - got the point select working (I had spotted the prompt bit ), however, does the editmode run in a separate thread - as it does not appear to halt the main logic? How do I wait until the user has selected a point and how do I retrieve the point in the main logic of the plugin?

Sorry for so many questions.

[10bulls]

The current EditMode runs in the main thread, but not all the time.   All the user input events (mouse,keyboard etc) are passed to the currently selected EditMode.  If the EditMode handles the event it will return true, otherwise the current view will handle it.  The currently active EditMode will keep handling input events until it throws a OnReturnOK or OnReturnCancel event.

You then retrieve the selected point in the OnReturnOK event handler, which will be stored in the ReturnValue property.

How do I wait until the user has selected a point and how do I retrieve the point in the main logic of the plugin?

You split your main plugin logic into 2 parts.  The first part just kicks off the edit mode.
The 2nd part is called by the edit mode's OnReturnOK event handler which does something with the return point.

In your case you would actually need 3 parts, so the 2nd part retrieves the 1st selected point and stores it, then kicks off a 2nd point select edit mode with your 3rd part hooked onto the OnReturnOK handler for that.

I'm sure I could explain that better but I'm starting to think that second coffee was decaf by mistake.   

[bigbigblue]

Right, now I am getting more adventurous.

What I would like to do is have the user click a point, then just like when drawing a circle with the built in CamBam function, I would like the user to be able to drag a polyline out to the size they require and click to confirm the size.

Any pointers as to what CamBam drawing function I could use to achieve this?

Oh, and while I'm asking, is there a function to rotate an object about its centroid, rather than the drawing origin?

Cheers,
Pete

[10bulls]

What I would like to do is have the user click a point, then just like when drawing a circle with the built in CamBam function, I would like the user to be able to drag a polyline out to the size they require and click to confirm the size.

Sizing, scaling, rotation etc are all done through each object's Transform matrix.
However, it sounds like you are wanting to make this more interactive which would mean getting into writing custom EditModes.

If it helps any, the next 0.9.4 release is mostly about improvements to the toolpath generation engine (CAM).
The next round of development for 0.9.5 will focus on improving the user interface and adding to the existing CAD functionality.  This will include nicer ways to interactively scale, stretch and rotate objects.
I'm quite looking forward to that work, as with toolpath and geometry work, I can spend days and even weeks writing, testing and debugging a concept that most users won't notice (other than hopefully their cutters won't snap).
Whereas with the UI stuff, a few days tinkering can bring the 'look and feel' of the program on leaps and bounds.

Oh, and while I'm asking, is there a function to rotate an object about its centroid, rather than the drawing origin?

There is no single function to do this.  In code you could do it easily by manipulating the transform matrices.
In the UI, you could do something like this.
. Select object, then Draw -> Pointlist -> Centers (or Extents)
. Edit->Transform->Center
. Rotate the object by using the transform matrix editor
. Then Edit->Transform->Translate (click the origin as the source and the original center as destination)

[bigbigblue]

Andy,
Thanks for the info - look forward to the new functionality :-)
Is there any documentation concerning the transform matrices which I could refer to?

Cheers
Pete

[Hans_G]

Is there any documentation concerning the transform matrices which I could refer to?

Read the MSDN documentation for the System.Drawing.Drawing2D namespace: http://msdn.microsoft.com/en-us/library/system.drawing.drawing2d.aspx  Start with the Matrix class, in the "See Also" section there is a link to an article on coordinate systems and transformations.  Hopefully one of those will answer your questions, or help you find what you're looking for eventually.  Also, if you read up on the GraphicsPath class some of the conventions in CamBam will suddenly make a lot more sense.

[lazer]

Hello Peter

In attached, a picture class_cambam_cad.bmp 1997X1162.
Take a look in class.
When the plugin create, publish in the session "Scritps and Plugins" with the source in C #. 

Cheers
Armando