# Python-based Data Binding

The Player Connector Library is a simple library written in Python and c++ that provides functionality to start and load scene composer binary assets and interact with a predefined set of data binding items (<span style="color: rgb(230, 126, 35);">[Variant](http://dev.doc.cgistudio.at/APILINK/class_feat_std_1_1_variant.html)</span>) through Python scripting.

### Player Connector Library Package

The main functionality of the library is contained in two files, **`CanderaAppConnector.py`** <sup>\[1\]</sup> and `<strong>BindingSourceEnum.py</strong>` <sup>\[2\]</sup>. These files contain three classes.

- `CanderaAppConnector`: This is the main class to be used to play assets and interact with them using data binding
- `BindingSourceEnum`: A Python enum generated by the build pipeline that contains the enum keys to be used when setting and getting data binding items. The keys underlay the nomenclature "SOURCE&lt;*sourceIndex&gt;*ITEM&lt;i*temIndex&gt;"*. Source - and item index start at one and go to ten, as we currently have ten predefined binding sources and ten items per source.
- `Logger`: Logger class that my be used to generate logs with compliant format and logging levels

The sources and types listed above are contained in a file system Python package that can be installed with pip.

```bash
pip install path/to/python/library/root/folder



```

<p class="callout info">It is suggested to install the library to a virtual environment and not to the global Python installation. For an exemplary usage refer to the [<span style="color: rgb(230, 126, 35);">Blood Pressure Sample</span>](https://doc316en.candera.eu/books/cgi-studio-professional-edition/page/blood-pressure-sample "Blood Pressure Sample") documentation and source code.</p>

\[1\]: */bin/ProfessionalEdition/Python/CanderaAppConnector/CanderaAppConnector.py*  
\[2\]: */bin/ProfessionalEdition/Python/Generated/BindingSourceEnum.py*

#### Workflow

The general workflow using the Player Connector Library package consists of:

1. Constructing the library with the Player Connector Library binary contained in the delivered package (PlayerConnectorLibrary)
2. Initializing the library with the asset binary
3. Optionally register data binding callbacks
4. Continuously calling step to invoke the render loop and internal message delivery
5. Interact with data bindings. Note that internally, changes to the data bindings are reflected on the view when step is called
6. Shutdown library and gracefully exit program

#### Documentation

#### Constructor

Creates and instance of this class. Expects and absolute or relative path to the Player Connector Library binary as parameter.

<table border="1" id="bkmrk-parameters-binarypat" style="border-collapse: collapse; width: 100%;"><colgroup><col style="width: 50%;"></col><col style="width: 50%;"></col></colgroup><tbody><tr><td>Parameters</td><td>1. `<strong>BinaryLibraryPath</strong>`: Absolute or relative path to the Player Connector Library binary

</td></tr></tbody></table>

#### Init

Initializes the player with the provided asset path. Expects an absolute or relative path to the asset binary as parameter. Must be called before every other method. Returns a bool value whether the operation was successful.

<table border="1" id="bkmrk-parameters-assetpath" style="border-collapse: collapse; width: 100%; height: 99.8281px;"><colgroup><col style="width: 50%;"></col><col style="width: 50%;"></col></colgroup><tbody><tr style="height: 70.0312px;"><td style="height: 70.0312px;">Parameters</td><td style="height: 70.0312px;">1. `<strong>AssetPath</strong>`: Absolute or relative path to the asset binary

</td></tr><tr style="height: 29.7969px;"><td style="height: 29.7969px;">Returns</td><td style="height: 29.7969px;">The bool value</td></tr></tbody></table>

#### Step

Invokes the internal message processing and render loop execution. Needs to be called continuously. Databinding updates are reflected internally during the invocation of this method. Returns a bool value whether the operation was successful.

<table border="1" id="bkmrk-parameters-none-retu" style="border-collapse: collapse; width: 100%;"><colgroup><col style="width: 50%;"></col><col style="width: 50%;"></col></colgroup><tbody><tr><td>Parameters</td><td>None</td></tr><tr><td>Returns</td><td>The bool value</td></tr></tbody></table>

#### SetIntValue

Sets an integer value to a predefined databinding source item.

<table border="1" id="bkmrk-parameters-bindingso" style="border-collapse: collapse; width: 100%;"><colgroup><col style="width: 50%;"></col><col style="width: 50%;"></col></colgroup><tbody><tr><td>Parameters</td><td>1. `<strong>BindingSourceItem</strong>`: Enum that specifies the binding source item. Enum is defined in *Generated/BindingSourceEnum.py*
2. `<strong>Value</strong>`: The integer value

</td></tr><tr><td>Returns</td><td>The bool value</td></tr></tbody></table>

#### SetBoolValue

Sets a bool value to a predefined databinding source item.

<table border="1" id="bkmrk-parameters-bindingso-1" style="border-collapse: collapse; width: 100%;"><colgroup><col style="width: 50%;"></col><col style="width: 50%;"></col></colgroup><tbody><tr><td>Parameters</td><td>1. `<strong>BindingSourceItem</strong>`: Enum that specifies the binding source item. Enum is defined in *Generated/BindingSourceEnum.py*
2. `<strong>Value</strong>`: The bool value

</td></tr><tr><td>Returns</td><td>The bool value</td></tr></tbody></table>

#### SetStringValue

Sets a string to a predefined databinding source item.

<table border="1" id="bkmrk-parameters-bindingso-2" style="border-collapse: collapse; width: 100%;"><colgroup><col style="width: 50%;"></col><col style="width: 50%;"></col></colgroup><tbody><tr><td>Parameters</td><td>1. `<strong>BindingSourceItem</strong>`: Enum that specifies the binding source item. Enum is defined in *Generated/BindingSourceEnum.py*
2. `<strong>Value</strong>`: The string

</td></tr><tr><td>Returns</td><td>The bool value</td></tr></tbody></table>

#### SetFloatValue

Sets a float value to a predefined databinding source item.

<table border="1" id="bkmrk-parameters-bindingso-3" style="border-collapse: collapse; width: 100%;"><colgroup><col style="width: 50%;"></col><col style="width: 50%;"></col></colgroup><tbody><tr><td>Parameters</td><td>1. `<strong>BindingSourceItem</strong>`: Enum that specifies the binding source item. Enum is defined in *Generated/BindingSourceEnum.py*
2. `<strong>Value</strong>`: The float value

</td></tr><tr><td>Returns</td><td>The bool value</td></tr></tbody></table>

#### GetIntValue

Gets an int value from a predefined databinding source item.

<table border="1" id="bkmrk-parameters-bindingso-4" style="border-collapse: collapse; width: 100%;"><colgroup><col style="width: 50%;"></col><col style="width: 50%;"></col></colgroup><tbody><tr><td>Parameters</td><td>1. `<strong>BindingSourceItem</strong>`: Enum that specifies the binding source item. Enum is defined in *Generated/BindingSourceEnum.py*

</td></tr><tr><td>Returns</td><td>The integer value</td></tr></tbody></table>

#### GetBoolValue

Gets a bool value from a predefined databinding source item.

<table border="1" id="bkmrk-parameters-bindingso-5" style="border-collapse: collapse; width: 100%;"><colgroup><col style="width: 50%;"></col><col style="width: 50%;"></col></colgroup><tbody><tr><td>Parameters</td><td>1. `<strong>BindingSourceItem</strong>`: Enum that specifies the binding source item. Enum is defined in *Generated/BindingSourceEnum.py*

</td></tr><tr><td>Returns</td><td>The bool value</td></tr></tbody></table>

#### GetStringValue

Gets a string from a predefined databinding source item.

<table border="1" id="bkmrk-parameters-bindingso-6" style="border-collapse: collapse; width: 100%;"><colgroup><col style="width: 50%;"></col><col style="width: 50%;"></col></colgroup><tbody><tr><td>Parameters</td><td>1. `<strong>BindingSourceItem</strong>`: Enum that specifies the binding source item. Enum is defined in *Generated/BindingSourceEnum.py*

</td></tr><tr><td>Returns</td><td>The string</td></tr></tbody></table>

#### GetFloatValue

Gets a float value from a predefined databinding source item.

<table border="1" id="bkmrk-parameters-bindingso-7" style="border-collapse: collapse; width: 100%;"><colgroup><col style="width: 50%;"></col><col style="width: 50%;"></col></colgroup><tbody><tr><td>Parameters</td><td>1. `<strong>BindingSourceItem</strong>`: Enum that specifies the binding source item. Enum is defined in *Generated/BindingSourceEnum.py*

</td></tr><tr><td>Returns</td><td>The float value</td></tr></tbody></table>

#### RegisterCallback

Registers a callback method. Multiple methods can be registered. Passed method must have two parameters. First param is BindingSourceItem and second parameter is value.

<table border="1" id="bkmrk-parameters-callbackf" style="border-collapse: collapse; width: 100%;"><colgroup><col style="width: 50%;"></col><col style="width: 50%;"></col></colgroup><tbody><tr><td>Parameters</td><td>1. **`CallbackFn`**: Callable type with two parameters

</td></tr><tr><td>Returns</td><td>The bool value</td></tr></tbody></table>

#### ShutDown

Shuts down the asset player and frees up allocated resources.

<table border="1" id="bkmrk-parameters-none-retu-1" style="border-collapse: collapse; width: 100%;"><colgroup><col style="width: 50%;"></col><col style="width: 50%;"></col></colgroup><tbody><tr><td>Parameters</td><td>None</td></tr><tr><td>Returns</td><td>The bool value</td></tr></tbody></table>