Dima Granetchi
125 lines
9.3 KiB
Markdown
125 lines
9.3 KiB
Markdown
## bindx2 - кроссплатформенная библиотека для связывания данных на haxe.
|
||
|
||
[](https://travis-ci.org/profelis/bindx2)
|
||
|
||
======
|
||
|
||
## Возможности:
|
||
|
||
- автоматическая генерация сигналов, оповещающих об изменениях свойств или методов класса,
|
||
- автоматическая генерация сеттеров свойств или модификация существующих
|
||
- удобное API для подписки на изменения свойств или методов класса,
|
||
- расширенное API для связывания произвольного выражения,
|
||
- API для быстрого связывания свойств
|
||
- поддержка и валидация `@:bindable` аттрибутов в интерфейсах
|
||
|
||
======
|
||
|
||
## Примеры:
|
||
|
||
```haxe
|
||
// UserModel.hx
|
||
|
||
import bindx.IBindable;
|
||
|
||
@:bindable
|
||
class UserModel implements IBindable
|
||
{
|
||
public var name:String;
|
||
public var coins:Int;
|
||
|
||
public var health:Float = 1;
|
||
|
||
public function new(name:String, coins:Int) {
|
||
this.name = name;
|
||
this.coins = coins;
|
||
}
|
||
}
|
||
```
|
||
...
|
||
```haxe
|
||
// bind complex expression with another field
|
||
unbindOldUser = BindExt.exprTo('Hello ${user.name}. You have ' + user.coins + " coins", this.textField.text);
|
||
|
||
// listen field changes
|
||
Bind.bind(user.health, onHealthChange);
|
||
|
||
function onHealthChange(from:Null<Float>, to:Null<Float>) {
|
||
trace('user health changed from $from to $to');
|
||
}
|
||
```
|
||
|
||
[Все примеры](https://github.com/profelis/bindx2/tree/master/samples/)
|
||
|
||
======
|
||
|
||
## API:
|
||
|
||
Method | Description
|
||
------------ | -------------
|
||
Bind.bind(expr, listener) | `listener` вызывается при смене свойства или метода в `expr`. Слушатель свойства принимает 2 параметра, старое и новое значение свойства, метода - 0 параметров
|
||
Bind.bindTo(expr, toExpr) | Присваивает значение `expr` выражению `toExpr` (NB: в случае метода вызывает метод без параметров!). Автоматически первый вызов НЕ происходит. Метод возвращает ссылку на функцию, позволяющую отписаться.
|
||
Bind.notify(expr, oldValue, newValue) | Ручной вызов оповещения об изменении свойства или метода (в случае метода ожидается только один аргумент в методе `notiry`)
|
||
Bind.unbind(expr, listener) | Удаляется подписка на изменения свойства (NB: если `listener` не указать, произойдет полная отписка всех слушателей!)
|
||
Bind.bindAll(obj:IBindable, listener, force) | `listener(name:String, oldValue:Dynamic, newValue:Dynamic):Void` Подписывается на изменения всех свойств и методов `obj` (force режим создаст все лениво создаваемые сигналы). Вернет колбек для отписки
|
||
Bind.unbindAll(obj:IBindable) | Удаляются все подписки на изменения всех свойств и методов объекта (NB: дальнейшая подписка доступна!)
|
||
|
||
## Расширенное API:
|
||
|
||
Method | Description
|
||
------------ | -------------
|
||
BindExt.chain(chainExpr, listener) | Подписка на последовательность вызовов `a.b.c(1).d..`, срабатывает при любом изменении в цепи вызово, автоматически отписываясь от предыдущего значения и подписываясь на новое. Методы доступно указывать с параметрами. (NB: первый раз `listener` вызывается автоматически). `listener` ведет себя аналогично как и в Bind.bind методе. Метод возвращает ссылку на функцию, позволяющую полностью отписаться.
|
||
BindExt.chainTo(chainExpr, toExpr) | Связывание выражения `chainExpr` с `toExpr`. (NB: первый раз связывание осуществляется автоматически). Метод возвращает ссылку на функцию, позволяющую полностью отписаться.
|
||
BindExt.expr(expr, listener) | Универсальный метод, `expr` может быть произвольным выражением, автоматически будут найдены все `IBindable` объекты и вызовы их свойств на которые можно подписаться. `listener` всегда принимает 2 параметра, в случае метода, предыдущее значение автоматически запомнимается. (NB: первый раз `listener` вызывается автоматически). Метод возвращает ссылку на функцию, позволяющую полностью отписаться.
|
||
BindExt.exprTo(expr, toExpr) | Связывание произвольного выражения `expr` с `toExpr`. (NB: первый раз `listener` вызывается автоматически). Метод возвращает ссылку на функцию, позволяющую полностью отписаться.
|
||
|
||
======
|
||
|
||
## `bindx.IBindable` и @:bindable meta:
|
||
|
||
Свойства и методы с метой `@:bindable` специально обрабатываются. `@:bindable` мета указанная для класса наследуется для всех публичных свойств без указанной `@:bindable` меты. Мета `@:bindable` учитывается только в классах и интерфейсах реализующих пустой интерфейс `bindx.IBindable`.
|
||
|
||
Поддерживает дополнительные параметры `@:bindable(paramName1 = value, paramName2 = value ...)`, короткая запись `paramName` эквивалентна `paramName = true`
|
||
|
||
Parameter | Default value | Description
|
||
------------ | ------------- | -------------
|
||
inlineSetter | false | В случае когда у свойства сеттер отсутствовал и то сгенерируется автоматически. А свойство `inlineSetter` укажет добавить ему `inline` аксессор или нет
|
||
force | false | Режим игнорирует другие параметры, создает сигнал для оповещения об изменениях, но не генерирует сеттеры или редактирует существующий, позволяя программисту самому управлять оповещением об изменениях используя метов `Bind.notify`. Также `force` режим расширяет список допустимых свойств, свойства у которых сеттер указан как `null`, `never` или `dynamic` (без `force` режима связывание подобных свойств невозможно из-за того, что нельзя изменить или создать сеттер).
|
||
lazySignal | true | Управляет правилом создания сигнала для оповещения. Сразу или автоматически при первом запросе (по умолчанию ленивая инициализация активна).
|
||
inlineSignalGetter | false | В случае ленивой инициализации сигнала, когда создается геттер для сигнала, добавляет `inline` аксессор данному геттеру. (NB: актуально только в случае `lazySignal = true`)
|
||
|
||
|
||
======
|
||
|
||
## Логирование:
|
||
|
||
```-D bindx_log=LOG_LEVEL```
|
||
|
||
Log level | Description
|
||
------------ | -------------
|
||
0 | Аналогично выключенному логированию
|
||
1 | Краткий формат логов (оптимальный вариант) (NB: доступна короткая запись -D bindx_log)
|
||
2 | Подробный лог по всем подпискам (полезен при дебаге)
|
||
|
||
======
|
||
|
||
## Установка:
|
||
|
||
`haxelib install bindx2`
|
||
|
||
======
|
||
|
||
## Настройка:
|
||
|
||
Define | Description | Default value
|
||
------------ | ------------- | -------------
|
||
`bindx_lazy_signal` | инициализация сигналов по требованию. `-D bindx_lazy_signal=0` выключает опцию | true
|
||
`bindx_inline_signal_getter` | геттер сигнала инлайнить | false
|
||
`bindx_inline_setter` | инлайнить ли автоматически сгенерированные сеттеры | false
|
||
|
||
======
|
||
|
||
## Дополнительно
|
||
|
||
- BindExt и `this`. Используйте `this.bindableA.bindableB` если необходимо слушать изменения `bindableA`, а не только `bindableB`
|