Scripting in Application (Python)

In this article:

Using .NET types
Global Variables
Global Functions
See Also

Python 3.4 which runs in .NET environment and is allowed accessing .NET types and functions.

Scripting in Python 3.4 is supported by ULogViewer 3.0+.

Using .NET types

.NET types are allowed to be accessed from Python, you just need to import types which you want to use.

For example:

            from System.IO import StreamReader

            from System.Text import Encoding

            stream = StreamReader("...", Encoding.Utf8)

            ......

            stream.Close()

.NET extension methods are not supported currently. You cannot call extension methods as static method.

⬆️ Back to top

Global Variables

There are 3 global variables in script runtime environment no matter what purpose the script for:

app
cancellation_token
context

app

Allows script accessing the application-level functions. The followings are members of app:

ExecuteCommand(command: string, cancellationToken: CancellationToken): intULogViewer 3.0+
ExecuteCommand(command: string, action: FunctionType, cancellationToken: CancellationToken): intULogViewer 3.0+
Execute external command and get exit code of command.

action is a call-back function to let you send data to standard input and read data from standard output/error from process of command, for example:
def read_from_my_command(process, cancellationToken):
    reader = process.StandardOutput
    line = reader.ReadLine()
    while line:
        # Process the read line...
        line = reader.ReadLine()

app.ExecuteCommand("my_command", read_from_my_command)
FindCommandPath(command: string, cancellationToken: CancellationToken): string
Find absolute path to the given command. Will returns None if command cannot be found.
GetFormattedString(string key, *args): string
Get format defined in application resources and generate formatted string with given arguments.
GetString(string key): string
GetString(key: string, defaultString: string): string
Get string resource with given key.
GetStringNonNull(key: string): string
GetStringNonNull(key: string, defaultString: string): string
Get string resource with given key which makes sure that the string won't be None.
IsDebugMode: bool
Check whether application is running in debug mode or not.
IsMainThread: bool
Check whether current thread is the main thread of application or not.
MainThreadSynchronizationContext: SynchronizationContext
Get System.Threading.SynchronizationContext of main thread of application.

cancellation_token

System.Threading.CancellationToken for checking whether cancellation of script running has been requested or not.

You can use is_cancellation_requested() global function directly.

context

Allows accessing functions according to purpose of script. The actual instance of context is also decided by the purpose of script. The followings are basic members of context:

Data: IDictionary<string, object>
A dictionary which stores custom data. The data may be transferred across scripts if scripts belong to same set of same purpose.
GetString(key: string): string
GetString(key: string, defaultString: string): string
Get the string with given key defined in context by calling PrepareStrings(). Will fallback to string defined in application if it cannot be found in context, or fallback to defaultString if string cannot be found in application either.
Logger: ILogger
Allow writing log to log buffer and file of ULogViewer.
You can use log_*() global functions directly.
PrepareStrings(preparation: FunctionType)
PrepareStrings(cultureName: string, preparation: FunctionType)
Setup string table for specific culture. The format of cultureName is languagecode2-country/regioncode2. For ex, en-US. You can also pass None to cultureName to define default string table.

preparation is a call-back function to setup string table. For example:
def setup_en_us_strings(table):
table["Message"] = "Hello"

def setup_zh_tw_strings(table):
table["Message"] = "哈囉"

context.PrepareStrings(None, setup_en_us_strings)
context.PrepareStrings("zh-TW", setup_zh_tw_strings)

String tables are dedicated for each context. Therefore, string tables setup through PrepareStrings() can only be accessed by its context.
ShowMultipleItemsSelectionDialog(message: string, items: IList): IListULogViewer 4.0+
ShowMultipleItemsSelectionDialog(message: string, items: IList, defaultItemIndex: int): IListULogViewer 4.0+
Show dialog to let user select one or more items. The returned value is the list of indices of selected items.
ShowSingleItemSelectionDialog(message: string, items: IList): intULogViewer 4.0+
ShowSingleItemSelectionDialog(message: string, items: IList, defaultItemIndex: int): intULogViewer 4.0+
Show dialog to let user select one item. The returned value is the index of selected item, or -1 if nothing is selected.
ShowMessageDialog(message: string): MessageDialogResult
ShowMessageDialog(message: string, icon: MessageDialogIcon): MessageDialogResult
ShowMessageDialog(message: string, icon: MessageDialogIcon, buttons: MessageDialogButtons): MessageDialogResult
Shows message dialog and wait for result selected by user.
Values defined in MessageDialogIcon:
- error
- Information (default)
- Question
- Success
- Warning
Values defined in MessageDialogButtons:
- Ok (default)
- OKCancel
- YesNo
- YesNoCancel
Values defined in MessageDialogResult:
- Cancel
- No
- OK
- Yes
ShowTextInputDialog(message: string): string
ShowTextInputDialog(message: string, initText: string): string
Shows text input dialog and wait for text input by user.

⬆️ Back to top

Global Functions

is_cancellation_requested(): bool

Check whether cancellation of script running has been requested or not. It is same as checking cancellation_token.IsCancellationRequested.

log_error(obj)

Write log with Error level.

log_debug(obj)

Write log with Debug level.

log_info(obj)

Write log with Information level.

log_trace(obj)

Write log with Trace level.

You can use print() function which also writes log with Trace level.

log_warning(obj)

Write log with Warning level.

⬆️ Back to top