Template plugIT¶

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

<?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>

3 - create the editor file
here "etemplate.pkg" as defined in the template.xml file in the EDITOR SCRIPT tag

// 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];
    );
  );;

4 - create the client file
here "ctemplate.pkg" as defined in the template.xml file in the CLIENT SCRIPT tag

/*! \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;;

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)