New table fragment (#185)

zircon.core/src/commonMain/kotlin/org/hexworks/zircon/api/Columns.kt

@@ -0,0 +1,74 @@
+package org.hexworks.zircon.api
+
+import org.hexworks.cobalt.databinding.api.binding.bindTransform
+import org.hexworks.cobalt.databinding.api.property.Property
+import org.hexworks.cobalt.databinding.api.value.ObservableValue
+import org.hexworks.zircon.api.component.Icon
+import org.hexworks.zircon.api.component.Label
+import org.hexworks.zircon.internal.fragment.impl.table.TableColumn
+
+/**
+ * This object provides different presets for [TableColumn]s.
+ */
+object Columns {
+
+    /**
+     * Creates a [TableColumn] that represents it's cell values with a [Label]. The text of the label
+     * is the toString() of the value provided by [valueAccessor].
+     *
+     * @param name the name of the column to be used as header
+     * @param width the width of the column
+     * @param valueAccessor returns the value to be used in each cell of the column. It should preferable be a
+     *  [String] or similar primitive type so that calling toString on it does not have strange side effects.
+     *  When the value returned is an [ObservableValue] or a [Property] the textProperty of the label
+     *  will update accordingly.
+     */
+    fun <M : Any, V : Any> textColumn(name: String, width: Int, valueAccessor: (M) -> V): TableColumn<M, V, Label> =
+        TableColumn(
+            name,
+            width,
+            valueAccessor
+        ) { cellValue ->
+            Components
+                .label()
+                .withSize(width, 1)
+                .build()
+                .apply {
+                    if (cellValue is ObservableValue<*>) {
+                        textProperty.updateFrom(cellValue.bindTransform { it.toString() }, true)
+                    } else {
+                        text = cellValue.toString()
+                    }
+                }
+        }
+
+    /**
+     * Creates a [textColumn] with the value returned by [valueAccessor] formatted with the format string [format].
+     */
+    fun <M : Any, V : Any> textColumnFormatted(
+        name: String,
+        width: Int,
+        format: String,
+        valueAccessor: (M) -> V
+    ): TableColumn<M, *, Label> =
+        textColumn(name, width) {
+            format
+                .format(
+                    valueAccessor
+                        .invoke(it)
+                )
+        }
+
+    /**
+     * Creates a column of width 1 which represents its values with an [Icon].
+     */
+    fun <M: Any, V: Any> icon(name: String,
+                              valueAccessor: (M) -> V,
+                              iconGenerator: (V) -> Icon): TableColumn<M, V, Icon> =
+            TableColumn(
+                    name,
+                    1,
+                    valueAccessor,
+                    iconGenerator
+            )
+}

zircon.core/src/commonMain/kotlin/org/hexworks/zircon/api/Fragments.kt

@@ -2,12 +2,12 @@ package org.hexworks.zircon.api
 
 import org.hexworks.zircon.api.builder.fragment.ColorThemeSelectorBuilder
 import org.hexworks.zircon.api.builder.fragment.SelectorBuilder
+import org.hexworks.zircon.api.builder.fragment.TableBuilder
 import org.hexworks.zircon.api.builder.fragment.TilesetSelectorBuilder
 import org.hexworks.zircon.api.component.ColorTheme
 import org.hexworks.zircon.api.component.Fragment
 import org.hexworks.zircon.api.fragment.Selector
 import org.hexworks.zircon.api.resource.TilesetResource
-import kotlin.jvm.JvmStatic
 
 /**
  * This *facade* object provides builders for the built-in [Fragment]s
@@ -39,4 +39,7 @@ object Fragments {
         theme: ColorTheme
     ): ColorThemeSelectorBuilder = ColorThemeSelectorBuilder.newBuilder(width, theme)
 
+    fun <M: Any> table(data: List<M>): TableBuilder<M> =
+        TableBuilder(data)
+
 }

zircon.core/src/commonMain/kotlin/org/hexworks/zircon/api/builder/fragment/TableBuilder.kt

@@ -0,0 +1,75 @@
+package org.hexworks.zircon.api.builder.fragment
+
+import org.hexworks.zircon.api.builder.Builder
+import org.hexworks.zircon.api.data.Position
+import org.hexworks.zircon.api.fragment.Table
+import org.hexworks.zircon.api.fragment.builder.FragmentBuilder
+import org.hexworks.zircon.internal.fragment.impl.table.DefaultTable
+import org.hexworks.zircon.internal.fragment.impl.table.TableColumn
+
+class TableBuilder<M : Any>(private val data: List<M>): FragmentBuilder<Table<M>, TableBuilder<M>> {
+
+    private val columns: MutableList<TableColumn<M, *, *>> = mutableListOf()
+    private var height: Int = 5
+    private var rowSpacing: Int = 0
+    private var colSpacing: Int = 0
+    private var position: Position? = null
+
+    override fun build(): Table<M> =
+        DefaultTable(
+            data,
+            columns,
+            height,
+            rowSpacing,
+            colSpacing
+        )
+            .apply {
+                position?.let { root.moveTo(it) }
+            }
+
+    /**
+     * Adds the given [TableColumn]s to the list of columns for this table. Multiple calls
+     * add to the already defined columns.
+     */
+    fun withColumns(vararg columns: TableColumn<M, *, *>) = also {
+        this.columns += columns
+    }
+
+    /**
+     * Sets the fragmentHeight of the resulting [Table].
+     */
+    fun withHeight(height: Int) = also {
+        this.height = height
+    }
+
+    /**
+     * Sets the spacing between each data row.
+     */
+    fun withRowSpacing(spacing: Int) = also {
+        rowSpacing = spacing
+    }
+
+    /**
+     * Sets the spacing between the columns.
+     */
+    fun withColumnSpacing(spacing: Int) = also {
+        colSpacing = spacing
+    }
+
+    override fun withPosition(position: Position): TableBuilder<M> = also {
+        this.position = position
+    }
+
+    override fun withPosition(x: Int, y: Int): TableBuilder<M> =
+        withPosition(Position.create(x, y))
+
+    override fun createCopy(): Builder<Table<M>> {
+        val copy = TableBuilder(data)
+            .withColumns(*columns.toTypedArray())
+            .withHeight(height)
+            .withRowSpacing(rowSpacing)
+            .withColumnSpacing(colSpacing)
+        position?.let { copy.withPosition(it) }
+        return copy
+    }
+}

zircon.core/src/commonMain/kotlin/org/hexworks/zircon/api/fragment/Table.kt

@@ -0,0 +1,31 @@
+package org.hexworks.zircon.api.fragment
+
+import org.hexworks.cobalt.databinding.api.value.ObservableValue
+import org.hexworks.zircon.api.component.Fragment
+import org.hexworks.zircon.api.data.Size
+
+/**
+ * A table fragment displays data in rows. Each row contains several cells. How a cell is displayed depends
+ * on the definition of it's column.
+ *
+ * A table contains data of type [M] (the model). Every model object represents one row in the table. **A table
+ * may not be empty**.
+ *
+ * @param M the type of the underlying model representing this table's data.
+ */
+interface Table<M: Any>: Fragment {
+    /**
+     * The element representing the currently selected row.
+     */
+    val selectedRow: M
+
+    /**
+     * The element representing the currently selected row as [ObservableValue].
+     */
+    val selectedRowValue: ObservableValue<M>
+
+    /**
+     * The size this table consumes based on its configured height and column definition.
+     */
+    val size: Size
+}

zircon.core/src/commonMain/kotlin/org/hexworks/zircon/internal/fragment/impl/table/DefaultTable.kt

@@ -0,0 +1,127 @@
+package org.hexworks.zircon.internal.fragment.impl.table
+
+import org.hexworks.cobalt.databinding.api.extension.toProperty
+import org.hexworks.cobalt.databinding.api.property.Property
+import org.hexworks.cobalt.databinding.api.value.ObservableValue
+import org.hexworks.zircon.api.Components
+import org.hexworks.zircon.api.component.AttachedComponent
+import org.hexworks.zircon.api.component.Component
+import org.hexworks.zircon.api.component.HBox
+import org.hexworks.zircon.api.component.VBox
+import org.hexworks.zircon.api.data.Size
+import org.hexworks.zircon.api.fragment.Table
+import org.hexworks.zircon.api.uievent.MouseEventType
+import org.hexworks.zircon.api.uievent.UIEventPhase
+import org.hexworks.zircon.api.uievent.UIEventResponse
+
+/**
+ * The **internal** default implementation of [Table].
+ */
+class DefaultTable<M: Any>(
+    private val data: List<M>,
+    private val columns: List<TableColumn<M, *, *>>,
+    /**
+     * The height this fragment will use. Keep in mind that the first row will be used as header row.
+     */
+    fragmentHeight: Int,
+    private val rowSpacing: Int = 0,
+    private val colSpacing: Int = 0
+): Table<M> {
+
+    init {
+        require(data.isNotEmpty()) {
+            "A table may not be empty! Please feed it some data to display."
+        }
+        require(columns.isNotEmpty()) {
+            "A table must have at least one column."
+        }
+        val minHeight = 2
+        require(fragmentHeight >= minHeight) {
+            "A table requires a height of at least $minHeight."
+        }
+    }
+
+    private val selectedElement: Property<M> = data.first().toProperty()
+
+    override val selectedRowValue: ObservableValue<M> = selectedElement
+
+    override val selectedRow: M
+        get() = selectedRowValue.value
+
+    override val size: Size = Size.create(
+        width = columns.sumBy { it.width } + ((columns.size - 1) * colSpacing),
+        height = fragmentHeight
+    )
+
+    override val root: VBox = Components
+        .vbox()
+        .withSpacing(0)
+        .withSize(size)
+        .build()
+
+    private val currentRows: MutableList<AttachedComponent> = mutableListOf()
+
+    init {
+        val headerRow = headerRow()
+        root
+            .addComponents(
+                headerRow,
+                dataPanel(Size.create(size.width, size.height - headerRow.height))
+            )
+    }
+
+    private fun dataPanel(panelSize: Size): VBox {
+        return Components
+            .vbox()
+            .withSize(panelSize)
+            .withSpacing(rowSpacing)
+            .build()
+            .apply {
+                var remainingHeight = panelSize.height
+                // TODO: Improve this loop to not loop over all elements
+                data.forEach { model ->
+                    val newRow = newRowFor(model)
+                    if(remainingHeight > 0) {
+                        currentRows.add(addComponent(newRow))
+                    }
+                    remainingHeight -= newRow.height + rowSpacing
+                }
+            }
+    }
+
+    private fun newRowFor(model: M): Component {
+        val cells: List<Component> = columns
+            .map { it.newCell(model) }
+        val rowHeight = cells.maxOf { it.height }
+        val row = Components
+            .hbox()
+            .withSpacing(colSpacing)
+            .withSize(size.width, rowHeight)
+            .build()
+        cells.forEach { row.addComponent(it) }
+        row.handleMouseEvents(MouseEventType.MOUSE_CLICKED) { _, phase ->
+            // allow for the cells to implement custom mouse event handling
+            if (phase == UIEventPhase.BUBBLE) {
+                selectedElement.updateValue(model)
+                UIEventResponse.processed()
+            } else {
+                UIEventResponse.pass()
+            }
+        }
+        return row
+    }
+
+    private fun headerRow(): HBox {
+        return Components
+            .hbox()
+            .withSize(size.width, 1)
+            .withSpacing(colSpacing)
+            .build()
+            .apply {
+                columns
+                    .forEach { column ->
+                        addComponent(column.header)
+                    }
+            }
+    }
+}

zircon.core/src/commonMain/kotlin/org/hexworks/zircon/internal/fragment/impl/table/TableColumn.kt

@@ -0,0 +1,42 @@
+package org.hexworks.zircon.internal.fragment.impl.table
+
+import org.hexworks.zircon.api.Components
+import org.hexworks.zircon.api.component.Component
+
+/**
+ * This class represents the definition of a column in a table. It provides means to get the value
+ * from a model object and wrap that value into a [Component]. This component is then displayed
+ * as table cell.
+ *
+ * @param M the type of the model. In other words: Every element/row in the table has this type
+ * @param V the type of the value of each cell in this column
+ * @param C type of the [Component] used to represent each cell
+ */
+open class TableColumn<M : Any, V : Any, C : Component>(
+    /**
+     * The name of this column. Will be used as table header.
+     */
+    val name: String,
+    /**
+     * The width of this column. The component created by [componentCreator] may not be wider than this.
+     */
+    val width: Int,
+    private val valueAccessor: (M) -> V,
+    private val componentCreator: (V) -> C
+) {
+    /**
+     * The [Component] that should be used as the column's header. It must have a width of [width] and a height
+     * of 1.
+     */
+    open val header: Component =
+        Components
+            .header()
+            .withText(name)
+            .withSize(width, 1)
+            .build()
+
+    fun newCell(rowElement: M): C =
+        componentCreator(
+            valueAccessor(rowElement)
+        )
+}

zircon.jvm.examples/src/main/java/org/hexworks/zircon/examples/playground/TablePrototypeJava.java

@@ -1,6 +1,9 @@
 package org.hexworks.zircon.examples.playground;
 
-import org.hexworks.zircon.api.*;
+import org.hexworks.zircon.api.CP437TilesetResources;
+import org.hexworks.zircon.api.ColorThemes;
+import org.hexworks.zircon.api.Components;
+import org.hexworks.zircon.api.SwingApplications;
 import org.hexworks.zircon.api.application.AppConfig;
 import org.hexworks.zircon.api.component.ComponentAlignment;
 import org.hexworks.zircon.api.component.Panel;
@@ -35,7 +38,7 @@ public static void main(String[] args) {
                 new Model(5, "Amanda", "Flair", "Brewer")
         );
 
-        Table<Model> table = new Table<>(fields, models);
+        TableOld<Model> table = new TableOld<>(fields, models);
 
         Screen screen = Screen.create(SwingApplications.startTileGrid(
                 AppConfig.newBuilder()