## Communicating with NIM

**Using NimQml - General Overview**

Nim objects meant to be exposed to QT import `NimQml` and use the `QtObject` macro, there is some basic methods that need to be setup for every `QtObject` such as `setup`, `delete`, and when initializing the object the `new` and `setup` method need to be called.
A basic QtObject will look like something like:

```nimrod=
import NimQml

QtObject:
    type MyView* = ref object of QObject
        someField*: string

    proc setup(self: MyView) =
        self.QObject.setup

    proc delete*(self: MyView) =
        self.QObject.delete

    proc newMyView*(): MyView =
        new(result, delete)
        result = MyView()
        result.setup
```

The object then is exposed to QML by creating and registering a `QVariant`

```nimrod=
import NimQml

...

# create variant
var view = newMyView()
var variant: QVariant = newQVariant(view)

# expose it to QML
let engine = newQQmlApplicationEngine()
engine.setRootContextProperty("MyNimObject", variant)
```

The variable `MyNimObject` is then accessible in QML and represent `MyView` and its methods or variables that have been defined to be exposed to QML, for example, adding:

```qml
proc foo*(self: MyView): string {.slot.} =
    "hello world"
```

and in QML doing

```qml
Text {
    text: "NIM says" + MyNimObject.foo()
}
```

will create a text "NIM says hello world"

**NimQml in nim-status-client**

The QtObjects are defined in `src/app/<module>/view.nim` and `src/app/<module>/views/`, they typically include the nim-status object as a parameter, for example `src/app/profile/view.nim`:

```nimrod=
...
QtObject:
  type ProfileView* = ref object of QObject
    ...
    status*: Status

  proc newProfileView*(status: Status): ProfileView =
    new(result, delete)
    result = ProfileView()
    ...
    result.status = status
    result.setup
  ...
```

The variant is created and wrapped in the "controller" `src/app/<module>/core.nim`, for example `src/app/profile/core.nim`:

```nimrod=
...
type ProfileController* = ref object of SignalSubscriber
  view*: ProfileView
  variant*: QVariant
  status*: Status

proc newController*(status: Status): ProfileController =
  result = ProfileController()
  result.status = status
  result.view = newProfileView(status)
  result.variant = newQVariant(result.view)
```

This controller is initialized in `src/nim_status_client.nim` and the variant is registered there, for example:

```nimrod=
var profile = profile.newController(status)
engine.setRootContextProperty("profileModel", profile.variant)
```

this variant is then accessible in QML as `profileModel`, for example in `ui/app/AppLayouts/Profile/Sections/AboutContainer.qml` the node version is displayed with:

```qml
...
    StyledText {
        text: qsTr("Node Version: %1").arg(profileModel.nodeVersion())
        ...
    }
...
```

**exposing methods to QML**

Methods can be exposed to QML need to be public and use the `{.slot.}` pragma

```nimrod=
QtObject:
    ...
    proc nodeVersion*(self: ProfileView): string {.slot.} =
        self.status.getNodeVersion()
```

**QtProperty Macro for simple types**

There is a handy `QtProperty[type]` macro, this macro defines what methods to call to get the latest value (`read`), which method updates that value (`write`) and a signal that notifies that value has changed (`notify`), here is a real example from `src/app/wallet/view.nim` that defines the `defaultCurrency` property

```nimrod=
  proc defaultCurrency*(self: WalletView): string {.slot.} =
    self.status.wallet.getDefaultCurrency()

  proc defaultCurrencyChanged*(self: WalletView) {.signal.}

  proc setDefaultCurrency*(self: WalletView, currency: string) {.slot.} =
    self.status.wallet.setDefaultCurrency(currency)
    self.defaultCurrencyChanged() # notify value has changed

  QtProperty[string] defaultCurrency:
    read = defaultCurrency
    write = setDefaultCurrency
    notify = defaultCurrencyChange
```

note: it's not necessary to define all these fields except for `read`

**QtProperty Macro for other QObjects**

This macro can also be used to expose other QtObjects as QVariants, this is typically done to simplify code and sometimes even required for things that need to be their own individual QTObjects such as Lists.

For example, in `src/app/profile/view.nim` the profileView QtObject (`src/app/profile/profileView.nim`) is exposed to QML with:

```nimrod=
QtObject:
    type ProfileView* = ref object of QObject
        profile*: ProfileInfoView
        ...
    ...
    proc getProfile(self: ProfileView): QVariant {.slot.} =
        return newQVariant(self.profile)

    proc setNewProfile*(self: ProfileView, profile: Profile) =
        self.profile.setProfile(profile)

    QtProperty[QVariant] profile:
        read = getProfile
```

**QAbstractListModel**

Lists are exposed to QML using a `QAbstractListModel` object, this method expects certain methods to be defined so QML can access the data: `rowCount`, `data` and `roleNames`
Other methods can be found in the QT documentation [here](https://doc.qt.io/qt-5/qabstractitemmodel.html)

Let's take as an example `src/app/wallet/views/asset_list.nim`

First the imports

```nim
import NimQml
import tables
```

then we define the `QtObject` macro as usual but this time the object uses `QAbstractListModel`

```nim
QtObject:
  type AssetList* = ref object of QAbstractListModel
    assets*: seq[Asset]
```

`assets` is the sequence that will hold the assets, `Asset` is imported and defined in `src/status/wallet/accounts.nim` and is a simple nim object

```nimrod=
type Asset* = ref object
    name*, symbol*, value*, fiatValue*, accountAddress*, address*: string
```

then there is the typical required initialization

```nimrod=
  proc setup(self: AssetList) = self.QAbstractListModel.setup

  proc delete(self: AssetList) =
    self.QAbstractListModel.delete
    self.assets = @[]

  proc newAssetList*(): AssetList =
    new(result, delete)
    result.assets = @[]
    result.setup
```

a role enum type needs to be defined, specifying the name of each field

```nimrod=
type
  AssetRoles {.pure.} = enum
    Name = UserRole + 1,
    Symbol = UserRole + 2,
    Value = UserRole + 3,
    FiatValue = UserRole + 
```

for the data to be exposed there are methods that need to be defined such as `rowCount` and `data`:

```nimrod=
  # returns total assets
  method rowCount(self: AssetList, index: QModelIndex = nil): int =
    return self.assets.len

  # returns Asset object at given index
  method data(self: AssetList, index: QModelIndex, role: int): QVariant =
    if not index.isValid:
      return
    if index.row < 0 or index.row >= self.assets.len:
      return
    let asset = self.assets[index.row]
    let assetRole = role.AssetRoles
    case assetRole:
    of AssetRoles.Name: result = newQVariant(asset.name)
    of AssetRoles.Symbol: result = newQVariant(asset.symbol)
    of AssetRoles.Value: result = newQVariant(asset.value)
    of AssetRoles.FiatValue: result = newQVariant(asset.fiatValue)
    
  # returns table with columns names and values
  method roleNames(self: AssetList): Table[int, string] =
    { AssetRoles.Name.int:"name",
    AssetRoles.Symbol.int:"symbol",
    AssetRoles.Value.int:"value",
    AssetRoles.FiatValue.int:"fiatValue" }.toTable
```

The asset list has been exposed in `src/app/wallet/view.nim` as QVariant called `assets` and the table can be display in QML, for example using a `ListView`:

```qml
    ListView {
        model: walletModel.assets // the table
        delegate: Text {
            text: "name:" + name + " | symbol: " + symbol
        }
    }
```

**TODO**: qml components with default properties
**TODO**: reusable qml components
**TODO**: qml components alias properties