4.2. Script-Editor

The script editor is one of the main windows of itom and allows creating, modifying and executing one or several python scripts.

../_images/scripteditor.png

Every script editor window can display one or multiple script files that are separated in different tabs at the bottom of the window. Click a tab to show the corresponding script in the center of the window. You can close, save, reorder or (un-)dock every single tab by its context menu.

../_images/scripteditor-tab-context.png

The content of the current script file is displayed in the center of the script editor window. Use this text editor to write or modify a script that can then be run or debugged. The menus of the script editor window provide many possibilities to edit and finally run or debug the script. The most important functions are also accessible via the toolbar and / or the context menu of the script area.

4.2.1. Basic functions

The file menu gives the opportunity to open an existing script or create a new one, to save the current script or to print or close the script.

Basic and advanced functions to edit the current script are contained in the edit menu. These are:

  • cut, copy and paste parts of the script.

  • comment (Ctrl+R) the selected lines using the #-character or uncomment lines (Ctrl+Shift+R).

  • indent or unindent the selected lines.

  • open a search bar at the bottom of the script to search for a string (quick search) (Ctrl+F).

  • open a search and replace dialog (Ctrl+H).

  • open a goto-dialog (Ctrl+G) where you can enter a specific line number the cursor should be moved to.

  • open the icon browser to search internal icons of itom and loaded plugins that can also be used for specific user interfaces.

  • You can set bookmarks by clicking the left margin (left from the line numbers). A star icon indicates a bookmarked line. Modify the bookmarks or jump to the next by clicking the corresponding menu entries.

4.2.2. Run or debug the script

In order to run or debug the script, use the functions given in the script menu.

../_images/editor_run_debug.png

These are:

  • Run Script (F5): Click this to run the current script. This is the default way to execute a script.

  • Run Selection: If you mark a specific part of the script and choose run selection, this selection is copied into the command line and executed. Please notice, that the number of leading spaces of the first selected line is also removed from the following lines.

  • Debug (F6): Click this to debug the current script such that you can jump from line to line or breakpoint and see the state of the script and all global or local variables. The line where the debugger is currently stopped is marked with a yellow arrow. Then, the debugger waits for your input how to proceed. The options are…

  • Continue (F6): Continue the script execution until the next valid breakpoint or the end of the script.

  • Step (F11): The script executes the following line or jumps into the first line of the function that should be executed in the currently marked line.

  • Step Over (F10): Almost the same than step besides that the debugger always executes the script until the next line in the current function or the main script. Further function calls are entirely executed.

  • Step Out (Shift+F11): Executes the script until the end of the current function and stops in the next line of the caller.

  • Stop (Shift+F10 or Ctrl+C): Stops a currently running script (run or debug mode). Please notice, that the script can not always be stopped immediately. For instance, the stop flag is not checked when a sleep command from python’s time module is executed.

The functions continue, step, step over, step out and stop are only enabled if a script is currently debugged or run (stop only). These functions are also accessible via the script menu of the itom main window.

More information about breakpoints are given in the next section.

4.2.3. Breakpoints

Breakpoints are red or gray points in the right side of the margin of a script window. In every valid script line, there can be at most one breakpoint. A breakpoint is added to a specific line by clicking the margin at the right side of the line numbers. You cannot add a breakpoint to a commented or empty line. If you clear or comment a line that already contains a breakpoint, the script debugger will fail with a corresponding error message.

../_images/editor-breakpoints.png

There are three different types of breakpoints:

  • Red point: This is an enabled, standard breakpoint. Once the script is debugged, it will always stop at this breakpoint.

  • Gray point: Disabled breakpoint. This breakpoint is currently inactive. You can enable or disable a breakpoint by clicking it or via its context menu.

  • Red point with white cross: Special breakpoint. Right click on a breakpoint and choose edit breakpoint to set further settings to the breakpoints behaviour.

../_images/editor-edit-breakpoints.png

The edit breakpoint dialog allows configuring the following properties of a breakpoint:

  • Condition: Indicate a python statement that is evaluated once the debugger comes to the corresponding line. It will only stop at this line of the condition returns true. You can use any global or active local variables inside of the condition.

  • Ignore Count: If this number is bigger than zero, the debugger ignores this breakpoint for the first n times, where n is the value of ignore count.

  • Temporary Breakpoint: The debugger only stops at this breakpoint once and ignores it after having stopped there for the first time.

  • Enabled: En/Disables the breakpoint.

The breakpoints of this and other scripts are all listed in the breakpoint toolbox of itom. If itom is closed, all current active and inactive breakpoints are saved and restored once itom is started again. Breakpoints are also active if the corresponding script is currently not visible in any script editor window.

Note

In order to stop the script execution in a debug-mode in any method that is for instance called by clicking a button in an user-defined interface or via a timer event, you need to set a breakpoint in the corresponding line in the script and toggle the button vardebugpython Run Python in debug mode in the main window of itom (toolbar or menu script). The same holds for a method that you call from the command line. Toggle this button and set a breakpoint in the method in order to run this method in debug-mode and let the debugger stop in the line marked with the breakpoint.

4.2.4. Bookmarks

It is possible to mark certain lines in a or multiple scripts with bookmarks, displayed as star icon in the most-left column (left to the column numbers). The list of all bookmarks is then visible in the bookmarks toolbox of itom. To add a bookmark to a line, which is not decorated with a bookmark yet, either click in the most-left column in the desired line or click at any character in the desired line to move the cursor there and click the toggle bookmark button in the toolbar.

To remove a bookmark, click on an existing bookmark icon in the editor again or click the toggle bookmark button again, if the cursor is currently in the line of a bookmark. It is additionally possible to clear all existing bookmarks.

Using the previous bookmark and next bookmark buttons (in the toolbar of the editor, in the context menu of the most-left column or via the bookmark toolbox) it is possible to jump to the previous or next bookmark in the global list of bookmarks.

Bookmarks are persisted at shutdown of itom and reloaded at the next startup. Bookmarks, that belong to non-existing Python scripts will not be persisted or reloaded.

4.2.6. Syntax highlighting and indentation

A script highlighting mechanism is implemented to simplify the reading and programming of the script. You can change the styles of the syntax highlighting in the property dialog (tab styles) of itom.

Another big feature is the additional help for working with indentations using spaces or tabs. The python language is structured using indentation. Each indentation level always needs to consist of the same amount of spaces or tabs; additionally you must not switch between tabs and spaces for the indentation within your scripts. The script editor has a feature to automatically replace tabs by a certain amount of spaces (it is recommended to set this feature and use four spaces for one tab). Additionally, you can display spaces or tabs and be warned if you switch between both. All these features are configurable in the tab general of the property dialog.

If you press the return key after the begin of a new indented block (usually indicated by a colon character), the next line is automatically indented.

4.2.7. Auto completion and calltips

Auto completion and calltips provide two mechanisms for an easier and faster scripting.

../_images/scripteditor_autocompletion.png

Once you typed a certain number of characters of a new statement, a check for possible auto completions is started in the background. Once the results are available, they are displayed as list. Select the right item from the list using the arrow keys and press Tab or Return to select the word. Quit the auto completion list with Esc.

The auto completion can be configured by the tab auto completion of the property dialog.

Calltips always appear if you open a rounded bracket to give the arguments of a function call.

../_images/scripteditor_calltip.png

If the statement before the bracket corresponds to a detectable method, the list of arguments of this method is shown as a tooltip, such that all arguments are clearly visible during coding. Configure the calltip behaviour in the tab calltips of the property dialog.

The introspection for auto completions and calltips uses an offline parsing of the current script as well as all imported packages. This might take some time, when a new package is imported and analzyed for the first time (e.g. for numpy).

Note

Auto completion and calltips require the Python package jedi to be installed. jedi itself depends on the package parso. Please install both packages to benefit from all features of the script editor (new in **itom* 3.2).

4.2.8. Goto definition or assignment

The script editor allows navigating to the definitions (or assignments) of function calls, used variables etc. in a script. You can either call the context menu over the word, to whose definition you would like to go to, or you press the shift-key and move the cursor over a specific word. If a definition (or assignment) can be found for this word, it is underlined after a short moment. Click the click to jump to the definition. A jump can be done within the same script, else the requested script is opened.

../_images/scripteditor_gotodef.png

The difference between an assignment and a definition is shown with respect to the image above. In the depicted sample, the definition of the call to myfunc is the original definition of the method, here this is the method calc_diff. The assignment however is the place, where the variable myfunc is introduced for the first time.

*New in itom 3.2

4.2.9. Direction class and method navigator

Above every script, there are two comboboxes that are part of a class and method navigator. If these combo boxes are not available, you need to enable this navigator in the property dialog, tab general. After a configurable number of seconds after the last change in the script, it is analyzed and the combo boxes are adapted with respect to the current structure of the script.

../_images/editor-class-navigator.png

The left combobox displays all classes and the global namespace of the script. By clicking on any class name, the cursor jumps to the class and the name is highlighted. The right combobox shows the sub-items that belong to the chosen class or namespace.

The navigator can distinguish between public and private methods, static methods (with the decorator @staticmethod) and specially marked class methods (decorator @classmethod). All globally defined methods are categorized into the global namespace (Global Scope).

4.2.10. Automatic syntax and code check

If desired, all opened scripts can be continuously be checked for syntax and other errors or hints, like the compliance with the Python style guide (PEP8) or the style guide for docstrings (PEP257).

Basic checks can already be provided, if the python package pyflakes is installed.

Style guide checks etc. (denoted as extended checks) are only available if the package flake8, that depends on pyflakes, pycodestyle and mccabe.

You need to have these packages installed in order to benefit from the desired service. If the necessary packages could not be found, the service is deactivated and a warning appears at startup or if you changed the properties.

The check mode (no check, basic checks, extended checks) as well as the detailed configuration can be done in the corresponding page of the property dialog of itom.

Any kind of message has one of the three possible levels info, warning or error. It is then displayed via one of three possible bug symbols in the left-most margin of the script editor window (blue dot: info, orange dot: warning, red ladybug: error):

../_images/propEditorCodeCheckers.png

The tooltip text of every bug icon displays the reason for the bug. Since the bug icon is displayed in the same margin column than the bookmarks, there is also a combined icon for a bug and a bookmark in one line.

../_images/editor-syntax-check.png

Please note, that one line can also contain multiple syntax hints, they are displayed in multiple lines in the tooltip text.

Note

You can automatically download and install pyflakes, flake8, pycodestyle etc. using the python package manager of itom accessible via the Script menu of the main window.

Click install in the manager and search the python package index for the package pyflakes (or others). Try to call:

import pyflakes

to check if pyflakes is installed correctly.

The bug icons are then available after a restart of itom.

4.2.11. Icon-Browser

To help adding icons to user defined buttons, menus or user interfaces, the icon browser of the script editor window shows a list of icons that come with itom or loaded plugins. The icon browser is opened via the menu edit >> icon browser… of any script editor window or the keyboard shortcut Ctrl + B.

../_images/editorIconBrowser.png

These icons can directly be used inside of any script by their virtual icon path. If you choose a specific icon, you have the following options via the buttons on the right side:

  • Insert and close: The virtual icon path of the selected icon is inserted at the current cursor position in the script and the icon browser is closed.

  • Copy to clipboard: The path is copied to the clipboard. The browser stays open.

  • Cancel: Hides the dialog without further action.

Since there are a lot of icons, it is possible to filter the list by typing parts of an icon filename into the search box on top of the icon list. Instead of using the Copy to clipboard button, it is also possible to copy the path of the selected icon from the textbox below the icon list.