class
System.
System
Bases: object
Access to generic CoDeSys system functionality.
An instance of this object is planted into the scriptengine module with the name "system".
exit
exitcode=0
Exits the application platform by shutting down the engine and exiting the process.
If you just want to terminate the script execution without exitting the platform, call sys.exit() or raise a SystemExitException. (When running the script via --runscript command line parameter in --noUI-Mode, this will also terminate CoDeSys, as there's nothing else to do after the script exitted.)
Parameters
exitcode (int) -- The exitcode we return to the operating system. If omitted, we return the ExitCode 0 which normally means success.
trace
Gets or sets a value indicating whether trace System is active on the current script execution.
trace is the replacement for the old "echo" functionality in the CoDeSys V2.3 batch mode. It adds log messages (Category ScriptMessage, Severity Info) into the IMessageStorage on the following events: Change of source code line, entering and exitting of python scope, exception thrown in python code.
This setting may be ignored: For example, due to internal restrictions in the IronPython Engine, script tracing is disabled in debugging mode.
Return type
bool
Returns
True if trace is activated; otherwise, False.
ui_present
Gets a value indicating whether we have an UI.
If this is false, we're running in a console application or background service.
Return type
bool
Returns
True if [UI present]; otherwise, False.
write_message
severity
stMessage
obj=None
position=-1
length=None
Writes the message to the Message Store.
Position and length are only meaningfull if obj is a ScriptObject and are ignored otherwise.
Parameters
severity (Severity) -- The severity.
stMessage (str) -- The message.
obj (ScriptTreeObject) -- The ScriptObject or ScriptProject the message belongs to.
position (long) -- The position including offset in the data for the message.
length (short) -- The length in the data for the message.
get_messages
category='{194B48A9-AB51-43ae-B9A9-51D3EDAADDF3}'
Gets all messages of a given category which are currently in the store.
Parameters
category (str) -- The category Guid (defaults to the ScriptMessage category)
Return type
list
Returns
The list of message texts
prompt_answers
Gets the prompt answers Dictionary for simulating interactive user input.
This dictionary is used to intercept the IMessageService interface. Whenever a method with a stmessage_key is called, the dictionary is searched for the message_key. If found, the corresponding value is returned (for prompts), or the call is ignored (for errors). All other calls are forwarded to the original messageService.
For this to work, all the keys must be strings matching the message_key values. For Prompts, the following possibilities exist:
|
A PromptResult member |
One of the PromptResult enum members, the list is PromptResult.OK, PromptResult.Cancel, PromptResult.Yes,:attr:PromptResult.No, PromptResult.Retry,:attr:PromptResult.Abort and PromptResult.Ignore. It depends on the exact prompt command which values make sense. |
|
An int |
The MultipleChoicePrompt methods will try to convert the value to an integer for the choice which was selected. |
|
A MultipleChoiceSelector delegate |
For the MultipleChoicePrompt methods, you can also give a delegate which gets the list of strings and returns the result. |
|
A tuple <PromptResult member, PromptChoiceFilter delegate> |
Some prompts present a list with possibly multiple selectable choices, and return a Prompt Result. For those prompts, a PromptResult is accepted as value (with results in none of the choices being selected), or a Tuple <list> containing at least 2 elements: a PromptResult followed by a PromptChoiceFilter delegate which allows the script for fine grained selection. |
If the value given does not make sense in the context of the current prompt, an InvalidCastException is raised.
For errors, the values are not used and don't matter (may be None / None).
To give best semantics for the scripts, this dictionary is a PythonDictionary instance, that means you can easily add values:
# set a value:
System.prompt_answers["OverWriteFiles"] = PromptResult.Cancel
# Set multiple values:
System.prompt_answers.update(
{"OverWriteFiles": PromptResult.OK,
"DisFullError": None})
# Reset everything:
System.prompt_answers.clear()
Return type
dict
Returns
The prompt answers.
executable_filename
Gets the name of the executable file (the currently running application).
Return type
str
process_messageloop
Processes the Win32 message loop of the current Thread, if present.
This allows the UI to be updated during long running processes. It should be safe to call this from python scripts without reentrancy problems, because the ScriptExecutor calls SystemInstances.Engine.Frame.StartLengthyOperation(); to prevent the user from triggering more commands while the script is running.
delay
milliseconds
Delays the script for the specified amount of milliseconds.
The message loop is served during the wait to allow background tasks to be processed. The actual duration of the delay will not meet hard realtime requirements.
Parameters
milliseconds (int) -- The duration to wait
prompt_handling
Gets or sets the way message service prompts are handled.
Version added
3.5.1.0
Return type
ui
Gets the script ui instance.
Version added
3.5.1.0
Return type
commands
Gets the commands.
Version added
3.5.1.0
Return type
factories
Gets the factories.
Version added
3.5.1.0
Return type
execute_on_primary_thread
code
async=False
Executes a specified piece of code in the primary thread.
!!Experts Only!!
Advanced users only! Using multiple threads is neither officially supported nor encouraged in CoDeSys python scripts, you do that "on your own risk". This method is safe to be called from non-primary threads. This method relies on the primary thread processes its message queue. (If you don't know what the message queue is, threads are probably not the right thing for you...) Be careful to ensure that all your own threads are finished when the main thread exits the script, or strange effects can occur. You can use the .NET System.Threading or the python threading module to create new threads.
Version added
3.5.1.0
Parameters
code (PieceOfCode) -- The code to execute. A python function, which will be called without parameters, and should not return any value.
async (bool) -- If true, this method returns immediately, otherwise the this method returns after the delegate has been finished.
get_message_objects
category=None
severities=4294967295
Gets all messages of a given category and severity which are currently in the store.
Version added
3.5.2.0
Parameters
category (str) -- The category Guid (defaults to the ScriptMessage category).
severities (Severity) -- The severities (This can be a combination of several severity flags). By default, all severities are returned.
Return type
list
Returns
The list of message texts.
get_message_categories
bActive=True
Gets all message categories.
Version added
3.5.2.0
Parameters
bActive (bool) -- If set to True (the default), only the active ones (those which had at least one message since the current codesys instance was started) are returned. If set to false, all categories existing in the current installation are returned.
Return type
list
Returns
A list of guids.
get_message_category_description
category
Gets a description for the specified message category.
Version added
3.5.2.0
Parameters
category (Guid) -- The category.
Return type
str
Returns
The description of that message category.
clear_messages
category
Clears the specified category.
Version added
3.5.2.0
abortable
Whether the script is abortable.
Since V3.5.5.0, scripts are abortable by default. The user can abort the script by pressing the Cancel button in the progress display. This property controls whether this Cancel button is enabled.
Version added
3.5.5.0
Return type
bool
abort_autocheck
Gets or sets a value indicating whether this script execution automatically checks for aborts.
If this property is set to True (the default value), the script engine uses the python tracing functionality to check for aborts after every line of executed python code, and throws an KeyboardInterruptException if aborted. You can disable this automatic checks by setting this property to false. Certain debuggin modes also disable this check.
Version added
3.5.5.0
Return type
bool
aborting
Gets a value indicating whether this System is aborting.
This property gets set to true once the user presses an enabled "Cancel" button on the progress display, and it cannot be reset by the script. Use this property for explicit abortion checks when you disabled abort_autocheck.
Version added
3.5.5.0
Return type
bool
progress_start
description
items=-1
unit=''
Starts the progress information for a specific subtask.
Version added
3.5.5.0
Parameters
description (str) -- The description of the subtask.
items (int) -- The number of items, if known in advance.
unit (str) -- The unit of items, for example objects or lines.
progress_step
item
completed=1
Advances the progress of the current subtask.
Version added
3.5.5.0
Parameters
item (str) -- The item which is currently completed.
completed (int) -- The number of items completed in this step.
progress_absolute
item
absolute_progress
Advances the progress of the current subtask.
Version added
3.5.5.0
Parameters
item (str) -- The item which is currently completed.
absolute_progress (int) -- The total number of items completed so far.
class
System.
ScriptMessage
Bases: object
Represents a message from the message storage.
project
The the project of the message position.
If this message does not have a position, None is returned.
Return type
object
The object of the message position.
If this message does not have a position, None is returned.
Return type
position
The position within the database object of the message position.
The interpretation of this number is handled privately by the object. To get a user-friendly display text for this position, the position_text property must be called. If this message does not have a position, 0 is returned.
Return type
long
position_text
The user-friendly display text for position within the database object of the message position.
The interpretation of this number is handled privately by the object. If this message does not have a position, None is returned.
Return type
str
position_offset
Gets an additional character offset to the position returned by the position property.
Return type
short
length
Gets length of Position.
Return type
short
text
Gets the message text.
Return type
str
severity
Gets the severity of this message.
Return type
Severity
FontColor
Gets the color of the message text, or System.Drawing.Color.Empty if the default color is defined.
Return type
Color
has_details_handler
Gets a value indicating whether this ScriptMessage has a details handler.
This is visually indicated by a [...]-Button in the message view.
Return type
bool
call_details_handler
Calls the details handler of this message (this will usually open a popup or similar).
icon
Specialized Icon. If None, the icon is set according to the severity.
Return type
Icon
number
Unambigous number identifying the message according to its category.
Together with the prefix, the number identifies the message. compile, LINT, IO-Config, etc. None is returned if not used.
Return type
uint or None
prefix
A prefix string identifying the message category (compile, LINT, IO-Config, etc).
Together with the number, the message is unambigously identified. None is returned if not used.
Return type
str
System.
PieceOfCode
self
Delegate for a parameterless function without return value.
class
System.
ScriptUI
Bases: object
The script can interact with the user via this instance.
Please note that some of the functionalities depend on the currently installed MessageService instance.
In --noUI-Mode (console-only mode), a basic, somehow restricted implementation querying the user via text input is provided instead. Especially multi-line input is not user friendly, and store_key or predefined values for text input do not work. But as --noUI-Mode is primarily meant for unattended batch execution, it is a bad idea to ask the user in general.
error
message
message_key='ScriptMessage'
*arguments
Reports an error message to the user. This method blocks until the user has acknowledged this message.
Parameters
message (arguments) -- The message to display the user.
message_key (str) -- The message key, for automated filtering / handling by prompt_answers or similar mechanism by other plugins (e. G. automated test tools). Most users can leave the default here.
message -- Optional objects which build the variable part of the message. In other words, if message is build via a string formatting operation, the arguments of that formatting operation should be passed as arguments here. This is for advanced usages via automated test tools, most users can ignore it.
warning
message
message_key='ScriptMessage'
*arguments
Reports an warning message to the user.
This method blocks until the user has acknowledged this message.
Parameters
message (arguments) -- The message to display the user.
message_key (str) -- The message key, for automated filtering / handling by prompt_answers or similar mechanism by other plugins (e. G. automated test tools). Most users can leave the default here.
message -- Optional objects which build the variable part of the message. In other words, if message is build via a string formatting operation, the arguments of that formatting operation should be passed as arguments here. This is for advanced usages via automated test tools, most users can ignore it.
info
message
message_key='ScriptMessage'
*arguments
Reports an informational message to the user.
This method blocks until the user has acknowledged this message.
Parameters
message (arguments) -- The message to display the user.
message_key (str) -- The message key, for automated filtering / handling by prompt_answers or similar mechanism by other plugins (e. G. automated test tools). Most users can leave the default here.
message -- Optional objects which build the variable part of the message. In other words, if message is build via a string formatting operation, the arguments of that formatting operation should be passed as arguments here. This is for advanced usages via automated test tools, most users can ignore it.
prompt
message
choice
default_result
store_description=None
store_key=None
message_key='ScriptMessage'
*arguments
Prompts the user.
This method blocks until the user has answered the question.
This method allows the user to store his/her answer. The next time the same question is prompted to the user by this method, the method immediately returns with the stored result. See also: reset_stored_result()
Parameters
message (str) -- The message to display.
choice (PromptChoice) -- The answers the user can chose from.
default_result (PromptResult) -- The default answer which is displayed to the user in a highlighted manner.
store_description (str) -- The text which is displayed next to the control where the user can decide that (s)he does not want to see that question again (e.g. "Do not show this message again", or "Apply for all objects"). This is optional, but you must supply either both store_description and store_key or none of them.
store_key (str) -- A non-None caller-specific key with which the prompt can be identified. This is optional, but you must supply either both store_description and store_key or none of them.
message_key (str) -- The message key, for automated filtering / handling by System.prompt_answers or similar mechanism by other plugins (e. G. automated test tools). Most users can leave the default here.
arguments (str) -- Optional objects which build the variable part of the message. In other words, if message is build via a string formatting operation, the arguments of that formatting operation should be passed as arguments here. This is for advanced usages via automated test tools, most users can ignore it.
Return type
PromptResult
Returns
The answer provided by the user.
select_many
message
choice
result
items
message_key='ScriptMessage'
*arguments
Prompts the user, allowing the user to select items for which to apply the answer.
This method blocks until the user has answered the question.
This method allows the user to store his/her answer. The next time the same question is prompted to the user by this method, the method immediately returns with the stored result.
Parameters
message (str) -- The message to display.
choice (PromptChoice) -- The answers the user can chose from.
result (PromptResult) -- The result.
items (list) -- An array containing items which are selectable for the user. The objects' ToString methods are used to get the string to display.
message_key (str) -- The message key, for automated filtering / handling by System.prompt_answers or similar mechanism by other plugins (e. G. automated test tools). Most users can leave the default here.
arguments (str) -- Optional objects which build the variable part of the message. In other words, if message is build via a string formatting operation, the arguments of that formatting operation should be passed as arguments here. This is for advanced usages via automated test tools, most users can ignore it.
Return type
list
Returns
A python tuple containing of the PromptResult as the first item, list of booleans in parallel to``items`` as second item, and a (possibly empty) sequence of the selected objects as third item.
choose
message
options
initial_selection=0
cancellable=True
message_key='ScriptMessage'
*arguments
Lets the user choose one of several listed items.
Parameters
message (str) -- The message to display.
options (list) -- A list of options to display. The objects will be converted to string to show them to the user.
initial_selection (int) -- The index of the initially selected object of the list.
cancellable (bool) -- if set to true, the user can cancel / abort the dialog.
message_key (str) -- The message key, for automated filtering / handling by System.prompt_answers or similar mechanism by other plugins (e. G. automated test tools). Most users can leave the default here.
arguments (str) -- Optional objects which build the variable part of the message. In other words, if message is build via a string formatting operation, the arguments of that formatting operation should be passed as arguments here. This is for advanced usages via automated test tools, most users can ignore it.
Return type
list
Returns
A python tuple containing the index of the selected item, or -1 if cancellable was set to True and the user cancelled the dialog as the first item, and the selected item or None as the second item.
reset_stored_result
store_key
Resets any prompt results stored by prompt() or select_many().
Parameters
store_key (str) -- A non-None caller-specific key with which the prompt can be identified.
open_file_dialog
title=None
filename=None
directory=None
filter=None
filter_index=None
default_extension=None
stateguid=None
multiselect=False
check_file_exists=True
check_path_exists=True
Displays an "Open File" dialog.
This method is currently not processed by System.prompt_answers.
In --NoUI-Mode, the user simply can enter a path here.
The "filter" string is a list of descriptions and pattern lists, separated by a pipe symbol ('|'). The pattern list uses the glob syntax, and is separated by a semicolon (';'). For example: Text files (*.txt)|*.txt|Image Files(*.BMP;*.JPG;*.GIF)|*.BMP;*.JPG;*.GIF|All files (*.*)|*.*
Parameters
title (str) -- The title of the dialog window, if you don't pass it, a generic "Python Script: Open File" like text will be displayed.
filename (str) -- The initially selected filename.
directory (str) -- The directory initially displayed. Default is None, which uses the current directory.
filter (str) -- The list of valid extension filters.
filter_index (str) -- Index of the filter which is active when the user opens the dialog. This index is 1-based.
default_extensions (str) -- The default extension which is added to the filename if the user does not add an extension, and the active filter does not specify one.
stateguid (Guid) -- This GUID is used to store the state inside the CoDeSys configuration space when the user closes the Dialog with "ok", and will be used to restore the state when the next dialog is opened with the same guid.
multiselect (bool) -- if set to True, the user may select multiple files.
check_file_exists (bool) -- if set to True, the dialog displays a warning if the user enters a file which does not exist.
check_path_exists (bool) -- if set to True, the dialog displays a warning if the user enters a path which does not exist.
Return type
obj
Returns
The path for the selected file, or a list of pathes if multiselect is allowed, or None if the user cancelled the dialog.
save_file_dialog
title=None
filename=None
directory=None
filter=None
filter_index=None
default_extension=None
stateguid=None
check_file_exists=True
check_path_exists=True
check_overwrite=True
check_create=False
Displays a "Save File" dialog.
This method is currently not processed by System.prompt_answers.
In --NoUI-Mode, the user simply can enter a path here.
The "filter" string is a list of descriptions and pattern lists, separated by a pipe symbol ('|'). The pattern list uses the glob syntax, and is separated by a semicolon (';'). For example: Text files (*.txt)|*.txt|Image Files(*.BMP;*.JPG;*.GIF)|*.BMP;*.JPG;*.GIF|All files (*.*)|*.*
Parameters
title (str) -- The title of the dialog window, if you don't pass it, a generic "Python Script: Save File" like text will be displayed.
filename (str) -- The initially selected filename.
directory (str) -- The directory initially displayed. Default is None, which uses the current directory.
filter (str) -- The list of valid extension filters.
filter_index (str) -- Index of the filter which is active when the user opens the dialog. This index is 1-based.
default_extensions (str) -- The default extension which is added to the filename if the user does not add an extension, and the active filter does not specify one.
stateguid (Guid) -- This GUID is used to store the state inside the CoDeSys configuration space when the user closes the Dialog with "ok", and will be used to restore the state when the next dialog is opened with the same guid.
check_file_exists (bool) -- if set to True, the dialog displays a warning if the user enters a file which does not exist.
check_path_exists (bool) -- if set to True, the dialog displays a warning if the user enters a path which does not exist.
check_overwrite (bool) -- if set to True, the dialog displays a warning if the user selection will overwrite an existing file.
check_create (bool) -- if set to True [check_create].
Return type
str
Returns
The path for the selected file, or None if the user cancelled the dialog.
browse_directory_dialog
message
path=''
root_folder='Environment.SpecialFolder.MyComputer'
new_folder_button=True
Opens a browse directory dialog.
This method is currently not processed by System.prompt_answers.
In --NoUI-Mode, the user simply can enter a path here.
The microsoft documentation for the root folder says: "Only the specified folder and any subfolders that are beneath it will appear in the dialog box and be selectable. The SelectedPath property, along with RootFolder, determines what the selected folder will be when the dialog box is displayed, as long as SelectedPath is an absolute path that is a subfolder of RootFolder (or more accurately, points to a subfolder of the shell namespace represented by RootFolder)."
Parameters
message (str) -- The message to display.
path (str) -- The path to be preselected when the dialog opens.
root_folder (Environment.SpecialFolder) -- The root folder for the browsing dialog.
new_folder_button (bool) -- if set to True, a button which allows the users to create new folders appears in the dialog box.
Return type
str
Returns
The path for the selected directory, or None if the user cancelled the dialog.
query_string
message=''
text=''
multi_line=False
cancellable=False
Queries the user to input or edit a text string.
This method is currently not processed by System.prompt_answers.
Parameters
message (str) -- The message to display for the user.
text (str) -- The text to be prefilled in the textbox.
multi_line (bool) -- if set to True, the user can enter a multiline text.
cancellable (bool) -- if set to True, the user can cancel / abort the dialog.
Return type
str
Returns
The entered string, or None if the user cancelled the dialog.
query_password
message=''
password=''
cancellable=False
Queries the user to input a password.
This method is currently not processed by System.prompt_answers.
Parameters
message (str) -- The message to display for the user.
password (str) -- The password to be prefilled in the textbox.
cancellable (bool) -- if set to True, the user can cancel / abort the dialog.
Return type
str
Returns
The entered password, or None if the user cancelled the dialog.
query_credentials
message=''
username=''
password=''
cancellable=False
Queries the user to input a password.
This method is currently not processed by System.prompt_answers.
Parameters
message (str) -- The message to display for the user.
username (str) -- The username to be prefilled in the textbox.
password (str) -- The password to be prefilled in the textbox.
cancellable (bool) -- if set to True, the user can cancel / abort the dialog.
Return type
list
Returns
A tuple containing the username and password, or None if the user did cancel the dialog.
System.
MultipleChoiceSelector
self
choices
Delegate for selecting one of multiple choices for simulating interactive user input via system.promt_answers.
Script authors have to cast their delegates to this type by wrapping them via a call to MultipleChoiceSelector().
Example::
def MyFilter(choice):
return choice in ("erste", "zweite", "dritte")
system.prompt_answers["my message key"] = PromptChoiceFilter(MyFilter)
Parameters
choices (list) -- The choices.
Return type
int
Returns
The index of the accepted choice.
class
System.
PromptHandling
Bases: enum.Flag
Definition flags for prompt handling. Prompts are standard dialog boxes issued by plugins to inform or query the user.
Simple prompts are those which have only a single button (like a single OK button) and don't leave any choices to the user. Simple prompt handling also applies to prompts with or without message keys, but prompts actually caught by message keys defined in System.prompt_answers are not subject to simple prompt handling. This enum may be extended in future releases. Currently, all handling choices are cumulative, so you can set ForwardSimplePrompts and LogSimplePrompts at the same time.
NONE
= 0
None of the flags are set. This implies that "simple" prompts are silently suppressed.
ForwardSimplePrompts
= 1
Handle simple prompts in their original way. Usually, this means, the user is queried with a dialog box. (However, other plugins may modify that behaviour.) This flag is set by default in UI mode. If you disable this flag, simple promts are not processed in any way.
LogSimplePrompts
= 2
Print simple prompts as a log message, similar to System.write_message(). Log the prompts to the message view with appropriate priority. This is set by default in Non-UI mode.
EnableTextPrompts
= 4
Enables a basic text mode message service implementation in --noUI mode. By default, this flag is not set for compatibility reasons with old scripts, and it is ignored if System.ui_present is true.
If this flag is not set, all MessageServicePrompts which ought to query the user simply return the default value, while ScriptUI.open_file_dialog(), ScriptUI.save_file_dialog(), ScriptUI.browse_directory_dialog(), ScriptUI.query_string(), ScriptUI.query_password() and ScriptUI.query_credentials() simplypop up the standard graphical dialogs.
ProcessScriptPrompts
= 8
If this flag is set, prompts issued by the Script itself via System2.ui are also subject to the System2.prompt_handling and System.prompt_answers processing / filtering. This flag is not set by default.
LogMessageKeys
= 16
Logs all MessageService calls with their message key to the message store. Use this to catch the message keys you need for System.prompt_answers.
Calls without a message key are logged with the key "<<No Key>>", calls which got passed None as message key are logged with "<<None>>"
class
System.
ScriptCommand
Bases: object
Represents a CoDeSys command (Menu, Toolbar, Context Menu).
name
Gets the display text of this command. This string is used as menu item label and usually is localized.
Return type
str
description
Gets the description for this command. This string is used as statusbar text and usually is localized.
Return type
str
tokens
Gets the tokens which introduce a corresponding batch instruction.
For example, a batch command which opens a project file would probably return the two tokens "file" and "open" here.
Return type
list of str
guid
Gets the GUID.
Return type
Guid
class
System.
ScriptCommands
Bases: list
A sequence of all known Commands in CoDeSys.
class
System.
ScriptObjectFactory
Bases: object
guid
Gets the GUID of the object factory.
Return type
Guid
object_type
Gets the guid of the produced object type.
Return type
Guid
object_namespace
Gets a GUID identifying the namespace the created object will belong to.
Return type
Guid
name
Gets the display text of this object factory. This string should be localized.
Return type
str
description
Gets the description for this object factory. This string should be localized.
Return type
str
class
System.
ScriptObjectFactories
Bases: list
A sequence of all known object factories.
search_factories_for
typeguid
Returns all known object factories for a given object type.
The list is ordered, so that perfect matches (which produce exactly the queried type) come before factories which produce subclasses of the queried type. For object permission management, permissions are tested for the first factory of that list which produces that actual type.
Parameters
typeguid (Guid) -- The typeguid
Return type
list
Returns
A (possibly empty) sequence of object factories.
