KTX 1.10.0-rc1 release. #407

.github/CONTRIBUTING.md

@@ -40,6 +40,12 @@ please check the  `README.md` file of the module, and add description of your ch
 should include a usage example in the module guide. Make sure to add all the necessary imports in the usage examples
 in `README.md` files to make it easier to try them out.
 
+## Donations
+
+<a href="https://opencollective.com/ktx">
+  <img alt="Contribute on OpenCollective" src="https://opencollective.com/ktx/tiers/supporter.svg?avatarHeight=60&width=600" />
+</a>
+
 ## Working from sources
 
 ```bash
@@ -115,6 +121,8 @@ should generally consist of the following sections:
   - README.md
 ```
 
+- Include the module in the listing in the main [`README.md`](../README.md) file.
+
 ## Maintenance
 
 The following sections are for the maintainers of the repository.

.github/CONTRIBUTORS.md

@@ -89,6 +89,10 @@ Project contributors listed chronologically.
   * Contributed an initial implementation of reflection-based component binding for the [inject module](../inject).
 * [@fejd](https://github.com/fejd)
   * Contributed utilities to the [collections module](../collections).
+* [@manabreak](https://github.com/manabreak)
+  * Contributed utilities to the [actors module](../actors).
+* [@crykn](https://github.com/crykn)
+  * Updated links to the new libGDX wiki.
 
 ### Metrics
 

.github/FUNDING.yml

@@ -0,0 +1,11 @@
+github: [czyzby]
+# patreon: # Replace with a single Patreon username
+open_collective: ktx
+# ko_fi: # Replace with a single Ko-fi username
+# tidelift: # Replace with a single Tidelift platform-name/package-name e.g., npm/babel
+# community_bridge: # Replace with a single Community Bridge project-name e.g., cloud-foundry
+# liberapay: # Replace with a single Liberapay username
+# issuehunt: # Replace with a single IssueHunt username
+# otechie: # Replace with a single Otechie username
+# lfx_crowdfunding: # Replace with a single LFX Crowdfunding project-name e.g., cloud-foundry
+# custom: # Replace with up to 4 custom sponsorship URLs e.g., ['link1', 'link2']

CHANGELOG.md

@@ -1,5 +1,27 @@
 _See also: [the official libGDX changelog](https://github.com/libgdx/libgdx/blob/master/CHANGES)._
 
+#### 1.10.0-rc1
+
+- **[UPDATE]** Updated to Kotlin 1.6.10.
+- **[UPDATE]** Updated to Kotlin Coroutines 1.6.0.
+- **[MISC]** Links to the libGDX wiki were updated.
+- **[MISC]** Stable **KTX** releases are now marked with the `-rc` suffix.
+- **[CHANGE]** (`ktx-scene2d`) The generic `Node` type of `KTreeWidget` was changed to `KNode<*>`.
+- **[FEATURE]** Added `Tree.onSelectionChange` extension method that attaches a `ChangeListener` to a `Tree`.
+- **[FEATURE]** (`ktx-script`) Added a new module with `KotlinScriptEngine` evaluating Kotlin scripts in runtime.
+  - `evaluate(String)`: compiles and executes a script passed as a string.
+  - `evaluate(FileHandle)`: compiles and executes a script from the selected file.
+  - `evaluateAs<T>(String)`: compiles and executes a script passed as a string. Casts the result to `T`.
+  - `evaluateAs<T>(FileHandle)`: compiles and executes a script from the selected file. Casts the result to `T`.
+  - `set(String, Any)`: adds a variable to the script execution context.
+  - `get(String)`: returns the current value assigned to the selected variable.
+  - `remove(String)`: removes the variable registered under the given name.
+  - `import(String, String?)`: adds an import to the script context. Accepts optional alias.
+  - `importAll(vararg String)`, `importAll(Iterable<String>)`: adds the selected imports to the script context.
+  - `setPackage(String)`: sets the package for the scripts.
+  - `onItemClick(Node)`: adds a listener that gets invoked when `Node` in a `Tree` gets clicked.
+- **[CHANGE]** (`ktx-vis`) The generic `Node` type of `KVisTree` was changed to `KNode<*>`.
+
 #### 1.10.0-b4
 
 - **[UPDATE]** Updated to Gradle 7.2.

README.md

@@ -1,5 +1,5 @@
 [![GitHub Build](https://github.com/libktx/ktx/workflows/build/badge.svg)](https://github.com/libktx/ktx/actions?query=workflow%3Abuild)
-[![Kotlin](https://img.shields.io/badge/kotlin-1.5.31-orange.svg)](http://kotlinlang.org/)
+[![Kotlin](https://img.shields.io/badge/kotlin-1.6.10-orange.svg)](http://kotlinlang.org/)
 [![libGDX](https://img.shields.io/badge/libgdx-1.10.0-red.svg)](https://libgdx.com/)
 [![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)
 
@@ -15,15 +15,15 @@ utilities and extensions for selected parts of libGDX with poor Kotlin support.
 
 Examples of Kotlin language features used to improve usability, performance, and readability of libGDX include:
 
-* *Operator overloads* for collections and mathematical operations.
-* *Extension methods* improving original libGDX APIs without the use of inheritance.
-* *Inline methods* with reduced runtime overhead for various listeners, builders, and loggers.
-* *Nullable types* which improve typing information of selected interfaces and functions.
-* *Default parameters* reducing boilerplate code.
-* *Type-safe builders* for GUI, styling, and physics engine.
-* *Default interface methods* for common interfaces, simplifying their implementations.
-* *Coroutines context* providing concurrency utilities and non-blocking asset loading.
-* *Reified types* that simplify usage of methods normally consuming `Class` parameters.
+- *Operator overloads* for collections and mathematical operations.
+- *Extension methods* improving original libGDX APIs without the use of inheritance.
+- *Inline methods* with reduced runtime overhead for various listeners, builders, and loggers.
+- *Nullable types* which improve typing information of selected interfaces and functions.
+- *Default parameters* reducing boilerplate code.
+- *Type-safe builders* for GUI, styling, and physics engine.
+- *Default interface methods* for common interfaces, simplifying their implementations.
+- *Coroutines context* providing concurrency utilities and non-blocking asset loading.
+- *Reified types* that simplify usage of methods normally consuming `Class` parameters.
 
 See the [_Choosing **KTX**_](https://github.com/libktx/ktx/wiki/Choosing-KTX) article for pros and cons of this framework.
 
@@ -34,25 +34,26 @@ You can include selected **KTX** modules based on the needs of your application.
 
 Module | Description
 :---: | ---
-[`ktx-actors`](actors) | [`Scene2D`](https://github.com/libgdx/libgdx/wiki/Scene2d) GUI extensions for stages, actors, actions, and event listeners.
+[`ktx-actors`](actors) | [`Scene2D`](https://libgdx.com/wiki/graphics/2d/scene2d/scene2d) GUI extensions for stages, actors, actions, and event listeners.
 [`ktx-app`](app) | `ApplicationListener` implementations and general application utilities.
 [`ktx-ashley`](ashley) | [`Ashley`](https://github.com/libgdx/ashley) entity-component-system utilities.
 [`ktx-assets`](assets) | Resources management utilities.
 [`ktx-assets-async`](assets-async) | Non-blocking asset loading using coroutines.
 [`ktx-async`](async) | [Coroutines](https://kotlinlang.org/docs/reference/coroutines.html) context based on libGDX threading model.
-[`ktx-box2d`](box2d) | [`Box2D`](https://github.com/libgdx/libgdx/wiki/Box2d) physics engine utilities.
+[`ktx-box2d`](box2d) | [`Box2D`](https://libgdx.com/wiki/extensions/physics/box2d) physics engine utilities.
 [`ktx-collections`](collections) | Extensions for libGDX custom collections.
 [`ktx-freetype`](freetype) | `FreeType` fonts loading utilities.
 [`ktx-freetype-async`](freetype-async) | Non-blocking `FreeType` fonts loading using coroutines.
 [`ktx-graphics`](graphics) | Utilities related to rendering tools and graphics.
 [`ktx-i18n`](i18n) | Internationalization API utilities.
 [`ktx-inject`](inject) | A dependency injection system with low overhead and no reflection usage.
-[`ktx-json`](json) | Utilities for libGDX [JSON](https://github.com/libgdx/libgdx/wiki/Reading-and-writing-JSON) serialization API.
+[`ktx-json`](json) | Utilities for libGDX [JSON](https://libgdx.com/wiki/utils/reading-and-writing-json) serialization API.
 [`ktx-log`](log) | Minimal runtime overhead cross-platform logging using inlined functions.
 [`ktx-math`](math) | Operator functions for libGDX math API and general math utilities.
-[`ktx-preferences`](preferences) | Improved API for accessing and saving [preferences](https://github.com/libgdx/libgdx/wiki/Preferences).
-[`ktx-reflect`](reflect) | Utilities for libGDX [reflection API](https://github.com/libgdx/libgdx/wiki/Reflection).
-[`ktx-scene2d`](scene2d) | Type-safe Kotlin builders for [`Scene2D`](https://github.com/libgdx/libgdx/wiki/Scene2d) GUI.
+[`ktx-preferences`](preferences) | Improved API for accessing and saving [preferences](https://libgdx.com/wiki/preferences).
+[`ktx-reflect`](reflect) | Utilities for libGDX [reflection API](https://libgdx.com/wiki/utils/reflection).
+[`ktx-scene2d`](scene2d) | Type-safe Kotlin builders for [`Scene2D`](https://libgdx.com/wiki/graphics/2d/scene2d/scene2d) GUI.
+[`ktx-script`](script) | Kotlin scripting engine for desktop applications.
 [`ktx-style`](style) | Type-safe Kotlin builders for `Scene2D` widget styles extending `Skin` API.
 [`ktx-tiled`](tiled) | Utilities for [Tiled](https://www.mapeditor.org/) maps.
 [`ktx-vis`](vis) | Type-safe Kotlin builders for [`VisUI`](https://github.com/kotcrab/vis-ui/).
@@ -78,7 +79,7 @@ in your `build.gradle` file:
 // Groovy DSL:
 ext {
   // Update this version to match the latest KTX release:
-  ktxVersion = '1.10.0-b4'
+  ktxVersion = '1.10.0-rc1'
 }
 
 dependencies {
@@ -90,7 +91,7 @@ dependencies {
 // Kotlin DSL:
 
 // Update this version to match the latest KTX release:
-val ktxVersion = "1.10.0-b4"
+val ktxVersion = "1.10.0-rc1"
 
 dependencies {
   api(group = "io.github.libktx", name = "ktx-app", version = ktxVersion)
@@ -110,8 +111,8 @@ reused throughout the build files. This will speed up updating of your project i
 #### Versioning
 
 **KTX** versions match the libGDX versions that they were compiled against. `$ktxVersion` will usually match your libGDX
-version, but it might end with `-b` postfix if it is a beta release, or `-SNAPSHOT` if you are using the development
-branch.
+version, but it might end with `-rc` suffix if it is a stable release, or `-SNAPSHOT` if you are using the development
+branch. Older **KTX** releases use the `-b` suffix to mark milestone releases.
 
 You can browse through our official releases [on Maven](https://search.maven.org/#search%7Cga%7C1%7Cg%3A%22io.github.libktx%22)
 and [on GitHub](https://github.com/libktx/ktx/releases).
@@ -177,7 +178,7 @@ Browse through the directories in the root folder to find out more about each li
 All functionalities are documented with Kotlin _KDocs_. You can access the source documentation by:
 
 - Viewing the generated Dokka files hosted on the [project website](https://libktx.github.io/docs/).
-- Extracting the `doc` folders with Dokka files from [release archives](https://github.com/libktx/ktx/releases).
+- Extracting the `doc` folders with Dokka files from the [release archives](https://github.com/libktx/ktx/releases).
 - Reading the sources directly.
 
 ### Links
@@ -186,7 +187,7 @@ All functionalities are documented with Kotlin _KDocs_. You can access the sourc
 
 Most official guides and code 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
-[the official libGDX wiki](https://github.com/libgdx/libgdx/wiki), and convert some Java examples to Kotlin.
+[the official libGDX wiki](https://libgdx.com/wiki/), and convert some Java examples to Kotlin.
 
 ## [Contribution](.github/CONTRIBUTING.md)
 

actors/README.md

@@ -42,6 +42,8 @@ and `onKeyboardFocusEvent` `Actor` extension methods were added. They consume th
 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.
+- Lambda-compatible `Tree.onSelectionChange` method was added. Attaches a listener invoked each time a `Tree`'s node
+selection is modified.
 
 #### Actions
 
@@ -312,4 +314,4 @@ HTML-inspired syntax.
 
 #### Additional documentation
 
-- [Scene2D UI article.](https://github.com/libgdx/libgdx/wiki/Scene2d.ui)
+- [Scene2D UI article.](https://libgdx.com/wiki/graphics/2d/scene2d/scene2d-ui)

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

@@ -7,12 +7,14 @@ import com.badlogic.gdx.scenes.scene2d.InputEvent.Type.keyDown
 import com.badlogic.gdx.scenes.scene2d.InputEvent.Type.keyTyped
 import com.badlogic.gdx.scenes.scene2d.InputEvent.Type.keyUp
 import com.badlogic.gdx.scenes.scene2d.InputListener
+import com.badlogic.gdx.scenes.scene2d.ui.Tree
 import com.badlogic.gdx.scenes.scene2d.utils.ChangeListener
 import com.badlogic.gdx.scenes.scene2d.utils.ChangeListener.ChangeEvent
 import com.badlogic.gdx.scenes.scene2d.utils.ClickListener
 import com.badlogic.gdx.scenes.scene2d.utils.FocusListener.FocusEvent
 import com.badlogic.gdx.scenes.scene2d.utils.FocusListener.FocusEvent.Type.keyboard
 import com.badlogic.gdx.scenes.scene2d.utils.FocusListener.FocusEvent.Type.scroll
+import com.badlogic.gdx.scenes.scene2d.utils.Selection
 
 /**
  * Attaches a [ChangeListener] to this actor.
@@ -88,6 +90,25 @@ inline fun <T : Actor> T.onClickEvent(
   return clickListener
 }
 
+/**
+ * Attaches a [ChangeListener] to this [Tree].
+ * @param listener invoked each time the node [Selection] is changed. Receives the [Selection] object
+ * which can be used to obtain all selected items with [Selection.items] or the latest selected item
+ * with [Selection.getLastSelected].
+ * @return [ChangeListener] instance.
+ */
+inline fun <N : Tree.Node<N, *, *>> Tree<N, *>.onSelectionChange(
+  crossinline listener: ((Selection<N>) -> Unit)
+): ChangeListener {
+  val changeListener = object : ChangeListener() {
+    override fun changed(event: ChangeEvent, actor: Actor) {
+      listener(this@onSelectionChange.selection)
+    }
+  }
+  addListener(changeListener)
+  return changeListener
+}
+
 /**
  * Attaches an [InputListener] to this actor.
  * @param listener invoked each time this actor is touched. Consumes the [Actor] as `this`.

actors/src/test/kotlin/ktx/actors/EventsTest.kt

@@ -8,15 +8,19 @@ import com.badlogic.gdx.scenes.scene2d.InputEvent.Type.keyTyped
 import com.badlogic.gdx.scenes.scene2d.InputEvent.Type.keyUp
 import com.badlogic.gdx.scenes.scene2d.InputEvent.Type.touchDown
 import com.badlogic.gdx.scenes.scene2d.InputEvent.Type.touchUp
+import com.badlogic.gdx.scenes.scene2d.ui.Tree
 import com.badlogic.gdx.scenes.scene2d.utils.ChangeListener.ChangeEvent
 import com.badlogic.gdx.scenes.scene2d.utils.FocusListener.FocusEvent
 import com.badlogic.gdx.scenes.scene2d.utils.FocusListener.FocusEvent.Type.keyboard
 import com.badlogic.gdx.scenes.scene2d.utils.FocusListener.FocusEvent.Type.scroll
+import io.kotlintest.mock.mock
 import org.junit.Assert.assertEquals
 import org.junit.Assert.assertNotNull
 import org.junit.Assert.assertNull
+import org.junit.Assert.assertSame
 import org.junit.Assert.assertTrue
 import org.junit.Test
+import java.util.concurrent.atomic.AtomicInteger
 
 /**
  * Tests events and listeners utilities.
@@ -79,6 +83,48 @@ class EventsTest {
     assertTrue(listener in actor.listeners)
   }
 
+  class SampleNode : Tree.Node<SampleNode, Any, Actor>(mock())
+
+  @Test
+  fun `should attach ChangeListener to a Tree consuming Selection with the selected Nodes`() {
+    val style = mock<Tree.TreeStyle>()
+    style.plus = mock()
+    style.minus = mock()
+    val tree = Tree<SampleNode, Any>(style)
+
+    val listener = tree.onSelectionChange {}
+
+    assertNotNull(listener)
+    assertTrue(listener in tree.listeners)
+  }
+
+  @Test
+  fun `should invoke attached ChangeListener when tree Selection changes`() {
+    val style = mock<Tree.TreeStyle>()
+    style.plus = mock()
+    style.minus = mock()
+    val tree = Tree<SampleNode, Any>(style)
+    tree.selection.setProgrammaticChangeEvents(true)
+    val nodes = Array(3) { SampleNode() }
+    val selected = SampleNode()
+    nodes.forEach(tree::add)
+    tree.add(selected)
+    val executions = AtomicInteger()
+    val selectedNodes = mutableListOf<SampleNode>()
+    tree.selection.clear()
+    tree.onSelectionChange { selection ->
+      executions.incrementAndGet()
+      selectedNodes.clear()
+      selectedNodes.addAll(selection.items())
+    }
+
+    tree.selection.add(selected)
+
+    assertEquals(1, executions.get())
+    assertEquals(1, selectedNodes.size)
+    assertSame(selected, selectedNodes.first())
+  }
+
   @Test
   fun `should attach InputListener for touchDown`() {
     val actor = Actor()

app/README.md

@@ -80,7 +80,7 @@ class MyApplicationListener : KtxApplicationAdapter {
 }
 ```
 
-Implementing `KtxGame` with one screen that displays text with `Batch` utilities from `ktx-graphics`: 
+Implementing `KtxGame` with one screen that displays text with `Batch` utilities from `ktx-graphics`:
 
 ```kotlin
 import com.badlogic.gdx.Screen
@@ -170,7 +170,7 @@ Executing platform-specific code:
 import ktx.app.Platform
 
 fun runOnPlatform() {
-  Platform.runOnMobile { 
+  Platform.runOnMobile {
     println("Will print only on mobile platforms!")
   }
 }
@@ -261,6 +261,6 @@ initiates and handles annotated view instances.
 
 #### Additional documentation
 
-- [Official life cycle article.](https://github.com/libgdx/libgdx/wiki/The-life-cycle)
-- [Official viewports article.](https://github.com/libgdx/libgdx/wiki/Viewports)
-- [Official article on profiling.](https://github.com/libgdx/libgdx/wiki/Profiling)
+- [Official life cycle article.](https://libgdx.com/wiki/app/the-life-cycle)
+- [Official viewports article.](https://libgdx.com/wiki/graphics/viewports)
+- [Official article on profiling.](https://libgdx.com/wiki/graphics/profiling)

assets-async/README.md

@@ -966,7 +966,7 @@ and fully compatible with coroutines. It offers superior performance and better
 should be used instead only as an intermediate step during migration from an `AssetManager` to the `AssetStorage`, or
 if an `AssetManager` is strictly required by an otherwise incompatible third-party API.
 
-`AsyncAssetManager` supports all features of the [`AssetManager`](https://github.com/libgdx/libgdx/wiki/Managing-your-assets).
+`AsyncAssetManager` supports all features of the [`AssetManager`](https://libgdx.com/wiki/managing-your-assets).
 The main difference is that `loadAsync` should be used over the standard `load` methods whenever you need a reference to
 the loaded asset or need full control over its error handling.
 
@@ -1130,7 +1130,7 @@ There seem to be no other coroutines-based asset loaders available.
 However, libGDX `AssetManager` is still viable when efficient parallel loading is not a requirement.
 Alternatives to the `AssetStorage` and `AsyncAssetManager` include:
 
-- Using [`AssetManager`](https://github.com/libgdx/libgdx/wiki/Managing-your-assets) directly.
+- Using [`AssetManager`](https://libgdx.com/wiki/managing-your-assets) directly.
 - Using [`ktx-assets`](../assets) extensions for `AssetManager`.
 - [`AnnotationAssetManager`](https://bitbucket.org/dermetfan/libgdx-utils/wiki/net.dermetfan.gdx.assets.AnnotationAssetManager)
 from [`libgdx-utils`](https://bitbucket.org/dermetfan/libgdx-utils) that extends `AssetManager` and allows
@@ -1140,4 +1140,4 @@ specifying assets for loading by marking fields with annotations.
 #### Additional documentation
 
 - [`ktx-async` module](../async), which is used extensively by this extension.
-- [Official libGDX `AssetManager` article.](https://github.com/libgdx/libgdx/wiki/Managing-your-assets)
+- [Official libGDX `AssetManager` article.](https://libgdx.com/wiki/managing-your-assets)