terraineer SourceForge.net Logo

how to write a terraineer plugin

writing a terraineer plugin is very easy. all you need to know is to know the basics of a mono/.net language and of gtk#.

you can use any mono/.net language you wish to. my choice is nemerle. all the examples will be written in it. if you don't know it, don't worry: the syntax is pretty similar to that of c#, just much more comfortable in many ways.

there's one quite important thing before you start: the name of the file must be the same as the name of the class it contains; only the capitalization may be different. this is inconvenient and due to change in the future.

you can also take a look at the heavily commented plugin template and the so far very modest api.

once you are ready with your plugin, please let me know about it. if you have no place to host it, this very site might sound like a good solution. i'll be very happy to be able to host both the plugin and its documentation here.

how does it all work?
it's pretty simple. you are only forced to provide 1 variable and 2 methods:

Host:TerrHost { set; }
this one is needed to let the plugin communicate with the host (i.e. terraineer). it's set automatically, and ready for you to use everywhere in the plugin.

this is called by the host at startup. it needs to do two things:
1. store the nr variable that will be passed to the plugin (required for the "rerun plugin" functionality);
2. add the plugin to the host's menu (see the template for details).

guess what this does, hehe ;) yes, this is the real part of the plugin; you won a lollypop!
two host's methods will need to get called during the run of this method:
1. host.Start(nr) to let the host know the plugin's been run and prepare for it;
2. host.Update() to make the host apply the changes.
please, see the template and the api for details.

once you will have provided all these parts, there's time to write the actual plugin. the basic idea of how it all works goes as follows:
1. at terraineer startup, plugins are loaded;
2. plugin's Host variable is set;
3. plugin's Register(nr:int):void method is called, where:
   3a. plugin remembers its "serial number" (nr:int);
   3b. plugin adds itself to the terraineer's menu and decides what happens when the menu entry is activated.

the standard scheme of what happens in the plugin after the menu entry activation would be something like this:
1. a settings window is created to allow the user adjust the plugin's behaviour;
2. the Run():void method is run. it is quite important that this method does the actual work. otherwise, the "rerun plugin" option will not work with your plugin.

and that's it! you're ready with a 0.3 compliant plugin. all that is left, is to make it actually do anything :)
the template and api give further details on how to do it.

konqueror  valid xhtml  valid css  nemerle  opensource  gpl