Scol

h1. Template plugIT

h2. Start a new plugIT (template)

1 - choose his category (for example "misc")

create a new "template" directory in the category path : "Partition_LockedApp\tools\os3dplugins\misc"

2 - create the plugIT definition file (xml)

the xml file MUST have the same name as the plugIT directory here "template.xml"

the PLUGIN tag :

- name : the plugIT name displayed in the OS3D plugIT menu

- version : the plugIT version

- type : the category name

the DESCRIPTION tag : 

the plugIT description shown in the plugIT editor

the HELP tag :

the text shown as a tooltip on the help button in the plugIT editor, or an internet url pointing to the plugIT documentation

the RESOURCE tag :

it contain FILE tags with a "path" param, for additional files needed by the plugIT

the EDITOR tag :

it contain the scol scripts to load to execute the plugIT editor and the editor params and types to save

> the SCRIPT tag :

> > the "path" param contain the editor file, it can be relative to the plugIT directory with "./"

> the PARAM tag :

> > the "name" param contain the name of the editor variable to save

> > the "type" param contain the type of the param, it can be :

> > * "value"

> > * "file"

> > * "mesh"

> > * "material"

> > * "node"

> > * "light"

> > * "anim"

> > *  ...

the CLIENT tag :

it contain the client side scol scripts and the default actions/events

> the SCRIPT tag :

> > the "path" param contain the editor file, it can be relative to the plugIT directory with "./"

> the EVENT tag :

> > it define an event name in the "name" param

> the ACTION tag :

> it define an action name in the "name" param

<pre>

<?xml version="1.0" encoding="UTF-8" standalone="no"?>

<PLUGIN name="template" version="1.0" type="misc">

  <DESCRIPTION>Template plugIT</DESCRIPTION>

  <HELP>Template plugIT help</HELP>

  <RESOURCE>

    <FILE path="./myres.jpg" />

  </RESOURCE>

  <EDITOR>

    <SCRIPT path="./etemplate.pkg" />

    <PARAM name="oninit" type="value" />

  </EDITOR>

  <CLIENT minstance="true">

    <SCRIPT path="./ctemplate.pkg" />

    <ACTION name="Go" />

    <EVENT name="Done" />

  </CLIENT>

</PLUGIN>

</pre>

3 - create the editor file

here "etemplate.pkg" as defined in the template.xml file in the EDITOR SCRIPT tag

<pre>

// prototype of the cbCloseEdit function in case you don't use params

//proto cbCloseEdit = fun [] [[S S] r1];;

/*! \brief Callback on plugIT instance editor closed

  *

  *  called on Apply / Ok button, this callback return the parameters to save in the XOS project

  *

  *  <b>Prototype:</b> fun [] [[S S] r1]

  *   

  *  \return [[S S] r1] : parameters to save in the instance XML data

  **/

fun cbCloseEdit(ctrlinit)=

  // get the check state and add it to the param list

  let itoa getEdCtrlCheckState ctrlinit -> state in

    ["oninit" state]::

    nil;;

/*! \brief Callback on plugIT instance editor destroyed

  *

  *  called when the editor window is destroyed, this is useful to destroy added objects or resources

  *

  *  <b>Prototype:</b> fun [] I

  *   

  *  \return I : 0

  **/

fun cbDestroyEdit()=

  0;;

/*! \brief Callback on plugIT instance editor opened

  *

  *  called when a user the plugIT Editor

  *

  *  <b>Prototype:</b> fun [EdWindow PInstance V3Dview] I

  *

  *  \param EdWindow : editor window structure

  *  \param PInstance : plugIT instance

  *  \param V3Dview : default 3D view structure

  *  

  *  \return @fun [] [[S S] r1] : Callback to call on close

  **/

fun dynamicedit(winstr, inst, viewstr) =

  // size of the window

  let [400 90] -> [iw ih] in

  (

    // resize the editor window

    setEdWindowSize winstr iw ih;

    // retrieve the current param value

    let atoi (getPluginInstanceParam inst "oninit") -> state in

    // create the check box control on the editor window

    let crEdCtrlCheck winstr 10 10 280 20 "Run on init" EDWIN_RESIZE_MW -> ctrlinit in

    (

      // set the current check state

      setEdCtrlCheckState ctrlinit state;

      [(mkfun1 @cbCloseEdit ctrlinit) @cbDestroyEdit];

    );

  );;

</pre>

4 - create the client file

here "ctemplate.pkg" as defined in the template.xml file in the CLIENT SCRIPT tag

<pre>

/*! \brief Callback on instance destruction

  * Callback called when a plugIT instance is destroyed

  *

  *  <b>Prototype:</b> fun [PInstance u0] I

  *

  *  \param PInstance : destroyed plugIT instance

  *  \param u0 : user parameter, the type is not defined here because it is not used in this template

  *   

  *  \return I : 0

  **/

fun deleteOb(inst, uparam)=

  0;;

// plugIT doing something

fun doSomething(value)=

  // test the value to define a default one

  let if value == nil then "none" else value -> value in

  (

    // create a dialog box with the value as text

      _DLGMessageBox _channel DMSwin "Template Plugit !!" value 0;

    // send the Done event

    _DMSevent this (getPluginInstanceEvent inst "Done") nil nil;

  );

  0;;

/*! \brief Callback on "Go" dms action

  *

  *  Call the program function to display a dialog box

  *

  *  <b>Prototype:</b> fun [PInstance DMI S S I u0] I

  *

  *  \param PInstance : plugIT instance

  *  \param DMI : DMS module who call the action (not used)

  *  \param S : name of the launched action

  *  \param S : data posted in DMS action link

  *  \param I : reply flag (not used)

  *  \param u0 : user parameter, the type is not defined here because it is not used in this template

  * 

  *  \return I : 0

  **/

fun cbGo(inst, from, action, param, rep, uparam)=

  // call the dialog box and set the link parameter as text

  doSomething param;

  0;;

/*! \brief Callback on new plugIT instance

  *

  *  Read the parameters from editor values and initialise the plugIT

  *

  *  <b>Prototype:</b> fun [PInstance] I

  *

  *  \param PInstance : plugIT instance

  *   

  *  \return I : 0

  **/

fun newOb(inst)=

  // retrieve the oninit param value

  let atoi (getPluginInstanceParam inst "oninit") -> state in

  (

    // define the function to call when we receive the Go action

    PluginRegisterAction inst "Go" mkfun6 @cbGo nil;

    // test the oninit param to know if we have to start the plugIT functionalities here

    if !state then nil else

      doSomething nil;

    // define the function to call when the plugIT instance is destroyed

    setPluginInstanceCbDel inst mkfun2 @deleteOb nil;

  );

  0;;

/*! \brief Global plugIT function to initialize the plugIT callbacks

  *

  * called on plugIT load, here define the functions to use for a new instance and the editor

  *

  *  <b>Prototype:</b> fun [s] I

  *

  *  \param S : plugIT file path

  *  

  *  \return I : 0

  **/

fun IniPlug(file)=

  PlugRegister @newOb nil;

  setPluginEditor @dynamicedit;

  0;;

</pre>

Now reload the plugITs in the OS3D Editor (hit F5 after a focus in the plugITs window, or right click > "reload")

If the plugIT don't appear in the plugITs menu :

- look at the error in the OS3D Editor log window (at the bottom of the main interface)