|
Information
Installation
Documentation
|
EJS has some predefined methods for typical actions that you can use anywhere in your code, either in model pages or in view element property actions.
Methods can be classified in model methods, view methods and tools methods.
All predefined model methods start with an underscore character '_', to help them distinguish with your own custom methods. View and tools methods are accessed using the object oriented syntax _view.method() and _tools.method().
Here is the list of EJS predefined methods (grouped by functionality and in alphabetical order):
|
Model methods to control the execution of the simulation
| |
int _getDelay()
Returns the current delay time in milliseconds.
| |
org.opensourcephysics.numerics.EJSODE _getODE ( String _odeName)
Returns the EJSODE object for the given ODE page.
| |
void _initialize()
Executes the Initialization workpanel code without resetting model variables to their default value. This method is often used to re-initialize a simulation with user interface values because it does not reset global variables to the values in the table of variables.
| |
boolean _isApplet()
Determines if the simulation is running in an applet (web browser) environment.
| |
boolean _isPaused()
Determines whether the evolution of the simulation is not playing. It is the opposite of the _isPlaying() method.
| |
boolean _isPlaying()
Determines if the evolution is playing. This method is often used to enable or disable elements of the view.
| |
void _pause()
Pauses the evolution at the end of the current evolution step.
| |
void _play()
Starts (plays) the evolution. The evolution proceeds at a rate determined by the frames per second (FPS) property and the step per display (SPD) property. If FPS is 10 and SPD is 5 the program will execute the evolution algorithm 50 times per second and will collect data at the end of every step but will only redraw the screen 10 times per second.
| |
void _reset()
Resets the simulation to its initial state. This method clears all data, sets global variables to the initial value in the table of variables, and sets all user interface elements to their default values.
| |
void _setDelay(int msec)
Sets the delay time in milliseconds between model's evolution steps. The delay time is the reciprocal of the frames per second (FPS) property.
| |
void _setFPS(int fps)
Sets the number of frames per second (FPS) of the simulation to the given value. The default FPS parameter is displayed on the Evolution workpanel.
| |
void _step()
Performs SPD evolution steps and refreshes the display (see the _view.setSPD() method). Fixed relations are evaluated after every evaluation of the evolution so that multiple data points are generated and collected if SPD is greater than one. If the simulation is running, the evolution pauses at the end of the current step.
| |
void _setPageEnabled(String pageName, boolean enabled)
Enable/disable a page in run-time. The page is referred to using the header title as it appears in EJS. If two pages share the same title, they are enabled/disabled together. The method only has effect on pages of the Initialization, Evolution, and Fixed Relations sections of EJS, and also on ODE Event pages. Other disabled pages are not processed by EJS when generating the simulation. (Only since EJS 4.2.)
|
|
Model Input/Output methods to save and read data
| |
String[] _getArguments()
Returns the in command-line arguments when the simulation is run from a shell window.
| |
boolean _readState(String filename)
Reads the previously saved model state. This method reads the value of all the variables of the model from the file. If the filename ends with the suffix ".xml", the data is assumed to be a text file in XML form. Otherwise, the data file is considered to be binary and then caution is needed in the sense that the data file must have been created with the _saveState() method from the same simulation with exactly the same variables and declared in the same order.
If successful, the method returns a true boolean and false otherwise.
If the name of this file begins with the keyword ``URL", the method will read the rest of the name as an Internet address and will try to connect to this address. If successful, it will play the simulation from the data on the web server in question. If the rest of the name begins with "http:", then the Internet will be used as the source of the data file.
| |
String _readText(String filename)
Reads text from a given file. Returns null if there is any I/O error.
| |
boolean _readVariables(String filename, String variablesList)
Reads a list of variables from a file. The list of variables is a String with the variable names separated by commas, spaces, or semicolons.
| |
boolean _readVariables(String filename, java.util.List<String> variablesList)
Similar to the previous one, but now the list of variables is given as a java.util.List of Strings.
| |
boolean _saveImage(String filename, String elementName)
Saves an image of the given view element to file.
| |
boolean _saveState(String filename)
Saves the model state. This method saves the current values of global variables defined in the Variables tables in the specified file. It returns a true boolean if successful. This methods returns false if it encounters an IO error, such as a write protected output location. The file name specifies the relative or absolute path where the file will be created.
If the file name has a ".xml" suffix, a text file in XML form will be created. In all other cases, the file will be created in binary form. Binary files can be considerably smaller than XML files, but the _readState() method will then read the variables blindly in the order in which they appear in the model. Hence, if you modify the number of variables or their order of declaration in a model, previously saved data may be read incorrectly.
If the file name begins with the prefix "ejs:", then the data is stored only in memory. A model can read this data as if it were a disk file (using the method _readState() during the current session, but that data will be lost at the end of the session. Temporary storage is useful for storing various intermediate stages during the same session. In particular,
this is of interest when the application runs as an applet, since (for security reasons) an (unsigned) applet can not write to the hard disk.
| |
boolean _saveText(String filename, String text)
Saves text to file.
| |
boolean _saveVariables(String filename,String variablesList)
Saves only the prescribed list of variables to a file. If the filename ends with ".xml" the file is a text file in XML form. Otherwise, the file is binary and must be read with the _readVariables() method with the same list of variables. The list of variables is a String with the variable names separated by commas, spaces, or semicolons.
| |
boolean _saveVariables(String filename, java.util.List<String> variablesList)
Similar to the previous one, but now the list of variables is given as a java.util.List of Strings.
|
|
Model methods to control EJS applets using Java Script
| |
String _getParameter(String parameterName)
Returns the applet's parameter with this name. Null if the parameter is not specified in the applet.
| |
boolean _setVariables(String command, String sep, String arraySep)
Sets the value of one or more variables of the model. The command string must consist of pairs of the type 'variable=value' separated by the separator string sep. The arraySep string is used as separator string for values of array variables. The method returns true if all the variables are correctly set.
| |
boolean _setVariables(String command)
Equivalent to _setVariables (command, ";", ",").
| |
_getVariable(String variableName)
Returns a String with the value of a public variable of the model. If the variable is an array, individual element values are separated by commas. Only public variables of primitive or String type can be accessed by this method.
|
EJS-created applets have also public fields called _model, _simulation, and _view, which provide access to all other predefined and custom methods. A method you may need to use frequently in applet mode is the _simulation.update() method. This method is called automatically whenever the user clicks on a button in the view. However, clicking on JavaScript controls do not update the simulation and requires you to invoke this method explicitly.
|
Tool methods
| |
void _tools.clearDataTool()
Clears all data from the data tool.
| |
void _tools.clearFourierTool()
Clears all data from the Fourier analysis tool.
| |
Object _tools.showDataTool(Data... _view.dataElement)
Same as _tools.showDataTool(null, Data... _view.dataElement).
| |
Object _tools.showDataTool(Component _view.parentComponent, Data... _view.dataElement)
Similar to the next one, but here all data is considered to belong to a same series and appears in a single tool tab with the first column considered to be equal.
| |
Object _tools.showDataTool(Component _view.parentComponent, java.util.List<Data> _view.dataElement)
Displays data of one or several elements. Each data in the list is considered to be independent and appears in a separate tool tab. If this method is used repeatedly with the same data, the data in the data tool is updated. The data tool appears relative to the given view element or centered if null. Returns the data tool.
| |
Object _tools.showFourierTool(Data... _view.dataElement)
Similar to the matching showDataTool method but using the Fourier analysis tool.
| |
Object _tools.showFourierTool(Component _view.parentComponent, Data... _view.dataElement)
Similar to the matching showDataTool method but using the Fourier analysis tool.
| |
Object _tools.showFourierTool(Component _view.parentComponent, java.util.List<Data> _view.dataElement)
Similar to the matching showDataTool method but using the Fourier analysis tool.
| |
Object _tools.showTable(Data... _view.dataElement)
Same as _tools.showTable(null, Data... _view.dataElement).
| |
Object _tools.showTable(Component _view.parentComponent, Data... _view.dataElement)
Creates a table with the data of one or several elements. The table appears relative to the given view element or centered if null. Returns the ArrayFrame object which contains the table.
|
|
View methods
| |
void _view.clearData()
Clears data from the elements that store them (such as trails, traces, or tables).
| |
void _view.clearElements()
Clears data from the view. The effect of this method depends on the type of element. Unlike the _view.resetElements() method, this method should not affect formatting. See also _view.clearData().
| |
Element _view.getElement(String elementName)
Returns the EJS element with the given name. This element is a wrapper object for the underlying Java object, which can be obtained using the construction _view.elementName. The wrapper object is seldom used, but can be used by advanced users to change the element properties in run-time.
| |
java.awt.Container _view.getTopLevelAncestor(String elementName)
Returns the top-level ancestor of the given view element (either the containing Window or Applet), or null if the element has not been added to any container. If no element name is provided, the first view element whose component is a Window is returned.
| |
void _view.resetElements()
Resets view elements to their original state. The effect depends on each type of view element. For example, this method removes stored data from trace and trail elements and removes formatting and other programmatic customization. See also _view.resetTraces().
| |
void _view.resetTraces()
Same as _view.clearData().
| |
void _view.setSPD(int steps)
Sets the number of steps per display. This number indicates how many evolution steps are computed before updating the view. View elements which collect data will accumulate the data, but the view will not be refreshed. Setting a high number of steps per display can speed up the simulation considerably because unnecessary screen redrawing is avoided. The default is displayed in the Evolution workpanel.
| |
void _view.setUpdateView(boolean update)
Indicates whether to update the view every time after an evolution step. Default is true, but disabling the updating of the view (i.e. invoking this method with a false parameter) can be useful to have the model run as fast as possible, not losing any CPU effort in refreshing the view. When the computation is done, the program can use this method again with a true parameter.
| |
void _view.update()
Updates all view elements with the current values of the model's global variables.
|
|
View methods to display documents
| |
JDialog _view.createDescriptionDialog(Component owner, String pageName)
Returns a javax.swing.JDialog displaying the named description page and the specified window as owner. The owner window may be null.
| |
JDialog _view.createDialog(Component owner, Component child)
Returns a javax.swing.JDialog with the given owner and child component.
| |
JDialog _view.createHTMLDialog(Component owner, String pageURL)
Returns a javax.swing.JDialog displaying the given HTML page and the specified window as owner. The owner window may be null.
| |
JDialog _view.createHTMLDialog(Component owner, java.net.URL aURL)
Returns a javax.swing.JDialog displaying the given HTML page and the specified window as owner. The owner window may be null.
| |
JScrollPane _view.createHTMLPage(String pageURL)
Returns a javax.swing.JScrollPane displaying the given HTML page.
| |
JScrollPane _view.createHTMLPage(java.net.URL url)
Returns a javax.swing.JScrollPane displaying the given HTML page.
| |
java.net.URL _view.getDescriptionPageURL (String pageName)
Returns the URL of the HTML page corresponding to the description page with the given name. This URL locates the description file inside the JAR file of the simulation and can be used programmatically to display a single page of the description.
| |
void _view.showDescription(boolean show)
Shows/hides the description dialog that is distributed in the simulation's jar file.
| |
void _view.showDescriptionAtStartUp(boolean show)
Indicates whether the description of the simulation must be displayed at start-up. Default is true, but users can disable it in order to display programmatically the description, or individual pages of it.
| |
_view.showDocument(String document)
Opens the given document using the native application, if a document reader is defined.
|
|
View methods to display messages
| |
void _view.alert(String elementName,String title, String message)
Displays a message in an alert dialog window with the given title and message. The simulation pauses until the dialog is closed. This method is useful for displaying error messages or warnings that the user should not ignore. The dialog is centered on the given view element or centered on the screen (or on the last parent component specified by the setParentComponent method) if a null element name is given.
| |
void _view.clearMessages()
Clears all text from the last created text area of the view (if any). See _view.println().
| |
String _view.format(double value, String template)
Converts a double value to a string with the given template. Example: _format(Math.PI, "0.00") prints the number PI with two decimal digits.
| |
void _view.print(String message)
Prints the given message in the last created text area of the view. If the view has no text area elements, the message will appear in the standard output.
| |
void _view.println(String message)
Prints the message followed by a new line character.
| |
void _view.println()
Prints an empty new line.
| |
void _view.setParentComponent(String elementName)
Sets the parent element for displaying dialog windows, such as alerts.
|
|
