From 1798f2aea18d858ccccd7ef517ab6c34e9fa100f Mon Sep 17 00:00:00 2001 From: Leandro Di Lorenzo Date: Sun, 4 Aug 2019 23:47:55 -0300 Subject: [PATCH] Update README with components usage --- README.md | 389 ++++++++++++++++++++++++++++++++++++------- kotlin_extensions.md | 14 -- 2 files changed, 325 insertions(+), 78 deletions(-) delete mode 100644 kotlin_extensions.md diff --git a/README.md b/README.md index cb8f0a8..f253bf4 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,6 @@ # Kotlin Extensions for Arena Framework - ## Arena MVVM Framework * [Home Page](http://arena.uqbar-project.org) @@ -10,103 +9,365 @@ ## About this repository -In order to use Arena with Kotlin in a more pleasant way, -here are some extensions that can help. +This package allows you to use Arena with Kotlin in a more pleasant way. -## How to use +It provides some extensions that take advantage of Kotlin's functions, +as well as the possibility of [extending the classes](https://kotlinlang.org/docs/reference/extensions.html) +and [high order functions](https://kotlinlang.org/docs/reference/lambdas.html). + +## Dependency + +You need to add this code to your `pom.xml` -There are two ways to use Arena with this Kotlin package: **Extensions** and **Native Components**. +```xml + -### Extensions + + + jitpack.io + https://jitpack.io + + + uqbar + Uqbar + http://maven.uqbar.org/releases/ + + -Using Arena without kotlin extensions result in code like this: + + org.uqbar-project + arena-xtend-parent + 3.6.3 + + + + + + + com.github.unq-ui + arena-kotlin-extensions + 1.2.1 + + + + + +``` + +## How to use + +> **Important:** You always have to add this import: +> +> `import org.uqbar.arena.kotlin.extensions.*` + +### Quick Start ```kt +package examples.extensions.widgets.control + +import java.awt.Color +import org.uqbar.arena.widgets.* +import org.uqbar.arena.windows.MainWindow +import org.uqbar.arena.kotlin.extensions.* +import org.uqbar.commons.model.annotations.Observable + +fun main() = ExampleWindow(AppModel(42, Color.YELLOW)).startApplication() + +@Observable class AppModel(var number: Int, var bg: Color) + class ExampleWindow(model: AppModel) : MainWindow(model) { override fun createContents(mainPanel: Panel) { - title = "Example" - Label(mainPanel) - .setText("Soy un label") - .bindBackgroundToProperty("bg") - TextBox(mainPanel) - .bindValueToProperty("number") + title = "Example" + Label(mainPanel) with { + text = "Soy un label" + bindBackgroundTo("bg") + } + TextBox(mainPanel) with { + bindTo("number") + } } } ``` -Because sometimes Kotlin can't infer types of generics, so you need to write generics explicitly, -making code with a lot of verbosity. +### Components + +* Inputs + + [Text Boxes](#text-boxes) + + [Numeric Fields](#numeric-fields) + + [Password Fields](#password-fields) + + [Text Areas](#text-areas) + + [Spinners](#spinners) +* [Labels](#labels) +* Options + + [Selectors](#selectors) + + [Lists](#lists) + + [Radio Selectors](#radio-selectors) +* [Check Boxes](#check-boxes) +* Actions + + [Buttons](#buttons) + + [Links](#links) + + [File Selectors](#file-selectors) +* [Tables](#tables) +* Trees (**TODO**) +* Types of Panels + + [Panels](#panels) + + [Group Panels](#group-panels) + +#### Inputs -With extensions you can create components in a less verbose way: +##### Text Boxes ```kt -import org.uqbar.arena.kotlin.extensions.* +TextBox(mainPanel) with { + height = 20 + width = 45 + bindTo("textBoxText") + bindColorTo("blue") + bindEnabledTo("enabled") + withFilter { it.inputText.toString().contains("a") } +} -class ExampleWindow(model: AppModel) : MainWindow(model) { - override fun createContents(mainPanel: Panel) { - title = "Example" - Label(mainPanel) - .setText("Soy un label") - .bindBackgroundTo("bg") - TextBox(mainPanel).bindTo("number") - } +TextBox(mainPanel) with { + fontSize = 24 + align = "center" // right, left, center + color = Color.YELLOW + bgColor = Color.BLUE + bindTo("textBoxText") } ``` -In addition, as Kotlin allows to create -[infix functions](https://kotlinlang.org/docs/reference/functions.html#infix-notation), -you can rewrite that code as follow: +##### Numeric Fields ```kt -import org.uqbar.arena.kotlin.extensions.* +NumericField(mainPanel) with { + height = 20 + width = 45 + bindTo("number") + bindColorTo("blue") + bindEnabledTo("enabled") + withDecimals = false +} -class ExampleWindow(model: AppModel) : MainWindow(model) { - override fun createContents(mainPanel: Panel) { - title = "Example" +NumericField(mainPanel) with { + fontSize = 20 + color = Color.WHITE + bgColor = Color.BLACK + withDecimals = true + bindTo("number") +} +``` - val label = Label(mainPanel).setText("Soy un label") - label bindBackgroundTo "bg" - - TextBox(mainPanel) bindTo "number" - } +##### Password Fields + +```kt +PasswordField(mainPanel) props { + bindTo("password") + fontSize = 20 } ``` -To know how to use all Kotlin extensions for Arena, go to [Kotlin Extensions Page](kotlin_extensions.md). +##### Text Areas -### Native Components +```kt +KeyWordTextArea(mainPanel) with { + height = 200 + bindTo("textBoxText") + bindColorTo("blue") + bindEnabledTo("enabled") +} +``` -To go a step further, we can wrap all components to get a better code syntax. +##### Spinners -Using [infix functions](https://kotlinlang.org/docs/reference/functions.html#infix-notation) -and -[high order functions](https://kotlinlang.org/docs/reference/lambdas.html) -we can create a [DSL](https://en.wikipedia.org/wiki/Domain-specific_language) -Syntax for Arena. +```kt +Spinner(mainPanel) with { + width = 50 + minValue = 2 + maxValue = 10 +} +``` -So now we can write this kind of code +#### Labels ```kt -import org.uqbar.arena.windows.MainWindow -import org.uqbar.arena.kotlin.widgets.Panel -import org.uqbar.arena.kotlin.widgets.Label -import org.uqbar.arena.kotlin.widgets.TextBox +Label(mainPanel) with { + text = "Ejemplo" + width = 400 + height = 200 + fontSize = 16 + align = "center" + color = Color.BLUE + bgColor = Color.CYAN +} -class ExampleWindow(model: AppModel) : MainWindow(model) { - override fun createContents(mainPanel: Panel) { - title = "Example" - - // We can use any of this alternatives - Label(mainPanel) { - text = "Soy un label" - width(200) - it bindBackgroundTo "bg" - content color Color.BLUE - } - - TextBox(mainPanel) bindTo "number" +Label(mainPanel) with { + bindTo("text") + bindColorTo("blue") + bindBackgroundTo("orange") + bindEnabledTo("enabled") + bindVisibleTo("visible") +} +``` + +#### Options + +##### Selectors + +```kt +Selector(mainPanel) with { + bindItemsTo("items").adaptWithProp("name") + bindColorTo("color") +} +``` + +##### Lists + +```kt +List(mainPanel) with { + bindItemsTo("items").adaptWithProp("name") + bindSelectedTo("itemSelected") + bindBackgroundTo("color") +} +``` + +##### Radio Selectors + +```kt +RadioSelector(mainPanel) with { + bindItemsTo("items") + bindSelectedTo("itemSelected") +} +``` + +#### Check Boxes + +```kt +CheckBox(it) with { + bindTo("selected") + bindEnabledTo("disabled") + bindBackgroundTo("color") +} +``` + +#### Actions + +##### Buttons + +```kt +Button(mainPanel) with { + caption = "Button 1 Blue" + color = Color.BLUE + fontSize = 14 + +Button(mainPanel) with { + text = "Click Me again" // text is an alias of caption + color = Color.RED + setAsDefault() +} + +Button(mainPanel) with { + bindCaptionTo("buttonName") + onClick { modelObject.inc() } +} +``` + +##### Links + +```kt +Link(mainPanel) with { + text = "Click Me!" + onClick { modelObject.inc() } +} + +Link(mainPanel) with { + caption = "No hago nada!" +} +``` + +##### File Selectors + +```kt +FileSelector(mainPanel) with { + title = "Title of the selection window" + caption = "Seleccionar archivo..." + path = "/home" // Path where selection window open by default + bindTo("storage") // Where file selected will be saved + extensions("*.txt", "*.png") // Extensions allowed +} + +FileSelector(mainPanel) props { + path = "/home" + setAsDefault() + bindTo("storage") + bindCaptionTo("caption") +} +``` + +#### Tables + +```kt +table(mainPanel) { + bindItemsTo("items") + bindSelectionTo("selected") + visibleRows = 5 + column { + title = "ID" + fixedSize = 30 + bindContentsTo("id") + bindBackgroundTo("blue") + } + column { + title = "Name" + weight = 50 + align("center") + bindContentsTo("name") + } + column { + title = "Description" + background = Color.BLACK + align("right") + bindContentsTo("description") + } +} +``` + +#### Types of Panels + +##### Panels + +```kt +Panel(mainPanel) with { + asVertical() + width = 250 + Label(it) with { + text = "Label V1-1" + width = 200 + height = 75 } + Label(it) with { text = "Label V1-2" } +} + +Panel(mainPanel) with { + asHorizontal() + Label(it) props { text = "Label H1-1" } + Label(it) props { text = "Label H1-2" } +} + +Panel(mainPanel) with { + asColumns(3) + Label(it) with { text = "Label C1-1" } + Label(it) with { text = "Label C1-2" } + Label(it) with { text = "Label C1-3" } } ``` -To see more examples go to [code of Label Examples](./src/main/java/examples/kotlin) +##### Group Panels + +```kt +GroupPanel(mainPanel) with { + title = "Group Panel" + asHorizontal() + Label(it) with { text = "Label H1-1" } + Label(it) with { text = "Label H1-2" } +} +``` diff --git a/kotlin_extensions.md b/kotlin_extensions.md deleted file mode 100644 index 2c7d092..0000000 --- a/kotlin_extensions.md +++ /dev/null @@ -1,14 +0,0 @@ -# Kotlin Extensions for Arena Framework - - * [Back to Home](README.md) - * [Native Components](kotlin_native.md) - -## Kotlin Extensions - -First at all if you want to use extensions you have to import: - -```kt -import org.uqbar.arena.kotlin.extensions.* -``` - - \ No newline at end of file