Scilab Function
Last update : 10/09/2007

scipad - Embedded Scilab text editor

### Calling Sequence

  `scipad()`
  `scipad(f1[,f2,...])`
  `scipad f1 f2 ...`

### Parameters

- `f1, f2...`: (strings or vectors of strings) file or directory pathnames

### Description

Scipad is an embedded Scilab text editor written in Tcl/Tk. It can be started with a fresh text buffer pressing the "Editor" button on top of the main Scilab window, or from Scilab command line with the instruction `scipad()`, or it can open specific files if invoked with any of the calling sequences above.

The same invocation adds further files to an already opened Scipad. If any of the arguments is a directory pathname, a file chooser starting in that directory pops up, allowing (multiple) selection of files.

Scipad allows Windows like edition modes. Keyboard shortcuts are defined for most possible editing actions and reported by the menu entries.

Additionally, the following shortcuts are defined:

<F2> | Save file
<F5> | Save file and run it into Scilab
<F6> | Show previous buffer
<F7> | Show next buffer
<Control-F6> | Switch to previous visible buffer
<Control-F7> | Switch to next visible buffer
<double-click mouse-button1> | Select word
<triple-click mouse-button1> | Select line
<Shift-Control-mouse-button1> | Select a block
<mouse-button2> | Paste selection
<mouse-button3> | Popup edit menu, or debug menu if clicked during a debug session
<Shift-mouse-button3> | Popup Execute menu
<Control-mouse-button3> | Popup Options menu
<Shift-Control-mouse-button3> | Open the source of the library function under the pointer
<Control-plus> | Increase the font size
<Control-minus> | Decrease the font size
<double-button1> on a tile title | Maximize this tile
<double-button1> on a sash | Space sashes evenly (for this paned window)
<button2> on a tile title | Switch hidden files

The "Load Into Scilab" (Ctrl-lowercase-l) menu entry can be used to `exec` the file content into Scilab, while "Execute selection" (Ctrl-lowercase-y) passes the selected lines to the scilab shell using `ScilabEval` (i.e. `execstr`).

### Debugger

Scipad includes a debugger targeted to Scilab scripts and macros. The user can:

  - Set/remove breakpoints anywhere in the opened files.The breakpointed lines get pink background. No breakpoint can be set on empty, blank or commented lines.

  - Configure execution.The user has to provide the function name to execute, its variable names, and variable values. To ease this step, a scan of the currently displayed buffer is implemented to look for functions defined in it, scan their names and variable names. All this is displayed to the user in a dialog for easy selection. First, the user has to select a function in a spinbox, then eventually one of its variables. Once a variable is selected, the user can set/change its value (another dialog pops). Variable values and names are displayed in listboxes. The user can also add a new variable or remove already defined variables. This is in case the user changes the input variables of his function in the file, and he does not want to scan the buffer again (which causes all the variable values to be reset to a null value). Note also that the `varargin` keyword is fully supported, and that variables that are not given a value by the user are ignored when Scipad launches the function for debug. If the current file contains main level code (i.e. executable code outside of a function definition), Scipad proposes to debug this file as a .sce file (see below).

  - Go to next breakpoint.Scilab executes the code, and stops at the next breakpoint or goes to the end of the file if there is no more breakpoints. The active breakpoint is highlighted in Scipad so that it can easily be identified.

  - Insert a new breakpoint or remove an existing breakpoint during the debug.The breakpointed lines get pink background, and lines where breakpoints are removed restore their normal background. The new breakpoint configuration is taken into account for the next steps of execution or debug.

  - Execute step by step, going into functions (step into).Scilab stops before execution of each line. The active stop position is highlighted in Scipad so that it can easily be identified. Every line of code in functions from opened files is taken into account, but Scipad does not search for or open files by itself in order to step into them. Lines with no executable code (blank or commented lines) are skipped.

  - Execute step by step, without going into ancillary functions (step over).Similar to step into, but ancillaries are executed at once without stepping into them. However, if the user has set a breakpoint in an ancillary, Scilab will nevertheless stop at this breakpoint.

  - Execute step by step, starting back from the return point of the current function (step out).Scilab executes instructions until the function returns from the current context, i.e. the next stop occurs just after the current function has returned. However, if the user has set a breakpoint in the current function or in an ancillary, Scilab will nevertheless stop at this breakpoint. Lines with no executable code (blank or commented lines) are skipped.

  - Run execution up to the cursor position.Scilab executes instructions until the cursor position is reached. If the user has set breakpoints in the current function or in an ancillary, Scilab will skip them and stop only when the cursor position is reached. Lines with no executable code (blank or commented lines) are also skipped: if the cursor is in such a line, Scilab will stop just before executing the next line carrying executable code.

  - Continue ignoring any breakpoint.Finish execution in Scilab as if there was no breakpoint at all.

  - Abort debug.Abort execution in Scilab and cancel the current debug session in Scipad.

  - Remove all breakpoints.This allows to quickly remove all the breakpoints from both Scilab and Scipad.

When one of the commands above is triggered for the first time, Scipad launches execution, i.e. it execs the currently displayed buffer as well as all the opened buffers that contain functions, sends to Scilab the `setbpt` instructions relative to all the breakpoints that have been set, and executes the selected function with the input variable values provided during the configure execution step. Then the execution is automagically stopped by Scilab according to the debug command that was launched. A new debug command can then be executed.

At any time during the debug, a watch window can be displayed on user request. It allows to monitor any variable value, or change a variable value during a breakpoint stop and relaunch execution with the modified value. A watchable variable can be part of a larger structure, for instance if A is a 20x20 matrix, the shorter sub-matrix A(2:4,7:9) can be watched. The watch window also displays the calling stack and contains a toolbar with the most useful commands from the debug menu.

In its current development state the debugger works well with functions, i.e. pure .sci files. Support of .sce files or mixed .sce/.sci files is implemented but should be considered as a beta functionality. Debug of .sce or mixed .sce/sci files makes use of the implementation for the .sci case after having wrapped the code in a function/endfunction clause.

### Remarks

  - Localisation:

    Scipad menues and messages can be translated to several languages. By default they appear in English, but other languages are being added. The localization in effect can be selected with the menu Options/Locale, and is remembered across sessions. Currently, the supported languages are: "da" (Danish), "de" (German) ,"eng" (English), "es" (Spanish), "fr" (French), "it" (Italian), "no" (Norwegian), "pl" (Polish), "se" (Swedish), "zh_tw" (Chinese-Taiwan).Further languages can be added by creating the proper translation file and putting it in `SCI/modules/scipad/tcl/msg_files/`. If you plan to do such a job, please check the file `SCI/modules/scipad/tcl/msg_files/AddingTranslations.txt` for detailed instructions, and consider to contribute it to the community.

  - Drag and drop:

    DnD has been implemented in Scipad for moving around text, for dropping selected text from and to external applications, and for opening a file or a list of files.

    Dragging one or more files from an explorer and dropping to Scipad will open the file(s) in Scipad. Doing the same with a directory will open recursively all the directory contents (beware!)

    For text selected within the Scipad window, the possible actions are move (just use mouse button-1) and copy (Control button-1). Text selections can be moved or copied also between different Scipad subpanes, when tiling is active.

    Drag and drop capabilities in Scipad rely on the TkDnD package (http://sourceforge.net/projects/tkdnd). Presence of this package should be automatically detected by Scipad, enabling the corresponding features at that time. Windows and linux-i386 binary versions of Scilab are currently shipped with TkDnD. If not, here are some installation instructions:

    Windows platforms: Download the full package (currently tkdnd-1.0a2.tar.gz), and uncompress it somewhere. Copy the content of lib\tkdnd and paste it into `SCI\modules\tclsci\tcl\tk8.4\tkdnd`. That's all!

    linux-i386 platforms: Download the rpm package (currently tkdnd-1.0-b2.i386.rpm). Install it with rpm -U (may have to force --nodeps if it doesn't recognize an existing Tcl installation). If you have a source version of Scilab and an installation of Tcl/Tk, check where they are installed (e.g. `/usr/share/`) and move the newly created directory `/usr/lib/tkdnd1.0/` to there. If you have a binary version of Scilab, move `tkdnd1.0/` to `SCI/modules/tclsci/tcl/`, where the supplied Tcl/Tk binaries are.

  - Known Issues:

    The commands passed are output on the Scilab window, but are not recorded in the history.

  - Bugs:

    There are still a few... Details can be found in file `SCI/modules/scipad/BUGS`. Officially reported bugs are filed in the Bugzilla http://scilabsoft.inria.fr/cgi-bin/bugzilla_bug_II/index.cgi and can be easily retrieved by filtering entries wrt the "Scipad Editor" element.

  - Additional features in Scipad and most recent developments:

    Currently Scilab is shipped with Tcl/Tk 8.4. However, Scipad offers a handful of quite handy features that are available as soon as Tcl/Tk 8.5 is running in its background. For instance, peer text widgets are available from Tk 8.5, and this capability is used in Scipad to allow for displaying more than one contiguous area of an opened file at a time in tile mode. Instructions about how to upgrade to Tcl/Tk 8.5 can be found on the Scilab wiki: http://wiki.scilab.org/Linking_Scilab_with_Tcl/Tk_8.5 .

### Examples

       scipad SCI/etc/scilab.start

### See Also

`edit`, `manedit`, `edit_error`,

### Authors

  Scipad is derived from `tknotepad` written by Joseph Acosta;
  Mathieu Philippe, INRIA, 2001;
  Enrico Segre, Weizmann Institute, 2003-2006;
  Francois Vogel, 2004-2007.