Custom DSL functions

[Divelix]

Hi, I'm not pro in Kotlin yet and can't figure out how to add my custom functions to libktx DSL (in my project) to make code more readable and consistent. For instance, I have two similar builders for windows (for win and for defeat cases) and to avoid duplication I try to do this:

fun endWindow(title: String, content: () -> Unit): VisWindow {
        return window(title) {
            centerWindow()
            padTop(50f) // title height
            defaults().top()
            width = 320f
            height = 500f
            row()
            content()
            row()
            label("end of endWindow")
        }
    }

    fun winWindow(): VisWindow {
        return endWindow("Victory!") {
            label("You won!")
        }
    }

    fun loseWindow(): VisWindow {
        return endWindow("gameOver!") {
            label("You lost!")
        }
    }

But this code doesn't work and I feel like I'm using lambda as last parameter in endWindow incorrectly, but can't figure out how to fix it, please, help.

And moreover it would be cool to use my custom functions like endWindow as fancy libktx DSL:

endWindow("Win!") {
    table {
        // stats and score here
    }
}

But as for now, I can do just old fashioned stuff like that:

fun endWindow(title: String): VisWindow {
    return window(title) {
        table {
           // stats and score here
        }
    }
}
// And add this it in init
stage.add(endWindow("Win!))

[czyzby]

You have to add the window to the lambda signature, so it becomes this, exposing all DSL methods:

fun endWindow(title: String, content: KVisWindow.() -> Unit): VisWindow

We're using a KVisWindow instead of VisWindow for the lambda, as it has access to the DSL.

Also, you're not using an updated version of ktx-vis. There were some notable API changes and performance improvements, so I encourage you to try it out. Updated code that compiles:

import com.kotcrab.vis.ui.widget.VisWindow
import ktx.scene2d.scene2d
import ktx.scene2d.vis.KVisWindow
import ktx.scene2d.vis.visLabel
import ktx.scene2d.vis.visWindow

fun endWindow(title: String, content: KVisWindow.() -> Unit): VisWindow {
  return scene2d.visWindow(title) {
    centerWindow()
    padTop(50f) // title height
    defaults().top()
    width = 320f
    height = 500f
    row()
    content()
    row()
    visLabel("end of endWindow")
  }
}

fun winWindow(): VisWindow {
  return endWindow("Victory!") {
    visLabel("You won!")
  }
}

fun loseWindow(): VisWindow {
  return endWindow("gameOver!") {
    visLabel("You lost!")
  }
}

[Divelix]

Thank you! Now my code should become more readable. I just updated to 1.9.10-b6 which broke most of my code (already fixed it) and I see you used experimental contracts everywhere - won't it break everything if they change it's syntax? And also, is there any way to call VisTable instead of scene2d.VisTable?

[czyzby]

I see you used experimental contracts everywhere - won't it break everything if they change it's syntax?

Contracts API is already pretty stable, and we're only using the most common functionalities. I would consider waiting for Kotlin 1.4 if contacts were promoted to a stable feature in this release, but it seems that they won't just yet. Given their obvious benefits for DSLs, I think it's worth risking the future incompatibilities for today's convenience.

And also, is there any way to call VisTable instead of scene2d.VisTable?

The scene2d. prefix is deliberate, as we needed to differentiate between top-level actors and their nested children. Before, most actors (e.g. table, window and so on) had 2 separate factory methods, which made code completion worse, as you could accidentally use the top level factory method instead of the correct one.

You can omit scene2d. if you use stage.actors { } extension - this will automatically add the defined actors to the stage. For example:

stage.actors {
  window("Title") {
    label("This window will be added to the stage!")
  }
}

You can also use built-in Kotlin utilities like with or apply:

fun differentWaysToBuildALabel() {
  val label1 = scene2d { 
    label("1")
  }
  
  val label2: Label
  with(scene2d) {
    label2 = label("2")
  }
  
  val label3: Label
  scene2d.apply { 
    label3 = label("3")
  }
}

Check out the README files for more info. ktx-scene2d and ktx-vis guides are both up-to-date and contain migration guides for b6 version.