Script methods
Last modified by WikiBot on 2025/03/20 14:16
Script methods
Script methods are scripts associated with objects of specific types. All script methods associated with non-atomic objects of a certain type are stored as records in the file type.cms in the application folder. The structure of a record is
(method-name script-command ...)
Some attributes of atomic data object may also contain scripts.
The scripts may also be used in the description of forms and dialogs.
The following methods are called by the IDA Modeler (the list will be longer in the following versions of IDA):
- :assert
- Applicable to all non-atomic objects. The script is called as part of the assertion procedure, after validation of parameter values. Should check the consistency of the whole set of parameter values
- Base: the object to be checked
- Variables: _errorlevel – break on errors with level > this.
- :invoke
- For IDA systems, either builds the model of the next level (physical or mathematical), or tries to set well-posed problem;
- For reports, establishes the connections between report object and the sources of information
- Base: the object to be invoked
- Variables: none
- :after-invoke
- (?ICE only?) For IDA systems, called after the invoke procedure, if the application does not call :invoke script
- Base: the invoked object
- Variables: none
- :run
- For wizards, builds and simulates the model
- Base: the object to be simulated
- Variables: none
- :process-output
- Called after running a simulation, for every NMF or Modelica model.
- Base: the model
- Variable:
| _time | the end time of the simulation in utime format. |
- :compose
- For reports, collects the information and prepares the report (after simulation)
- Base: the parent of the report object
- Variable:
| target | the report object |
- :full-report
- Generates a text file with data for general report. Applicable to IDA systems only.
- Base: the IDA system
- Variables: none
- :to-full-report
- Prepares the data for the general report. Normally applicable to report objects only, but may be called for other objects from script method :full-report.
- Base: the data object
- Variables: none
- :insert-new
- Overrides the standard method of creating new data objects. Should create the required object and insert it in the contents of the parent object.
- If it returns NIL, the standard creating method is used.
- Base: the template for new data object
- Variables:
| _pane | the active pane |
| _parent | the host object for new created object |
| _opts | the list of options: (attr value …) |
- :new-document
- Overrides the standard method of creating new IDA documents. Should create and (unless in batch mode) show the required document.
- If returns NIL, the standard creating method is used.
- Base: the template for new data object
- Variables:
| _args | the list arguments:  |
- :new-resource
- Called when the user selects New resource from the shortcut menu of a resource parameter. Overrides the standard method of creating new IDA resources. Should return a new resource or NIL.
- Base: the data object containing the resource parameter
- Variables:
| _source | the resource currently pointed by the resource parameter; |
| _template | the template for resources of this type. |
- The standard method creates a copy of the _source, asking the user about the name, description and scope of the new resource. A possible alternative is (:show _template). This script shows the template for the new resource; the user can edit it and store it by clicking "Save as…". This alternative works only if the resource is edited in a modal dialog.
- :default
- For a resource parameter, returns the parameter with default settings for the given resource parameter. If it returns NIL, the standard procedure is used: [@ :system defaults name].
- Base: the resource parameter
- Variables: none
- :on-init
:on-init-template - Called when an object or a template of this type is created, before creating components.
- Base: the created object
- Variables: _mode – one of :derive, :copy or :implant. All initialization arguments are also passed as variables.
- :on-create
:on-create-template - Called after an object or a template of this type is completely created and inserted in the parent object.
- Base: the created object
- Variables: none.
- :on-remove
:on-remove-template - Called before an object or a template of this type is removed from the parent object.
- Base: the object to be removed
- Variables: none.
- :on-add
- For non-atomic data objects: executed when the user creates a new object of that type. If the creating method is overridden (method :insert-new), this method is not called by the IDA Modeler (but it may be called by :insert-new method);
- For graphical elements: executed (with pane’s object as the base and with parameters _pane _field and _form) when an element is added to a pane.
- :on-paste
- Called after a data object is pasted or dropped into a view, with that object as the base.
- When dropping, the method is called before changing the selection on the target pane.
- :on-change
- Called after a data object was modified in a modal dialog (after the changes are applied to the data object).
- :on-activate
- Called after an IDA system or IDA application becomes active (except after temporary deactivation).
- :on-deactivate
- Called before an IDA system or IDA application becomes non-active (except temporary).
- :on-connect
- Called after connection of two interfaces.
- Base: the macro object containing the interfaces.
- Variables: _from, _to – the interfaces; _line – the connection line.
- :on-start
- Called before starting a simulation, for every macro object and simulated math model.
- Base: the model.
- Variables: none.
- :on-enter
- Called when a non-modal window with the object is selected. Not called when switching views of the object.
- Base: the object
- Variables: _from – the previously active window, _to – the window being activated
- :on-leave
- Called when a non-modal window with the object is inactivated (either closed or moved to background). Not called when switching views of the object.
- Base: the object
- Variables: _from – the window being inactivated, _to – the window being activated (may be NIL).
- :refresh-on
- Called after a data object is added, removed, or (in some cases) edited. The script should update the views that are not updated automatically.
- Base: the changed object
- Variable: _action – one of :add, :edit, :remove.
- :custom-boundaries
- Called when preparing input for IDA Solver, for every equation object. Generates and returns extra bindings for unconnected variables to be inserted in the solver's input file.
- :custom-plot
- May be defined for variables in tables and plot files. It may also be defined as a diagram property.
- Applied to the variable in order to draw it in a custom diagram. The arguments are:
| _out | the output stream (e.g., window or printer etc); |
| _pane | the window containing the diagram (same as _out when drawing on the screen); |
| _field | the diagram element; |
| _prn | either the list of points (for variables in tables) or a reference to the table containing plot file data (for variables in plot files); |
| _t, _x, _y | gives time and space range as list (column (min max) (min_row max_row)). For variables in tables, the column is not used. The row numbers are given for time range only |
| _box | the diagram area, |
| _scale | scale parameter, |
| _attr | the list of attributes of the variable. |
Script properties and methods associated with specific views
These properties and methods are stored as
(:viewname (property_name code) ... )
Here is the list of supported methods
- :on-load
- Called after associating a document or an object with a view.
- Base: the object
- Variables:
| _pane | the view’s pane |
| _document | the document (normally, a form) associated with the view |
- :on-resize
- Called after the user has changed the form’s size.
- Base: the object
- Variable:
| _form | the form document associated with the view |
- :update-pane
- Called by IDA Modeler after changes in a data object that require rebuilding the view. May also be called from scripts (function update-pane) and from menu. Overrides the standard method.
- Base: the data object.
- Variable: _pane.
- When running the method, the selection is not shown.
- :pane-menu
- The property value gives the list of menu items in the pane menu
Script methods may also be called
- From other scripts, using script command :exec
- From the Options menu
- From the Log window, to show the source of a message
- To evaluate the contents of a collection, see :collections property
- As set-methods of parameters (base: the model containing the parameter, variables: _param – the parameter; _index – list of indices (for element of array), _value – the new value, _old – the old-value; _check – if non-nil the new value should be checked)
- To find an appropriate property page
- Method :on-click for buttons in forms (base – view’s object, variables: _pane – the view’s pane, _form – the view’s form document)
- Method :open for graphical elements
- Method :on-click for toolbar buttons (base – IDA application)
- Writer scripts for fields (base – the field’s value, variables: _field –the field (element or the form), _pane – the window containing the field)
- Writer scripts for dialog items in dialog (base – the field’s object, variable: _val –the value)
- Acceptor scripts for editable fields (base – the field’s object, variables: value and _value – the new value, _old – the old value, _widget – the dialog item, _field –the field (element or the form), _pane – the window containing the field)
- Method :on-popup for script dialogs; methods :on-click and :on-change for dialog items in script dialogs
- In script-controlled menus: writer (base – the application, variables: _menu, _item, _value) and acceptor (base – the application, variables: _menu, _item, _reg: the registry key used to store the option)
- In the Tools menu: reader and evaluator