Refactoring. API documentation.

4 files changed, 257 insertions, 14 deletions

diff --git a/src/main/kotlin/pl/treksoft/kvision/form/check/CheckBox.kt b/src/main/kotlin/pl/treksoft/kvision/form/check/CheckBox.kt
index ea41c429..0bad8440 100644
--- a/src/main/kotlin/pl/treksoft/kvision/form/check/CheckBox.kt
+++ b/src/main/kotlin/pl/treksoft/kvision/form/check/CheckBox.kt
@@ -1,15 +1,39 @@
+/*
+ * Copyright (c) 2017-present Robert Jaros
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
 package pl.treksoft.kvision.form.check
 
 import org.w3c.dom.events.MouseEvent
+import pl.treksoft.kvision.core.StringBoolPair
 import pl.treksoft.kvision.core.Widget
 import pl.treksoft.kvision.form.BoolFormControl
 import pl.treksoft.kvision.form.FieldLabel
 import pl.treksoft.kvision.form.HelpBlock
 import pl.treksoft.kvision.panel.SimplePanel
 import pl.treksoft.kvision.utils.SnOn
-import pl.treksoft.kvision.core.StringBoolPair
 
-enum class CHECKBOXSTYLE(val className: String) {
+/**
+ * Checkbox style options.
+ */
+enum class CHECKBOXSTYLE(internal val className: String) {
     DEFAULT("checkbox-default"),
     PRIMARY("checkbox-primary"),
     SUCCESS("checkbox-success"),
@@ -18,21 +42,41 @@ enum class CHECKBOXSTYLE(val className: String) {
     DANGER("checkbox-danger"),
 }
 
+/**
+ * The form field component rendered as HTML *input type="checkbox"*.
+ *
+ * @constructor
+ * @param value selection state
+ * @param label label text bound to the input element
+ * @param rich determines if [label] can contain HTML code
+ */
 open class CheckBox(
     value: Boolean = false, label: String? = null,
     rich: Boolean = false
 ) : SimplePanel(setOf("checkbox")), BoolFormControl {
 
+    /**
+     * The selection state of the checkbox.
+     */
     override var value
         get() = input.value
         set(value) {
             input.value = value
         }
+    /**
+     * The value attribute of the generated HTML input element.
+     *
+     * This value is placed directly in generated HTML code, while the [value] property is dynamically
+     * bound to the input selection state.
+     */
     var startValue
         get() = input.startValue
         set(value) {
             input.startValue = value
         }
+    /**
+     * The name attribute of the generated HTML input element.
+     */
     var name
         get() = input.name
         set(value) {
@@ -43,31 +87,49 @@ open class CheckBox(
         set(value) {
             input.disabled = value
         }
+    /**
+     * The label text bound to the input element.
+     */
     var label
         get() = flabel.text
         set(value) {
             flabel.text = value
         }
+    /**
+     * Determines if [label] can contain HTML code.
+     */
     var rich
         get() = flabel.rich
         set(value) {
             flabel.rich = value
         }
+    /**
+     * The style (one of Bootstrap standard colors) of the input.
+     */
     var style: CHECKBOXSTYLE? = null
         set(value) {
             field = value
             refresh()
         }
+    /**
+     * Determines if the checkbox is rendered as a circle.
+     */
     var circled: Boolean = false
         set(value) {
             field = value
             refresh()
         }
+    /**
+     * Determines if the checkbox is rendered inline.
+     */
     var inline: Boolean = false
         set(value) {
             field = value
             refresh()
         }
+    /**
+     * The size of the input.
+     */
     override var size
         get() = input.size
         set(value) {
@@ -92,7 +154,7 @@ open class CheckBox(
     }
 
     companion object {
-        var counter = 0
+        internal var counter = 0
     }
 
     @Suppress("UNCHECKED_CAST")
@@ -128,6 +190,9 @@ open class CheckBox(
         return cl
     }
 
+    /**
+     * A convenient helper for easy setting onClick event handler.
+     */
     open fun onClick(handler: CheckBox.(MouseEvent) -> Unit): CheckBox {
         this.setEventListener<CheckBox> {
             click = { e ->
diff --git a/src/main/kotlin/pl/treksoft/kvision/form/check/CheckInput.kt b/src/main/kotlin/pl/treksoft/kvision/form/check/CheckInput.kt
index a7d562a2..26a06fa7 100644
--- a/src/main/kotlin/pl/treksoft/kvision/form/check/CheckInput.kt
+++ b/src/main/kotlin/pl/treksoft/kvision/form/check/CheckInput.kt
@@ -1,17 +1,49 @@
+/*
+ * Copyright (c) 2017-present Robert Jaros
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
 package pl.treksoft.kvision.form.check
 
 import com.github.snabbdom.VNode
 import org.w3c.dom.events.MouseEvent
-import pl.treksoft.kvision.core.Widget
-import pl.treksoft.kvision.form.INPUTSIZE
 import pl.treksoft.kvision.core.StringBoolPair
 import pl.treksoft.kvision.core.StringPair
+import pl.treksoft.kvision.core.Widget
+import pl.treksoft.kvision.form.INPUTSIZE
 
-enum class CHECKINPUTTYPE(val type: String) {
+/**
+ * Type of the check input control (checkbox or radio).
+ */
+enum class CHECKINPUTTYPE(internal val type: String) {
     CHECKBOX("checkbox"),
     RADIO("radio")
 }
 
+/**
+ * The basic input component rendered as HTML *input type="checkbox"* or *input type="radio"*.
+ *
+ * @constructor
+ * @param type type of the input control
+ * @param value selection state
+ * @param classes a set of CSS class names
+ */
 open class CheckInput(
     type: CHECKINPUTTYPE = CHECKINPUTTYPE.CHECKBOX, value: Boolean = false,
     classes: Set<String> = setOf()
@@ -30,37 +62,61 @@ open class CheckInput(
         }
     }
 
+    /**
+     * The selection state of the input.
+     */
     var value: Boolean = value
         set(value) {
             field = value
             refreshState()
         }
+    /**
+     * The value attribute of the generated HTML input element.
+     *
+     * This value is placed directly in generated HTML code, while the [value] property is dynamically
+     * bound to the input selection state.
+     */
     var startValue: Boolean = value
         set(value) {
             field = value
             this.value = value
             refresh()
         }
+    /**
+     * The type of the generated HTML input element.
+     */
     var type: CHECKINPUTTYPE = type
         set(value) {
             field = value
             refresh()
         }
+    /**
+     * The name attribute of the generated HTML input element.
+     */
     var name: String? = null
         set(value) {
             field = value
             refresh()
         }
+    /**
+     * Determines if the field is disabled.
+     */
     var disabled: Boolean = false
         set(value) {
             field = value
             refresh()
         }
+    /**
+     * The additional String value used for the radio button group.
+     */
     var extraValue: String? = null
         set(value) {
             field = value
             refresh()
         }
+    /**
+     * The size of the input.
+     */
     var size: INPUTSIZE? = null
         set(value) {
             field = value
@@ -68,7 +124,7 @@ open class CheckInput(
         }
 
     override fun render(): VNode {
-        return kvh("input")
+        return render("input")
     }
 
     override fun getSnClass(): List<StringBoolPair> {
@@ -112,6 +168,9 @@ open class CheckInput(
         }
     }
 
+    /**
+     * A convenient helper for easy setting onClick event handler.
+     */
     open fun onClick(handler: CheckInput.(MouseEvent) -> Unit): CheckInput {
         this.setEventListener<CheckInput> {
             click = { e ->
diff --git a/src/main/kotlin/pl/treksoft/kvision/form/check/Radio.kt b/src/main/kotlin/pl/treksoft/kvision/form/check/Radio.kt
index ac6df5b1..a8059230 100644
--- a/src/main/kotlin/pl/treksoft/kvision/form/check/Radio.kt
+++ b/src/main/kotlin/pl/treksoft/kvision/form/check/Radio.kt
@@ -1,15 +1,39 @@
+/*
+ * Copyright (c) 2017-present Robert Jaros
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
 package pl.treksoft.kvision.form.check
 
 import org.w3c.dom.events.MouseEvent
+import pl.treksoft.kvision.core.StringBoolPair
 import pl.treksoft.kvision.core.Widget
 import pl.treksoft.kvision.form.BoolFormControl
 import pl.treksoft.kvision.form.FieldLabel
 import pl.treksoft.kvision.form.HelpBlock
 import pl.treksoft.kvision.panel.SimplePanel
 import pl.treksoft.kvision.utils.SnOn
-import pl.treksoft.kvision.core.StringBoolPair
 
-enum class RADIOSTYLE(val className: String) {
+/**
+ * Radio style options.
+ */
+enum class RADIOSTYLE(internal val className: String) {
     DEFAULT("radio-default"),
     PRIMARY("radio-primary"),
     SUCCESS("radio-success"),
@@ -18,26 +42,51 @@ enum class RADIOSTYLE(val className: String) {
     DANGER("radio-danger"),
 }
 
+/**
+ * The form field component rendered as HTML *input type="radio"*.
+ *
+ * @constructor
+ * @param value selection state
+ * @param extraValue the additional String value used for the radio button group
+ * @param name the name attribute of the generated HTML input element
+ * @param label label text bound to the input element
+ * @param rich determines if [label] can contain HTML code
+ */
 open class Radio(
     value: Boolean = false, extraValue: String? = null, name: String? = null, label: String? = null,
     rich: Boolean = false
 ) : SimplePanel(), BoolFormControl {
 
+    /**
+     * The selection state of the radio button.
+     */
     override var value
         get() = input.value
         set(value) {
             input.value = value
         }
+    /**
+     * The value attribute of the generated HTML input element.
+     *
+     * This value is placed directly in generated HTML code, while the [value] property is dynamically
+     * bound to the input selection state.
+     */
     var startValue
         get() = input.startValue
         set(value) {
             input.startValue = value
         }
+    /**
+     * The additional String value used for the radio button group.
+     */
     var extraValue
         get() = input.extraValue
         set(value) {
             input.extraValue = value
         }
+    /**
+     * The name attribute of the generated HTML input element.
+     */
     var name
         get() = input.name
         set(value) {
@@ -48,31 +97,49 @@ open class Radio(
         set(value) {
             input.disabled = value
         }
+    /**
+     * The label text bound to the input element.
+     */
     var label
         get() = flabel.text
         set(value) {
             flabel.text = value
         }
+    /**
+     * Determines if [label] can contain HTML code.
+     */
     var rich
         get() = flabel.rich
         set(value) {
             flabel.rich = value
         }
+    /**
+     * The style (one of Bootstrap standard colors) of the input.
+     */
     var style: RADIOSTYLE? = null
         set(value) {
             field = value
             refresh()
         }
+    /**
+     * Determines if the radio button is rendered as a square.
+     */
     var squared: Boolean = false
         set(value) {
             field = value
             refresh()
         }
+    /**
+     * Determines if the radio button is rendered inline.
+     */
     var inline: Boolean = false
         set(value) {
             field = value
             refresh()
         }
+    /**
+     * The size of the input.
+     */
     override var size
         get() = input.size
         set(value) {
@@ -98,7 +165,7 @@ open class Radio(
     }
 
     companion object {
-        var counter = 0
+        internal var counter = 0
     }
 
     @Suppress("UNCHECKED_CAST")
@@ -143,6 +210,9 @@ open class Radio(
         return cl
     }
 
+    /**
+     * A convenient helper for easy setting onClick event handler.
+     */
     open fun onClick(handler: Radio.(MouseEvent) -> Unit): Radio {
         this.setEventListener<Radio> {
             click = { e ->
diff --git a/src/main/kotlin/pl/treksoft/kvision/form/check/RadioGroup.kt b/src/main/kotlin/pl/treksoft/kvision/form/check/RadioGroup.kt
index 5060b6cb..7bd13d4e 100644
--- a/src/main/kotlin/pl/treksoft/kvision/form/check/RadioGroup.kt
+++ b/src/main/kotlin/pl/treksoft/kvision/form/check/RadioGroup.kt
@@ -1,5 +1,28 @@
+/*
+ * Copyright (c) 2017-present Robert Jaros
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
 package pl.treksoft.kvision.form.check
 
+import pl.treksoft.kvision.core.StringBoolPair
+import pl.treksoft.kvision.core.StringPair
 import pl.treksoft.kvision.core.Widget
 import pl.treksoft.kvision.form.FieldLabel
 import pl.treksoft.kvision.form.HelpBlock
@@ -7,27 +30,47 @@ import pl.treksoft.kvision.form.INPUTSIZE
 import pl.treksoft.kvision.form.StringFormControl
 import pl.treksoft.kvision.form.select.Select
 import pl.treksoft.kvision.panel.SimplePanel
-import pl.treksoft.kvision.core.StringBoolPair
-import pl.treksoft.kvision.core.StringPair
 
+/**
+ * The form field component rendered as a group of HTML *input type="radio"* elements with the same name attribute.
+ *
+ * The radio group can be populated directly from *options* parameter or manually by adding
+ * [Radio] components to the container.
+ *
+ * @constructor
+ * @param options an optional list of options (label to value pairs) for the group
+ * @param value selected option
+ * @param inline determines if the options are rendered inline
+ * @param label label text of the options group
+ * @param rich determines if [label] can contain HTML code
+ */
 open class RadioGroup(
     options: List<StringPair>? = null, value: String? = null, inline: Boolean = false,
     label: String? = null,
     rich: Boolean = false
 ) : SimplePanel(setOf("form-group")), StringFormControl {
 
-    internal var options = options
+    /**
+     * A list of options (label to value pairs) for the group.
+     */
+    var options = options
         set(value) {
             field = value
             setChildrenFromOptions()
         }
 
+    /**
+     * A value of the selected option.
+     */
     override var value = value
         set(value) {
             field = value
             setValueToChildren(value)
         }
 
+    /**
+     * Determines if the options are rendered inline.
+     */
     var inline: Boolean = inline
         set(value) {
             field = value
@@ -39,11 +82,17 @@ open class RadioGroup(
         set(value) {
             setDisabledToChildren(value)
         }
+    /**
+     * The label text of the options group.
+     */
     var label
         get() = flabel.text
         set(value) {
             flabel.text = value
         }
+    /**
+     * Determines if [label] can contain HTML code.
+     */
     var rich
         get() = flabel.rich
         set(value) {
@@ -62,7 +111,7 @@ open class RadioGroup(
     }
 
     companion object {
-        var counter = 0
+        internal var counter = 0
     }
 
     override fun getSnClass(): List<StringBoolPair> {