BrandonM's Total War Toolset - Plugin Example

[BrandonM]

A number of people have expressed interest in creating plugins for the Toolset.
So here are some instructions and a sample plugin with Source.

This is an example Plugin for my Total War Toolset.
Most of the work is done in the IPlugin_Example.cs file
so make sure to read that.

This may seem like a ton of work, but really it only takes a few
minutes to get the plugin up and running. The bulk of your time
will be spent on making the editor/tool/whatever, not setting up
the plugin interface. (Hopefully)

Classes can be created using C# or VB.NET. The Example plugin and the instructions here are in C#, but should be able to
be easily understood and used by VB.NET developers.

Basic Steps
1> From Visual Studio - Create a new project of type Class Library - Name it Plugin_NameOfYourPlugin
2> Add a Reference to BMTWTSPluginInterface.DLL
3> Add a Reference to BM_M2TWDAL.DLL - If you plan on using my M2TWDAL to Read/Write Files and/or alter/share data with the Framework .
4> Either Add a New Class or in the Class1.cs file that is auto-created Make sure you have a Unique Namespace
- I use the same as the Class Library Name (Plugin_NameOfYourPlugin)
5> Add the following references in the class file:
using System;
using BMTWTS;
using System.Windows.Forms;
using System.IO;
using System.Xml;
using System.Reflection;

6> Have the class be called IPlugin_NameOfYourPlugin
7> Have the class inherit the BMTWTS.IBMTWTSPlugin class.

----------------------------------------------------------------
Example> The FIle should currently look something like this:

using System;
using BMTWTS;
using System.Windows.Forms;
using System.IO;
using System.Xml;
using System.Reflection;

//Give the plugin a unique namespace
namespace Plugin_Example
{

    //Make a class inheriting the BMTWTS.IBMTWTSPlugin Interface
    //I name mine IPlugin_NameOfPlugin

    public class IPlugin_Example : BMTWTS.IBMTWTSPlugin
    {       
        public IPlugin_Example()
        {
        
        }
    }
}

------------------------------------------------------------------

8> Add this private variable to the Class: private static IBMTWTSApp refPFApp;
9> Add these two functions to the class:

------------------------------------------------------------------------------------------------------------------

        public void InitializeAddin(ref IBMTWTSApp refProjectFrameworkApp, long lSession, bool bFirstLoad)
        {
            refPFApp = refProjectFrameworkApp;

            Assembly thisAssembly = Assembly.GetExecutingAssembly();
        
            //Have this Strem point to the embed XMLMenu.xml file - the path is namespace.XMLMenu.xml (If you rename the XMLMenu.xml file, make sure to rename it here)
            //Make sure the XMLMenu.xml file is an Embedded Resource.  By default it's content.  Change it's properties in the properties pane.
            Stream rgbxml = thisAssembly.GetManifestResourceStream("Plugin_Example.XMLMenu.xml");
            XmlDocument doc = new XmlDocument();
            doc.Load(rgbxml);
            string strMenuXML = doc.InnerXml;
            refProjectFrameworkApp.AddCommandsInfo(strMenuXML, lSession, (object)this.GetType().Module, null);            
        }
        public void UnInitializeAddin(long lSession)
        {
            MessageBox.Show("UnInitializeAddin", "Example Plugin");
        }

--------------------------------------------------------------------------------------------------------------------

10> In the InitializeAddin Function, change the line: Stream rgbxml = thisAssembly.GetManifestResourceStream("Plugin_Example.XMLMenu.xml");
You need to change the Plugin_Example.XMLMenu.xml to Plugin_NameOfYourPlugin.XMLMenu.xml

11> Add a function that makes your Plugin start. It can be called anything and do anything, but this function is what fires
when the user selects your plugin from the menu.

Example> This function creates a form, gets a reference to the Framework M2TWDAL DataSet, and opens the windows.
---------------------------------------------------------

        //You will need to create a Form in the project
        //In/On the Form you will need to make a public variable of type:   public M2TWDAL.M2TWDataSet
        public void LaunchForm()
        {            
            
            frmExample frm = new frmExample();
            refPFApp.Get_M2TW_DataSet(ref frm.M2DS);
            frm.ShowDialog();            
        }

---------------------------------------------------------

12> Create a New XML File named XMLMenu.xml.
13> Change it's Properties->Build Action to Embedded Resource - Very Important.
14> This file is what controls what Menus show up in the Framework and what Functions those Menu items fire.
15> Copy in the text below and alter it to your needs.
Example>
-------------------------------------------------------------------------------------

<ProjectFrameworkAddin>
  <AppVer>2</AppVer>
  <AddinName>Example Plugin</AddinName>
  <ToolbarButtonCount>1 </ToobarButtonCount>
  <MainMenu>
    <Name>Examples</Name>
    <ShortcutKeyIndex>2</ShortcutKeyIndex>
    <SubMenu>
      <Name>Example Sub Menu</Name>
      <ShortcutKeyIndex>2</ShortcutKeyIndex>
      <LeafMenu>
        <Name>Example Item 1</Name>
        <FunctionName> LaunchForm </FunctionName>
        <HelpString> Example Form Help</HelpString>
        <ToolTip>Example Form ToolTip </ToolTip>
        <ToolBarIndex>PluginExample.ico</ToolBarIndex>
        <ShortCutKey>Ctrl+E</ShortCutKey>
      </LeafMenu>

    </SubMenu>

  </MainMenu>


</ProjectFrameworkAddin>

----------------------------------------------------------------------------------------------------------------------

<AddinName> Change this to the name of your plugin
<ToolbarButtonCount> Each Plugin gets it's own toolbar, you can put buttons on it. This is how many buttons you have. Put in 0 if you don't want a Toolbar.
<MainMenu> Section
<Name> This is what shows up at the very top of the Menu Bar, with File, Settings, Help. Do not use one of those three. You can use anything else, but
try to keep it consistant with the rest of the Toolset. If this is an Editor, put Tools here.

<SubMenu> Section
<Name> This is the SubMenu. Again, put whatever you want but keep it consistant. If this is an Editor put Editors here.

<LeafMenu> Section
<Name> This is what actually launches a function. Put the Name of your plugin here.
<FunctionName> This is the Function that fires when you choose this Menu Item. In our Example we would but LaunchForm here.

----------------------------------------------------------------------------------------------------------------------

16> Create any required Forms. In the example I created a frmExample form, and on the form added a variable of type: public M2TWDAL.M2TWDataSet
This is where the bulk of your work will happen. You make it just like any other normal Windows Form.

17> Finally, let the Toolset know your plugin exists. Open up the BMTWTSPlugins.xml file and add a new entry for your plugin. This file is
located where you installed the BMTWTS Program. You will need to provide this xml Snippet for your users to copy/paste into
their BMTWTSPlugins.xml file.


-----------------------------------------------------------------------------------------------------

<Addin>
    <DllName>Plugin_Example.dll</DllName>
    <AddinInterfaceName>Plugin_Example.IPlugin_Example</AddinInterfaceName>
    <LoadAddin>1</LoadAddin>
  </Addin>

-----------------------------------------------------------------------------------------------------
<DLLName> The name of your compiled DLL goes here.
<AddinInterfaceName> NameSpace.ClassName
<LoadAddin> 0 = Don't load it , 1 = Load it

18> Make sure you either compile or copy your plugin into the BMTWTS\Plugins Directory.
19> Start the Toolset, see your plugin.



---------------------------------------------------------------------------------

If you want to extend the M2TWDAL to be able to read more files, you can do the following:
1> In a new project create a typed dataset.
2> Create the table structure to support the data
3> Create a Read function and a Write function with the following structure:

    Read_NameOfFile(ref YourM2TWDataSet mds, ref StreamReader sr, Boolean ClearTable);
    //This function should take the referenced DataSet, and the referenced StreamReader and 
    //Fill the appropriate table in the DataSet with    Data.  If the ClearTable value is True, it should Clear() the target table first.

    Write_NameOfFile(ref YourM2TWDataSet mds, ref StreamWriter)
    //This function should use the referenced StreamWriter to create the data text file filled with data from the referenced dataset.

4> Please send the project to me to incorporate into the Master M2TWDAL.

The M2TWDAL can currently do the following:
Read in ExportDescrUnit
Read in ExportDescrCharacterTrait
Read in DescrSmFactions
Write ExportDescrUnit