Released 1.9.6-b5. #83

.github/CONTRIBUTING.md

@@ -54,7 +54,8 @@ Releasing a new KTX version:
 - Change `libVersion` settings in `version.txt`. KTX uses the same versioning schema as LibGDX (mimicking the
 LibGDX version that it was compiled against) with optional `-b#` or `-SNAPSHOT` suffixes depending on version status.
 - Run `gradle build install uploadArchives closeAndPromoteRepository` to push artifacts to both _Maven Local_ and
-_Maven Central_.
+_Maven Central_. Note that Maven plugin has its issues and you might need to run `gradle promoteRepository` after the
+previous task sequence (if it fails on the `closeAndPromoteRepository` task).
 - Run `gradle distZip` to prepare archive with KTX sources, compiled binary and documentation.
 - Upload the archive to [releases](https://github.com/libktx/ktx/releases) section. Tag should match released version.
 Name of the release should match `KTX $libVersion`. Copy latest [changelog](../CHANGELOG.md) entries to release

.github/CONTRIBUTORS.md

@@ -3,13 +3,14 @@ Project contributors listed chronologically.
 * [@czyzby](https://github.com/czyzby)
   * Author of most libraries, main maintainer.
 * [@kotcrab](https://github.com/kotcrab)
-  * Author of [`VisUI`](../vis) extension.
+  * Author of [`VisUI` extension](../vis).
 * [@MrPlow442](https://github.com/MrPlow442)
   * Contributed LibGDX [collections](../collections) utilities.
 * [@sreich](https://github.com/sreich)
   * Contributed various utilities from [Ore Infinium](https://github.com/sreich/ore-infinium) project.
 * [@raincole](https://github.com/raincole)
   * Provided insightful review of the [`Async`](../async) module.
+    Contributed LibGDX [collections](../collections) utilities.
 * [@Jkly](https://github.com/Jkly)
-  * Author of [gdx-box2d-kotlin](https://github.com/Jkly/gdx-box2d-kotlin), which inspired the `Box2D` **KTX** library.
-    Provided insightful review of the [`Box2D`](../box2d) module.
+  * Author of [`Ashley` module](../ashley), as well as the [gdx-box2d-kotlin](https://github.com/Jkly/gdx-box2d-kotlin)
+    library, which inspired the `Box2D` **KTX** module. Provided insightful review of the [`Box2D`](../box2d) module.

.travis.yml

@@ -2,8 +2,8 @@ language: java
 jdk:
   - oraclejdk8
 
-install: gradle assemble install -x dokka -x dokkaJavadoc
-script: gradle check -x dokka -x dokkaJavadoc
+install: ./gradlew assemble install -x dokka -x dokkaJavadoc
+script: ./gradlew check -x dokka -x dokkaJavadoc
 
 before_cache:
   - rm -f  $HOME/.gradle/caches/modules-2/modules-2.lock

CHANGELOG.md

@@ -1,3 +1,22 @@
+#### 1.9.6-b5
+
+- **[UPDATE]** Updated to Kotlin 1.1.2-5.
+- **[UPDATE]** Updated to Kotlin Coroutines 0.16.
+- **[FEATURE]** (`ktx-actors`) `onChange`, `onClick`, `onKey`, `onKeyDown`, `onKeyUp`, `onScrollFocus` and `onKeyboardFocus`
+factory methods for `EventListener` instances were added. Contrary to existing factory methods, these use minimal set
+of parameters to make listeners creation as concise as possible.
+- **[CHANGE]** (`ktx-actors`) Existing `onChange`, `onClick`, `onKey`, `onKeyDown`, `onKeyUp`, `onScrollFocus` and
+`onKeyboardFocus` factory methods where renamed to `onChangeEvent`, `onClickEvent`, `onKeyEvent`, `onKeyDownEvent`,
+`onKeyUpEvent`, `onScrollFocusEvent` and `onKeyboardFocusEvent` respectively. Their excessive amount of parameters,
+useful only on rare occasions, led to unnecessary boilerplate during listeners creation. See `ktx-actors` file
+documentation for migration guide.
+- **[FEATURE]** (`ktx-ashley`) new **KTX** module with Ashley entity component system utilities: `ktx-ashley`.
+  - `PooledEngine.add` and `PooledEngine.entity` extension methods.
+  - `PooledEntity` wrapping `Entity` and providing access to `PooledEngine` API.
+  - `mapperFor` factory method that allows to create `ComponentMapper` instances.
+  - Accessors for `Entity` objects using `ComponentMappers`: `get`, `has`, `hasNot`, `remove`.
+  - DSL methods for constructing `Family` builders with `KClass` instances: `oneOf`, `allOf`, `exclude`.
+
 #### 1.9.6-b4
 
 - **[FEATURE]** (`ktx-collections`) Added `map`, `filter` and `flatten` extension methods that return LibGDX collections.
@@ -12,7 +31,7 @@
 #### 1.9.6-b3
 
 - **[UPDATE]** Updated to Kotlin 1.1.2-3.
-- **[UPDATE]** Updated to Kotlin Coroutines to 0.15.
+- **[UPDATE]** Updated to Kotlin Coroutines 0.15.
 - **[CHANGE]** (`ktx-assets`) Static `AssetManager` instance container - `Assets` - was removed. All top level functions
 depending on the global `AssetManager` were removed.
 - **[FEATURE]** (`ktx-assets`) Added `FileType.getResolver` extension method creating `FileHandleResolver` instances.

README.md

@@ -1,6 +1,6 @@
 [![Travis CI](https://travis-ci.org/libktx/ktx.svg?branch=master)](https://travis-ci.org/libktx/ktx)
 [![Maven Central](https://img.shields.io/maven-central/v/io.github.libktx/ktx-async.svg)](https://search.maven.org/#search%7Cga%7C1%7Cg%3A%22io.github.libktx%22)
-[![Kotlin](https://img.shields.io/badge/kotlin-1.1.2--3-orange.svg)](http://kotlinlang.org/)
+[![Kotlin](https://img.shields.io/badge/kotlin-1.1.2--5-orange.svg)](http://kotlinlang.org/)
 [![LibGDX](https://img.shields.io/badge/libgdx-1.9.6-red.svg)](https://libgdx.badlogicgames.com/)
 
 [![KTX](.github/ktx-logo.png "KTX")](http://libktx.github.io)

actors/README.md

@@ -26,15 +26,19 @@ a `Group` with `actor in group` syntax.
 #### Event listeners
 
 - Lambda-compatible `Actor.onChange` method was added. Allows to listen to `ChangeEvents`.
-- Lambda-compatible `Actor.onClick` methods were added. (More verbose version has access to local coordinates of the click
-events.) Attaches `ClickListeners`.
+- Lambda-compatible `Actor.onClick` method was added. Attaches `ClickListeners`.
 - Lambda-compatible `Actor.onKey` method was added. Allows to listen to `InputEvents` with `keyTyped` type.
 - Lambda-compatible `Actor.onKeyDown` and `Actor.onKeyUp` methods were added. They allow to listen to `InputEvents`
 with `keyDown` and `keyUp` type, consuming key code of the pressed or released key (see LibGDX `Keys` class).
 - Lambda-compatible `Actor.onScrollFocus` method was added. Allows to listen to `FocusEvents` with `scroll` type.
 - Lambda-compatible `Actor.onKeyboardFocus` method was added. Allows to listen to `FocusEvents` with `keyboard` type.
 - `KtxInputListener` is an open class that extends `InputListener` with no-op default implementations and type
 improvements (nullability data).
+- `onChangeEvent`, `onClickEvent`, `onKeyEvent`, `onKeyDownEvent`, `onKeyUpEvent`, `onScrollFocusEvent` and
+`onKeyboardFocusEvent` `Actor` extension methods were added. They consume the relevant `Event` instances as lambda
+parameters. Both listener factory variants are inlined, but the ones ending with *Event* provide more lambda parameters
+and allow to inspect the original `Event` instance that triggered the listener. Regular listener factory methods should
+be enough for most use cases.
 
 #### Actions
 
@@ -90,25 +94,79 @@ textField.setKeyboardFocus(true)
 scrollPane.setScrollFocus(false)
 ```
 
-Adding event listeners:
+Adding a `ChangeListener` to an `Actor`:
+
+```Kotlin
+import ktx.actors.*
+
+button.onChange {
+  println("Button changed!")
+}
+
+button.onChangeEvent { changeEvent, actor ->
+  // If you need access to the original ChangeEvent, use this expanded method variant.
+  println("$actor changed by $changeEvent!")
+}
+```
+
+Adding a `ClickListener` to an Actor:
+
+```Kotlin
+import ktx.actors.*
+
+label.onClick { 
+  println("Label clicked!")
+}
+
+label.onClickEvent { inputEvent, actor ->
+  // If you need access to the original InputEvent, use this expanded method variant.
+  println("$actor clicked by $inputEvent!")
+}
+label.onClickEvent { inputEvent, actor, x, y ->
+  // If you need access to the local actor click coordinates, use this expanded method variant.
+  println("$actor clicked by $inputEvent at ($x, $y)!")
+}
+```
+
+Adding an `EventListener` which consumes typed characters:
+
 ```Kotlin
 import ktx.actors.*
 
-button.onChange { changeEvent, button ->
-  println("$button changed!") }
-
-label.onClick { inputEvent, label ->
-  println("$label clicked!") }
-table.onClick { inputEvent, table, x, y ->
-  println("$table clicked at (${x}, ${y})!") }
-
-textField.onKey { inputEvent, textField, key ->
-  println("Typed $key char in ${textField}!") }
-
-scrollPane.onScrollFocus { focusEvent, scrollPane ->
-  println("$scrollPane focus: ${event.isFocused}!") }
-textField.onKeyboardFocus { focusEvent, textField ->
-  println("$textField focus: ${event.isFocused}!") }
+textField.onKey { key ->
+  println("Typed $key char to text field!")
+}
+
+textField.onKeyEvent { inputEvent, actor, key ->
+  // If you need access to the original InputEvent, use this expanded method variant.
+  println("Typed $key char to $actor by $inputEvent!")
+}
+```
+
+Adding `EventListeners` which listen to `FocusEvents`:
+
+```Kotlin
+import ktx.actors.*
+
+// FocusEvent with scroll type:
+scrollPane.onScrollFocus { focused ->
+  println("Scroll pane is focused: $focused!")
+}
+
+scrollPane.onScrollFocusEvent { focusEvent, actor ->
+  // If you need access to the original FocusEvent, use this expanded method variant.
+  println("$actor is focused: ${focusEvent.isFocused}!")
+}
+
+// FocusEvent with keyboard type:
+textField.onKeyboardFocus { focused ->
+  println("Text field is focused: $focused!")
+}
+
+textField.onKeyboardFocusEvent { focusEvent, actor ->
+  // If you need access to the original FocusEvent, use this expanded method variant.
+  println("$actor is focused: ${focusEvent.isFocused}!")
+}
 ```
 
 Chaining actions (`SequenceAction` utility):
@@ -159,6 +217,16 @@ class MyInputListener : KtxInputListener() {
 }
 ```
 
+#### Migration guide
+
+In **KTX** up to `1.9.6-b4`, extension methods `onChange`, `onClick`, `onKey`, `onKeyDown`, `onKeyUp`, `onScrollFocus`
+and `onKeyboardFocus` consumed `Event` and `Actor` instances. This lead to common usage of `_, _ ->`, which was against
+the goal of boilerplate-less listeners. That is why the existing listener factory methods where renamed with `Event`
+suffix, and a new set of extension methods with the same names were added - this time consuming a minimal amount of
+parameters. Add `Event` suffix to each of your listener methods or refactor them to the new API with less parameters.
+For example, if you used `Actor.onChange` extension method, use `Actor.onChangeEvent` instead or remove the `event, actor`
+parameters if you do not really need them at all.
+
 ### Alternatives
 
 - [VisUI](https://github.com/kotcrab/vis-editor/wiki/VisUI) includes some `Scene2D` utilities, as well as some extended