Released KTX 1.9.10-b4. #235

.editorconfig

@@ -0,0 +1,10 @@
+root = true
+
+[*]
+end_of_line = lf
+insert_final_newline = true
+charset = utf-8
+
+[*.kt]
+indent_style = space
+indent_size = 2

.github/CONTRIBUTORS.md

@@ -42,6 +42,8 @@ Project contributors listed chronologically.
   * Prepared several KTX template projects and showcases.
   * Improved [app](../app) utilities.
 * [@Quillraven](https://github.com/Quillraven)
+  * Author of the [Tiled](../tiled) module.
+  * Contributed [actors](../actors) utilities.
   * Wrote a complete [KTX tutorial](https://github.com/Quillraven/SimpleKtxGame/wiki) based on the original LibGDX introduction.
 * [@FocusPo1nt](https://github.com/FocusPo1nt)
   * Added utilities to [style module](../style).
@@ -52,7 +54,8 @@ Project contributors listed chronologically.
 * [@kvonspiczak](https://github.com/kvonspiczak)
   * Contributed documentation fix.
 * [@cypherdare](https://github.com/cypherdare)
-  * Contributed to numerous utilities in [actors](../actors), [collections](../collections) and [graphics](../graphics) modules.
+  * Contributed to numerous utilities in [actors](../actors), [collections](../collections), [graphics](../graphics)
+  and [math](../math) modules.
   * Added `AssetGroup` API to [assets](../assets).
 * [@jakewilson](https://github.com/jakewilson)
   * Added utilities to [graphics module](../graphics).

CHANGELOG.md

@@ -1,3 +1,23 @@
+#### 1.9.10-b4
+
+- **[FEATURE]** (`ktx-actors`) Added `onTouchDown`, `onTouchUp` and `onTouchEvent` extension methods that allow to attach `ClickListener` instances to actors.
+- **[CHANGE]** (`ktx-collections`) `Array.removeAll` and `retainAll` now return a boolean if any elements were removed.
+- **[CHANGE]** (`ktx-collections`) `Array.transfer` is now less strict about typing.
+- **[FEATURE]** (`ktx-math`) Added Kotlin ranges extensions that simplify creating ranges and rolling random numbers:
+    - `Int.amid`, `Float.amid`;
+    - `+`, `-`, `*` and `/` for ranges;
+    - `ClosedRange<Float>.random`, `IntRange.random`;
+    - `ClosedRange<Float>.randomGaussian`;
+    - `ClosedRange<Float>.randomTriangular`.
+- **[FEATURE]** (`ktx-tiled`) Added a new KTX module: Tiled API extensions.
+  - Added `contains` (`in`) and `set` (`[]`) operators support to `MapProperties`.
+  - Added extension methods that simplify properties extraction from `MapLayer`, `MapObject`, `TiledMap`, `TiledMapTile` and `TiledMapTileSet`:
+    - `property`
+    - `propertyOrNull`
+    - `containsProperty`
+  - Added `shape` extension field to `MapObject`.
+  - Added extension fields that ease extraction of basic properties from `TiledMap` and `MapObject`.
+
 #### 1.9.10-b3
 
 - **[UPDATE]** Updated to Kotlin 1.3.61.

README.md

@@ -49,6 +49,7 @@ Module | Dependency name | Description
 [math](math) | `ktx-math` | Operator functions for LibGDX math API and general math utilities.
 [scene2d](scene2d) | `ktx-scene2d` | Type-safe Kotlin builders for [`Scene2D`](https://github.com/libgdx/libgdx/wiki/Scene2d) GUI.
 [style](style) | `ktx-style` | Type-safe Kotlin builders for `Scene2D` widget styles extending `Skin` API.
+[tiled](tiled) | `ktx-tiled` | Utilities for [Tiled](https://www.mapeditor.org/) maps.
 [vis](vis) | `ktx-vis` | Type-safe Kotlin builders for [`VisUI`](https://github.com/kotcrab/vis-ui/). An _alternative_ to the [scene2d](scene2d) module.
 [vis-style](vis-style) | `ktx-vis-style` | Type-safe Kotlin builders for `VisUI` widget styles. An _extension_ of [style](style) module.
 
@@ -79,9 +80,9 @@ dependencies {
 }
 ```
 
-Note that defining `ktxVersion` is not necessary, as versions can be defined directly in the `dependencies` section.
-However, extracting the dependencies versions is a good practice, especially if they can be reused throughout the
-build files. This will speed up updating of your project if you include multiple KTX modules.
+Note that defining `ktxVersion` as a property is not necessary, as versions can be set directly in the `dependencies`
+section. However, extracting the dependencies versions is a good practice, especially if they can be reused throughout
+the build files. This will speed up updating of your project if you include multiple KTX modules.
 
 **KTX** modules should generally be added to the dependencies of the shared `core` module of your LibGDX application.
 
@@ -147,7 +148,7 @@ directly.
 
 ### Links
 
-[KTX wiki](https://github.com/libktx/ktx/wiki) lists some useful resources that can help you get started.
+[**KTX** wiki](https://github.com/libktx/ktx/wiki) lists some useful resources that can help you get started.
 
 Note that most official guides and examples in this repository assume that the reader is at least a bit familiar with
 the LibGDX API. If you are just getting to know the framework, it might be helpful to go through

actors/README.md

@@ -27,14 +27,15 @@ a `Group` with `actor in group` syntax.
 
 - Lambda-compatible `Actor.onChange` method was added. Allows to listen to `ChangeEvents`.
 - Lambda-compatible `Actor.onClick` method was added. Attaches `ClickListeners`.
+- Lambda-compatible `Actor.onTouchDown` and `Actor.onTouchUp` methods were 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
+- `onChangeEvent`, `onClickEvent`, `onTouchEvent`, `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
@@ -131,6 +132,38 @@ 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)!")
 }
+
+button.onTouchDown {
+  println("Button down!")
+}
+
+button.onTouchUp {
+  println("Button up!")
+}
+
+button.onTouchEvent(
+  // If you need access to the original InputEvent, use this expanded method variant.
+  downListener = { inputEvent, actor -> println("$actor down by $inputEvent!") },
+  upListener = { inputEvent, actor -> println("$actor up by $inputEvent!") }
+)
+// or with a single lambda. In this case you can use InputEvent.Type to distinguish between touchDown and touchUp
+button.onTouchEvent( { inputEvent, actor -> println("$actor ${inputEvent.type} by $inputEvent!") })
+
+button.onTouchEvent(
+  // If you need access to the local actor coordinates, use this expanded method variant.
+  downListener = { inputEvent, actor, x, y -> println("$actor down by $inputEvent at ($x, $y)!") },
+  upListener = { inputEvent, actor, x, y -> println("$actor up by $inputEvent at ($x, $y)!")}
+)
+// or again as single lambda
+button.onTouchEvent( { inputEvent, actor -> println("$actor ${inputEvent.type} by $inputEvent at ($x, $y)!") })
+
+button.onTouchEvent(
+  // If you need access to the pointer and mouse button, use this expanded method variant.
+  downListener = { inputEvent, actor, x, y, pointer, mouseButton -> println("$actor down by $inputEvent at ($x, $y) with pointer $pointer and mouseButton $mouseButton!") },
+  upListener = { inputEvent, actor, x, y, pointer, mouseButton -> println("$actor up by $inputEvent at ($x, $y) with pointer $pointer and mouseButton $mouseButton!")}
+)
+// or again as single lambda
+button.onTouchEvent( { inputEvent, actor -> println("$actor ${inputEvent.type} by $inputEvent at ($x, $y) with pointer $pointer and mouseButton $mouseButton!") })
 ```
 
 Adding an `EventListener` which consumes typed characters:

actors/src/main/kotlin/ktx/actors/events.kt

@@ -80,6 +80,179 @@ inline fun <Widget : Actor> Widget.onClickEvent(
   return clickListener
 }
 
+/**
+ * Attaches a [ClickListener] to this actor.
+ * @param listener invoked each time this actor is touched.
+ * @return [ClickListener] instance.
+ */
+inline fun Actor.onTouchDown(crossinline listener: () -> Unit): ClickListener {
+  val clickListener = object : ClickListener() {
+    override fun touchDown(event: InputEvent, x: Float, y: Float, pointer: Int, button: Int): Boolean {
+      listener()
+      return true
+    }
+  }
+  this.addListener(clickListener)
+  return clickListener
+}
+
+/**
+ * Attaches a [ClickListener] to this actor.
+ * @param listener invoked each time the touch of the actor is released.
+ * @return [ClickListener] instance.
+ */
+inline fun Actor.onTouchUp(crossinline listener: () -> Unit): ClickListener {
+  val clickListener = object : ClickListener() {
+    override fun touchUp(event: InputEvent, x: Float, y: Float, pointer: Int, button: Int) = listener()
+  }
+  this.addListener(clickListener)
+  return clickListener
+}
+
+/**
+ * Attaches a [ClickListener] to this actor.
+ * @param downListener invoked each time this actor is touched. Consumes the triggered [InputEvent] and the [Actor] that
+ * the listener was originally attached to. Refer to [ClickListener.touchDown] for parameter details.
+ * @param upListener invoked each time the touch of the actor is released. Consumes the triggered [InputEvent] and the [Actor] that
+ * the listener was originally attached to. Refer to [ClickListener.touchUp] for parameter details.
+ * @return [ClickListener] instance.
+ */
+inline fun <Widget : Actor> Widget.onTouchEvent(
+  crossinline downListener: (event: InputEvent, actor: Widget) -> Unit,
+  crossinline upListener: (event: InputEvent, actor: Widget) -> Unit
+): ClickListener {
+  val clickListener = object : ClickListener() {
+    override fun touchDown(event: InputEvent, x: Float, y: Float, pointer: Int, button: Int): Boolean {
+      downListener(event, this@onTouchEvent)
+      return true
+    }
+
+    override fun touchUp(event: InputEvent, x: Float, y: Float, pointer: Int, button: Int) =
+      upListener(event, this@onTouchEvent)
+  }
+  this.addListener(clickListener)
+  return clickListener
+}
+
+/**
+ * Attaches a [ClickListener] to this actor. Retrieve the [InputEvent.type] to distinguish between [touchDown][InputEvent.Type.touchDown]
+ * and [touchUp][InputEvent.Type.touchUp] events.
+ * @param listener invoked each time this actor is touched or the touch is released. Consumes the triggered [InputEvent] and the [Actor] that
+ * the listener was originally attached to. Refer to [ClickListener.touchDown] and [ClickListener.touchUp] for parameter details.
+ * @return [ClickListener] instance.
+ */
+inline fun <Widget : Actor> Widget.onTouchEvent(
+  crossinline listener: (event: InputEvent, actor: Widget) -> Unit
+): ClickListener {
+  val clickListener = object : ClickListener() {
+    override fun touchDown(event: InputEvent, x: Float, y: Float, pointer: Int, button: Int): Boolean {
+      listener(event, this@onTouchEvent)
+      return true
+    }
+
+    override fun touchUp(event: InputEvent, x: Float, y: Float, pointer: Int, button: Int) =
+      listener(event, this@onTouchEvent)
+  }
+  this.addListener(clickListener)
+  return clickListener
+}
+
+/**
+ * Attaches a [ClickListener] to this actor.
+ * @param downListener invoked each time this actor is touched. Consumes the triggered [InputEvent] and the [Actor] that
+ * the listener was originally attached to. Refer to [ClickListener.touchDown] for parameter details.
+ * @param upListener invoked each time the touch of the actor is released. Consumes the triggered [InputEvent] and the [Actor] that
+ * the listener was originally attached to. Refer to [ClickListener.touchUp] for parameter details.
+ * @return [ClickListener] instance.
+ */
+inline fun <Widget : Actor> Widget.onTouchEvent(
+  crossinline downListener: (event: InputEvent, actor: Widget, x: Float, y: Float) -> Unit,
+  crossinline upListener: (event: InputEvent, actor: Widget, x: Float, y: Float) -> Unit
+): ClickListener {
+  val clickListener = object : ClickListener() {
+    override fun touchDown(event: InputEvent, x: Float, y: Float, pointer: Int, button: Int): Boolean {
+      downListener(event, this@onTouchEvent, x, y)
+      return true
+    }
+
+    override fun touchUp(event: InputEvent, x: Float, y: Float, pointer: Int, button: Int) =
+      upListener(event, this@onTouchEvent, x, y)
+  }
+  this.addListener(clickListener)
+  return clickListener
+}
+
+/**
+ * Attaches a [ClickListener] to this actor. Retrieve the [InputEvent.type] to distinguish between [touchDown][InputEvent.Type.touchDown]
+ * and [touchUp][InputEvent.Type.touchUp] events.
+ * @param listener invoked each time this actor is touched or the touch is released. Consumes the triggered [InputEvent] and the [Actor] that
+ * the listener was originally attached to. Refer to [ClickListener.touchDown] and [ClickListener.touchUp] for parameter details.
+ * @return [ClickListener] instance.
+ */
+inline fun <Widget : Actor> Widget.onTouchEvent(
+  crossinline listener: (event: InputEvent, actor: Widget, x: Float, y: Float) -> Unit
+): ClickListener {
+  val clickListener = object : ClickListener() {
+    override fun touchDown(event: InputEvent, x: Float, y: Float, pointer: Int, button: Int): Boolean {
+      listener(event, this@onTouchEvent, x, y)
+      return true
+    }
+
+    override fun touchUp(event: InputEvent, x: Float, y: Float, pointer: Int, button: Int) =
+      listener(event, this@onTouchEvent, x, y)
+  }
+  this.addListener(clickListener)
+  return clickListener
+}
+
+/**
+ * Attaches a [ClickListener] to this actor.
+ * @param downListener invoked each time this actor is touched. Consumes the triggered [InputEvent] and the [Actor] that
+ * the listener was originally attached to. Refer to [ClickListener.touchDown] for parameter details.
+ * @param upListener invoked each time the touch of the actor is released. Consumes the triggered [InputEvent] and the [Actor] that
+ * the listener was originally attached to. Refer to [ClickListener.touchUp] for parameter details.
+ * @return [ClickListener] instance.
+ */
+inline fun <Widget : Actor> Widget.onTouchEvent(
+  crossinline downListener: (event: InputEvent, actor: Widget, x: Float, y: Float, pointer: Int, button: Int) -> Unit,
+  crossinline upListener: (event: InputEvent, actor: Widget, x: Float, y: Float, pointer: Int, button: Int) -> Unit
+): ClickListener {
+  val clickListener = object : ClickListener() {
+    override fun touchDown(event: InputEvent, x: Float, y: Float, pointer: Int, button: Int): Boolean {
+      downListener(event, this@onTouchEvent, x, y, pointer, button)
+      return true
+    }
+
+    override fun touchUp(event: InputEvent, x: Float, y: Float, pointer: Int, button: Int) =
+      upListener(event, this@onTouchEvent, x, y, pointer, button)
+  }
+  this.addListener(clickListener)
+  return clickListener
+}
+
+/**
+ * Attaches a [ClickListener] to this actor. Retrieve the [InputEvent.type] to distinguish between [touchDown][InputEvent.Type.touchDown]
+ * and [touchUp][InputEvent.Type.touchUp] events.
+ * @param listener invoked each time this actor is touched or the touch is released. Consumes the triggered [InputEvent] and the [Actor] that
+ * the listener was originally attached to. Refer to [ClickListener.touchDown] and [ClickListener.touchUp] for parameter details.
+ * @return [ClickListener] instance.
+ */
+inline fun <Widget : Actor> Widget.onTouchEvent(
+  crossinline listener: (event: InputEvent, actor: Widget, x: Float, y: Float, pointer: Int, button: Int) -> Unit
+): ClickListener {
+  val clickListener = object : ClickListener() {
+    override fun touchDown(event: InputEvent, x: Float, y: Float, pointer: Int, button: Int): Boolean {
+      listener(event, this@onTouchEvent, x, y, pointer, button)
+      return true
+    }
+
+    override fun touchUp(event: InputEvent, x: Float, y: Float, pointer: Int, button: Int) =
+      listener(event, this@onTouchEvent, x, y, pointer, button)
+  }
+  this.addListener(clickListener)
+  return clickListener
+}
+
 /**
  * Attaches an [EventListener] optimized to listen for key type events fired for this actor.
  * @param catchEvent if true, the event will not be passed further after it is handled by this listener. Defaults to false.