From d8779ac38742fe86d2489e47f5c8c4479ab74ba6 Mon Sep 17 00:00:00 2001 From: Robert Jaros Date: Fri, 9 Feb 2018 01:23:34 +0100 Subject: Refactoring. API documentation. --- src/main/kotlin/pl/treksoft/kvision/KVManager.kt | 22 ++- .../kotlin/pl/treksoft/kvision/core/Component.kt | 100 ++++++++++++- .../kotlin/pl/treksoft/kvision/core/Container.kt | 58 +++++++- src/main/kotlin/pl/treksoft/kvision/core/Css.kt | 144 +++++++++++++++++-- .../pl/treksoft/kvision/core/StyledComponent.kt | 127 ++++++++++++++++- src/main/kotlin/pl/treksoft/kvision/core/Types.kt | 35 +++++ src/main/kotlin/pl/treksoft/kvision/core/Widget.kt | 157 ++++++++++++++++++++- .../pl/treksoft/kvision/core/WidgetWrapper.kt | 46 ++++-- .../pl/treksoft/kvision/data/DataComponent.kt | 37 ++++- .../pl/treksoft/kvision/data/DataContainer.kt | 49 ++++++- .../pl/treksoft/kvision/data/DataUpdatable.kt | 24 ++++ .../pl/treksoft/kvision/dropdown/DropDown.kt | 87 ++++++++++-- .../kotlin/pl/treksoft/kvision/form/FieldLabel.kt | 32 ++++- src/main/kotlin/pl/treksoft/kvision/form/Form.kt | 127 +++++++++++++++-- .../kotlin/pl/treksoft/kvision/form/FormControl.kt | 95 +++++++++++++ .../kotlin/pl/treksoft/kvision/form/FormPanel.kt | 102 ++++++++++++- .../kotlin/pl/treksoft/kvision/form/HelpBlock.kt | 28 ++++ .../pl/treksoft/kvision/form/check/CheckBox.kt | 71 +++++++++- .../pl/treksoft/kvision/form/check/CheckInput.kt | 67 ++++++++- .../kotlin/pl/treksoft/kvision/form/check/Radio.kt | 76 +++++++++- .../pl/treksoft/kvision/form/check/RadioGroup.kt | 57 +++++++- .../pl/treksoft/kvision/form/select/AjaxOptions.kt | 78 ++++++++-- .../pl/treksoft/kvision/form/select/Select.kt | 109 ++++++++++++-- .../pl/treksoft/kvision/form/select/SelectInput.kt | 117 ++++++++++++--- .../treksoft/kvision/form/select/SelectOptGroup.kt | 53 ++++++- .../treksoft/kvision/form/select/SelectOption.kt | 62 ++++++-- .../pl/treksoft/kvision/form/spinner/Spinner.kt | 95 ++++++++++++- .../treksoft/kvision/form/spinner/SpinnerInput.kt | 107 +++++++++++++- .../pl/treksoft/kvision/form/text/AbstractText.kt | 80 ++++++++++- .../kvision/form/text/AbstractTextInput.kt | 84 ++++++++++- .../pl/treksoft/kvision/form/text/Password.kt | 29 ++++ .../pl/treksoft/kvision/form/text/RichText.kt | 32 +++++ .../pl/treksoft/kvision/form/text/RichTextInput.kt | 30 +++- .../kotlin/pl/treksoft/kvision/form/text/Text.kt | 37 ++++- .../pl/treksoft/kvision/form/text/TextArea.kt | 40 ++++++ .../pl/treksoft/kvision/form/text/TextAreaInput.kt | 43 +++++- .../pl/treksoft/kvision/form/text/TextInput.kt | 49 ++++++- .../pl/treksoft/kvision/form/time/DateTime.kt | 87 +++++++++++- .../pl/treksoft/kvision/form/time/DateTimeInput.kt | 95 ++++++++++++- .../pl/treksoft/kvision/hmr/ApplicationBase.kt | 22 ++- src/main/kotlin/pl/treksoft/kvision/hmr/HMR.kt | 22 ++- src/main/kotlin/pl/treksoft/kvision/html/Button.kt | 70 ++++++++- src/main/kotlin/pl/treksoft/kvision/html/Image.kt | 66 +++++++-- src/main/kotlin/pl/treksoft/kvision/html/Label.kt | 31 +++- src/main/kotlin/pl/treksoft/kvision/html/Link.kt | 55 +++++++- src/main/kotlin/pl/treksoft/kvision/html/List.kt | 76 ++++++++-- src/main/kotlin/pl/treksoft/kvision/html/Tag.kt | 60 +++++++- src/main/kotlin/pl/treksoft/kvision/modal/Alert.kt | 61 ++++++++ .../kotlin/pl/treksoft/kvision/modal/CloseIcon.kt | 31 +++- .../kotlin/pl/treksoft/kvision/modal/Confirm.kt | 61 +++++++- src/main/kotlin/pl/treksoft/kvision/modal/Modal.kt | 95 ++++++++++++- .../kotlin/pl/treksoft/kvision/panel/DockPanel.kt | 91 ++++++++++-- .../kotlin/pl/treksoft/kvision/panel/FlexPanel.kt | 96 +++++++++++-- .../kotlin/pl/treksoft/kvision/panel/GridPanel.kt | 118 +++++++++++++++- .../kotlin/pl/treksoft/kvision/panel/HPanel.kt | 33 +++++ .../treksoft/kvision/panel/ResponsiveGridPanel.kt | 63 ++++++++- src/main/kotlin/pl/treksoft/kvision/panel/Root.kt | 37 ++++- .../pl/treksoft/kvision/panel/SimplePanel.kt | 38 ++++- .../kotlin/pl/treksoft/kvision/panel/SplitPanel.kt | 40 +++++- .../kotlin/pl/treksoft/kvision/panel/StackPanel.kt | 40 ++++++ .../kotlin/pl/treksoft/kvision/panel/TabPanel.kt | 47 +++++- .../kotlin/pl/treksoft/kvision/panel/VPanel.kt | 32 +++++ .../kotlin/pl/treksoft/kvision/routing/Routing.kt | 33 +++++ src/main/kotlin/pl/treksoft/kvision/utils/Keys.kt | 31 ++++ .../kotlin/pl/treksoft/kvision/utils/Snabbdom.kt | 57 ++++++++ src/main/kotlin/pl/treksoft/kvision/utils/Utils.kt | 95 +++++++++++++ src/main/web/index.html | 21 +++ .../test/pl/treksoft/kvision/KVManagerSpec.kt | 21 +++ .../kotlin/test/pl/treksoft/kvision/TestUtil.kt | 21 +++ .../test/pl/treksoft/kvision/core/ContainerSpec.kt | 21 +++ .../test/pl/treksoft/kvision/core/WidgetSpec.kt | 21 +++ .../pl/treksoft/kvision/core/WidgetWrapperSpec.kt | 21 +++ .../pl/treksoft/kvision/data/DataContainerSpec.kt | 21 +++ .../pl/treksoft/kvision/dropdown/DropDownSpec.kt | 29 +++- .../pl/treksoft/kvision/form/FieldLabelSpec.kt | 21 +++ .../test/pl/treksoft/kvision/form/FormPanelSpec.kt | 21 +++ .../test/pl/treksoft/kvision/form/FormSpec.kt | 21 +++ .../test/pl/treksoft/kvision/form/HelpBlockSpec.kt | 21 +++ .../pl/treksoft/kvision/form/check/CheckBoxSpec.kt | 21 +++ .../treksoft/kvision/form/check/CheckInputSpec.kt | 21 +++ .../treksoft/kvision/form/check/RadioGroupSpec.kt | 21 +++ .../pl/treksoft/kvision/form/check/RadioSpec.kt | 21 +++ .../kvision/form/select/SelectInputSpec.kt | 21 +++ .../kvision/form/select/SelectOptGroupSpec.kt | 21 +++ .../kvision/form/select/SelectOptionSpec.kt | 21 +++ .../pl/treksoft/kvision/form/select/SelectSpec.kt | 21 +++ .../kvision/form/spinner/SpinnerInputSpec.kt | 21 +++ .../treksoft/kvision/form/spinner/SpinnerSpec.kt | 21 +++ .../pl/treksoft/kvision/form/text/PasswordSpec.kt | 21 +++ .../kvision/form/text/RichTextInputSpec.kt | 21 +++ .../pl/treksoft/kvision/form/text/RichTextSpec.kt | 21 +++ .../kvision/form/text/TextAreaInputSpec.kt | 21 +++ .../pl/treksoft/kvision/form/text/TextAreaSpec.kt | 21 +++ .../pl/treksoft/kvision/form/text/TextInputSpec.kt | 21 +++ .../test/pl/treksoft/kvision/form/text/TextSpec.kt | 21 +++ .../kvision/form/time/DateTimeInputSpec.kt | 21 +++ .../pl/treksoft/kvision/form/time/DateTimeSpec.kt | 21 +++ .../test/pl/treksoft/kvision/html/ButtonSpec.kt | 21 +++ .../test/pl/treksoft/kvision/html/ImageSpec.kt | 21 +++ .../test/pl/treksoft/kvision/html/LabelSpec.kt | 21 +++ .../test/pl/treksoft/kvision/html/LinkSpec.kt | 21 +++ .../test/pl/treksoft/kvision/html/ListSpec.kt | 27 +++- .../test/pl/treksoft/kvision/html/TagSpec.kt | 21 +++ .../test/pl/treksoft/kvision/modal/AlertSpec.kt | 21 +++ .../pl/treksoft/kvision/modal/CloseIconSpec.kt | 21 +++ .../test/pl/treksoft/kvision/modal/ConfirmSpec.kt | 21 +++ .../test/pl/treksoft/kvision/modal/ModalSpec.kt | 21 +++ .../pl/treksoft/kvision/panel/DockPanelSpec.kt | 21 +++ .../pl/treksoft/kvision/panel/FlexPanelSpec.kt | 21 +++ .../pl/treksoft/kvision/panel/GridPanelSpec.kt | 21 +++ .../test/pl/treksoft/kvision/panel/HPanelSpec.kt | 21 +++ .../kvision/panel/ResponsiveGridPanelSpec.kt | 21 +++ .../test/pl/treksoft/kvision/panel/RootSpec.kt | 21 +++ .../pl/treksoft/kvision/panel/SplitPanelSpec.kt | 21 +++ .../pl/treksoft/kvision/panel/StackPanelSpec.kt | 21 +++ .../test/pl/treksoft/kvision/panel/TabPanelSpec.kt | 21 +++ .../test/pl/treksoft/kvision/panel/VPanelSpec.kt | 21 +++ .../test/pl/treksoft/kvision/utils/UtilsSpec.kt | 21 +++ 118 files changed, 5103 insertions(+), 272 deletions(-) create mode 100644 src/main/kotlin/pl/treksoft/kvision/utils/Keys.kt (limited to 'src') diff --git a/src/main/kotlin/pl/treksoft/kvision/KVManager.kt b/src/main/kotlin/pl/treksoft/kvision/KVManager.kt index 5d5c03fa..b60764df 100644 --- a/src/main/kotlin/pl/treksoft/kvision/KVManager.kt +++ b/src/main/kotlin/pl/treksoft/kvision/KVManager.kt @@ -1,5 +1,23 @@ -/** - * @author Robert Jaros +/* + * 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 diff --git a/src/main/kotlin/pl/treksoft/kvision/core/Component.kt b/src/main/kotlin/pl/treksoft/kvision/core/Component.kt index c322892c..7125536a 100644 --- a/src/main/kotlin/pl/treksoft/kvision/core/Component.kt +++ b/src/main/kotlin/pl/treksoft/kvision/core/Component.kt @@ -1,3 +1,24 @@ +/* + * 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.core import com.github.snabbdom.VNode @@ -5,20 +26,91 @@ import org.w3c.dom.Node import pl.treksoft.jquery.JQuery import pl.treksoft.kvision.panel.Root +/** + * Base interface for all components. + */ interface Component { + /** + * Parent of the current component. + */ var parent: Component? + /** + * Visibility state of the current component. + */ var visible: Boolean - fun addCssClass(css: String): Widget - fun removeCssClass(css: String): Widget - fun addSurroundingCssClass(css: String): Widget - fun removeSurroundingCssClass(css: String): Widget + /** + * Adds given value to the set of CSS classes generated in html code of current component. + * @param css CSS class name + * @return current component + */ + fun addCssClass(css: String): Component + /** + * Removes given value from the set of CSS classes generated in html code of current component. + * @param css CSS class name + * @return current component + */ + fun removeCssClass(css: String): Component + + /** + * Adds given value to the set of CSS classes generated in html code of parent component. + * @param css CSS class name + * @return current component + */ + fun addSurroundingCssClass(css: String): Component + + /** + * Removes given value from the set of CSS classes generated in html code of parent component. + * @param css CSS class name + * @return current component + */ + fun removeSurroundingCssClass(css: String): Component + + /** + * @suppress + * Internal function + * Renders current component as a Snabbdom vnode. + * @return Snabbdom vnode + */ fun renderVNode(): VNode + + /** + * Returns DOM element bound to the current component. + * @return DOM element + */ fun getElement(): Node? + + /** + * Returns JQuery element bound to the current component. + * @return JQuery element + */ fun getElementJQuery(): JQuery? + + /** + * Returns JQuery element bound to the current component as a *dynamic* type. + * @return JQuery element as a *dynamic* type + */ fun getElementJQueryD(): dynamic + + /** + * @suppress + * Internal function. + * Sets **parent** property of current component to null. + * @return current component + */ fun clearParent(): Component + /** + * @suppress + * Internal function. + * Returns root component - the root node of components tree + * @return root component + */ fun getRoot(): Root? + /** + * @suppress + * Internal function + * Cleans resources allocated by the current component. + */ fun dispose() } diff --git a/src/main/kotlin/pl/treksoft/kvision/core/Container.kt b/src/main/kotlin/pl/treksoft/kvision/core/Container.kt index da436aba..a428ad14 100644 --- a/src/main/kotlin/pl/treksoft/kvision/core/Container.kt +++ b/src/main/kotlin/pl/treksoft/kvision/core/Container.kt @@ -1,14 +1,60 @@ +/* + * 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.core -import com.github.snabbdom.VNode - -interface Container { - var parent: Component? - var visible: Boolean - fun renderVNode(): VNode +/** + * Base interface for all containers. + */ +interface Container : Component { + /** + * Adds given component to the current container. + * @param child child component + * @return current container + */ fun add(child: Component): Container + + /** + * Adds a list of components to the current container. + * @param children list of child components + * @return current container + */ fun addAll(children: List): Container + + /** + * Removes given component from the current container. + * @param child child component + * @return current container + */ fun remove(child: Component): Container + + /** + * Removes all children from the current container. + * @return current container + */ fun removeAll(): Container + + /** + * Returns a list of children of the current container. + * @return list of children + */ fun getChildren(): List } diff --git a/src/main/kotlin/pl/treksoft/kvision/core/Css.kt b/src/main/kotlin/pl/treksoft/kvision/core/Css.kt index 80860647..8aeee71a 100644 --- a/src/main/kotlin/pl/treksoft/kvision/core/Css.kt +++ b/src/main/kotlin/pl/treksoft/kvision/core/Css.kt @@ -1,10 +1,34 @@ +/* + * 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.core import pl.treksoft.kvision.utils.asString import pl.treksoft.kvision.utils.toHexString +/** + * Definitions of CSS units. + */ @Suppress("EnumNaming", "EnumEntryName") -enum class UNIT(val unit: String) { +enum class UNIT(internal val unit: String) { px("px"), pt("pt"), em("em"), @@ -22,7 +46,10 @@ enum class UNIT(val unit: String) { auto("auto") } -enum class BORDERSTYLE(val borderStyle: String) { +/** + * Definitions of CSS border styles. + */ +enum class BORDERSTYLE(internal val borderStyle: String) { NONE("none"), HIDDEN("hidden"), DOTTED("dotted"), @@ -37,7 +64,10 @@ enum class BORDERSTYLE(val borderStyle: String) { INHERIT("inherit") } -enum class COLOR(val color: String) { +/** + * Definitions of CSS color names. + */ +enum class COLOR(internal val color: String) { ALICEBLUE("aliceblue"), ANTIQUEWHITE("antiquewhite"), AQUA("aqua"), @@ -181,63 +211,114 @@ enum class COLOR(val color: String) { YELLOWGREEN("yellowgreen") } -enum class BGSIZE(val size: String) { +/** + * Definitions of CSS background size. + */ +enum class BGSIZE(internal val size: String) { COVER("cover"), CONTAIN("contain") } -enum class BGREPEAT(val repeat: String) { +/** + * Definitions of CSS background repeat options. + */ +enum class BGREPEAT(internal val repeat: String) { REPEAT("repeat"), REPEATX("repeat-x"), REPEATY("repeat-y"), NOREPEAT("no-repeat") } -enum class BGATTACH(val attachment: String) { +/** + * Definitions of CSS background attachment options. + */ +enum class BGATTACH(internal val attachment: String) { SCROLL("scroll"), FIXED("fixed"), LOCAL("local") } -enum class BGORIGIN(val origin: String) { +/** + * Definitions of CSS background origin options. + */ +enum class BGORIGIN(internal val origin: String) { PADDING("padding-box"), BORDER("border-box"), CONTENT("content-box") } -enum class BGCLIP(val clip: String) { +/** + * Definitions of CSS background clipping options. + */ +enum class BGCLIP(internal val clip: String) { PADDING("padding-box"), BORDER("border-box"), CONTENT("content-box") } +/** + * Type-safe definition of CSS border. + */ class Border private constructor( private val width: CssSize? = null, private val style: BORDERSTYLE? = null, private val color: String? = null ) { + /** + * Creates CSS Border with given width and style. + * @param width width of the border + * @param style style of the border + */ constructor(width: CssSize? = null, style: BORDERSTYLE? = null) : this(width, style, null) + + /** + * Creates CSS Border with given width, style and color given in hex format. + * @param width width of the border + * @param style style of the border + * @param color color in hex format + */ constructor(width: CssSize? = null, style: BORDERSTYLE? = null, color: Int) : this( width, style, "#" + color.toHexString() ) + /** + * Creates CSS Border with given width, style and color given with named constant. + * @param width width of the border + * @param style style of the border + * @param color color named constant + */ constructor(width: CssSize? = null, style: BORDERSTYLE? = null, color: COLOR) : this(width, style, color.color) - fun asString(): String { + internal fun asString(): String { val w = width?.asString() return w.orEmpty() + " " + (style?.borderStyle).orEmpty() + " " + color.orEmpty() } } +/** + * Type-safe definition of CSS color. + */ class Color private constructor(private val color: String? = null) { + /** + * Creates CSS Color with color given in hex format. + * @param color color in hex format + */ constructor(color: Int) : this("#" + color.toHexString()) + + /** + * Creates CSS Color with color given with named constant. + * @param color color named constant + */ constructor(color: COLOR) : this(color.color) - fun asString(): String { + internal fun asString(): String { return color.orEmpty() } } +/** + * Type-safe definition of CSS background. + */ class Background private constructor( private val color: String? = null, private val image: ResString? = null, private val positionX: CssSize? = null, private val positionY: CssSize? = null, @@ -246,6 +327,19 @@ class Background private constructor( private val origin: BGORIGIN? = null, private val clip: BGCLIP? = null, private val attachment: BGATTACH? = null ) { + /** + * Creates CSS Background with given parameters. + * @param image background image + * @param positionX horizontal position of the background image + * @param positionY vertical position of the background image + * @param sizeX horizontal size of the background image + * @param sizeY vertical size of the background image + * @param size resize of the background image + * @param repeat repeat option of the background image + * @param origin origin option of the background image + * @param clip clipping option of the background image + * @param attachment attachment option of the background image + */ constructor( image: ResString? = null, positionX: CssSize? = null, positionY: CssSize? = null, sizeX: CssSize? = null, sizeY: CssSize? = null, size: BGSIZE? = null, @@ -256,6 +350,20 @@ class Background private constructor( image, positionX, positionY, sizeX, sizeY, size, repeat, origin, clip, attachment ) + /** + * Creates CSS Background with given parameters. + * @param color color of the background in hex format + * @param image background image + * @param positionX horizontal position of the background image + * @param positionY vertical position of the background image + * @param sizeX horizontal size of the background image + * @param sizeY vertical size of the background image + * @param size resize of the background image + * @param repeat repeat option of the background image + * @param origin origin option of the background image + * @param clip clipping option of the background image + * @param attachment attachment option of the background image + */ constructor( color: Int, image: ResString? = null, positionX: CssSize? = null, positionY: CssSize? = null, @@ -268,6 +376,20 @@ class Background private constructor( attachment ) + /** + * Creates CSS Background with given parameters. + * @param color color of the background with named constant + * @param image background image + * @param positionX horizontal position of the background image + * @param positionY vertical position of the background image + * @param sizeX horizontal size of the background image + * @param sizeY vertical size of the background image + * @param size resize of the background image + * @param repeat repeat option of the background image + * @param origin origin option of the background image + * @param clip clipping option of the background image + * @param attachment attachment option of the background image + */ constructor( color: COLOR, image: ResString? = null, positionX: CssSize? = null, positionY: CssSize? = null, sizeX: CssSize? = null, sizeY: CssSize? = null, @@ -278,7 +400,7 @@ class Background private constructor( positionX, positionY, sizeX, sizeY, size, repeat, origin, clip, attachment ) - fun asString(): String { + internal fun asString(): String { val img = image?.let { "url($image)" } diff --git a/src/main/kotlin/pl/treksoft/kvision/core/StyledComponent.kt b/src/main/kotlin/pl/treksoft/kvision/core/StyledComponent.kt index ed6def5f..f0ceb587 100644 --- a/src/main/kotlin/pl/treksoft/kvision/core/StyledComponent.kt +++ b/src/main/kotlin/pl/treksoft/kvision/core/StyledComponent.kt @@ -1,134 +1,247 @@ +/* + * 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.core import pl.treksoft.kvision.utils.asString +/** + * Base class for components supporting CSS styling. + */ abstract class StyledComponent : Component { - + /** + * Width of the current component. + */ open var width: CssSize? = null set(value) { field = value refresh() } + /** + * Minimal width of the current component. + */ var minWidth: CssSize? = null set(value) { field = value refresh() } + /** + * Maximal width of the current component. + */ var maxWidth: CssSize? = null set(value) { field = value refresh() } + /** + * Height of the current component. + */ var height: CssSize? = null set(value) { field = value refresh() } + /** + * Minimal height of the current component. + */ var minHeight: CssSize? = null set(value) { field = value refresh() } + /** + * Maximal height of the current component. + */ var maxHeight: CssSize? = null set(value) { field = value refresh() } + /** + * Border of the current component. + */ var border: Border? = null set(value) { field = value refresh() } + /** + * Top border of the current component. + */ var borderTop: Border? = null set(value) { field = value refresh() } + /** + * Right border of the current component. + */ var borderRight: Border? = null set(value) { field = value refresh() } + /** + * Bottom border of the current component. + */ var borderBottom: Border? = null set(value) { field = value refresh() } + /** + * Left border of the current component. + */ var borderLeft: Border? = null set(value) { field = value refresh() } + /** + * Margin of the current component. + */ var margin: CssSize? = null set(value) { field = value refresh() } + /** + * Top margin of the current component. + */ var marginTop: CssSize? = null set(value) { field = value refresh() } + /** + * Right margin of the current component. + */ var marginRight: CssSize? = null set(value) { field = value refresh() } + /** + * Bottom margin of the current component. + */ var marginBottom: CssSize? = null set(value) { field = value refresh() } + /** + * Left margin of the current component. + */ var marginLeft: CssSize? = null set(value) { field = value refresh() } + /** + * Padding of the current component. + */ var padding: CssSize? = null set(value) { field = value refresh() } + /** + * Top padding of the current component. + */ var paddingTop: CssSize? = null set(value) { field = value refresh() } + /** + * Right padding of the current component. + */ var paddingRight: CssSize? = null set(value) { field = value refresh() } + /** + * Bottom padding of the current component. + */ var paddingBottom: CssSize? = null set(value) { field = value refresh() } + /** + * Left padding of the current component. + */ var paddingLeft: CssSize? = null set(value) { field = value refresh() } + /** + * Text color for the current component. + */ var color: Color? = null set(value) { field = value refresh() } + /** + * Text color for the current component given in hex format (write only). + * + * This property gives a convenient way to set the value of [color] property e.g.: + * + * c.colorHex = 0x00ff00 + * + * The value read from this property is always null. + */ var colorHex: Int? get() = null set(value) { color = if (value != null) Color(value) else null } + /** + * Text color for the current component given with named constant (write only). + * + * This property gives a convenient way to set the value of [color] property e.g.: + * + * c.colorName = COLOR.GREEN + * + * The value read from this property is always null. + */ var colorName: COLOR? get() = null set(value) { color = if (value != null) Color(value) else null } + /** + * Opacity of the current component. + */ var opacity: Double? = null set(value) { field = value refresh() } + /** + * Background of the current component. + */ var background: Background? = null set(value) { field = value @@ -138,12 +251,18 @@ abstract class StyledComponent : Component { private var snStyleCache: List? = null + /** + * @suppress + * Internal function + * Re-renders the current component. + * @return current component + */ open fun refresh(): StyledComponent { snStyleCache = null return this } - protected fun getSnStyleInternal(): List { + internal fun getSnStyleInternal(): List { return snStyleCache ?: { val s = getSnStyle() snStyleCache = s @@ -151,6 +270,10 @@ abstract class StyledComponent : Component { }() } + /** + * Returns the list of String pairs defining CSS style attributes and their values. + * @return the list of attributes and their values + */ @Suppress("ComplexMethod", "LongMethod") protected open fun getSnStyle(): List { val snstyle = mutableListOf() diff --git a/src/main/kotlin/pl/treksoft/kvision/core/Types.kt b/src/main/kotlin/pl/treksoft/kvision/core/Types.kt index 05a4bec7..0817b3ae 100644 --- a/src/main/kotlin/pl/treksoft/kvision/core/Types.kt +++ b/src/main/kotlin/pl/treksoft/kvision/core/Types.kt @@ -1,9 +1,44 @@ +/* + * 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.core + /** + * This type is used for accessing resources with CommonJS **require** function. + * + * e.g. require("./img/picture.png") + */ typealias ResString = String + /** + * Helper type used to define CSS style attributes. + */ typealias StringPair = Pair + /** + * Helper type used to define CSS classes. + */ typealias StringBoolPair = Pair + /** + * This type is used for defining CSS dimensions (width, heights, margins, paddings, etc.). + */ typealias CssSize = Pair diff --git a/src/main/kotlin/pl/treksoft/kvision/core/Widget.kt b/src/main/kotlin/pl/treksoft/kvision/core/Widget.kt index 08e67da0..5f664563 100644 --- a/src/main/kotlin/pl/treksoft/kvision/core/Widget.kt +++ b/src/main/kotlin/pl/treksoft/kvision/core/Widget.kt @@ -1,3 +1,24 @@ +/* + * 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.core import com.github.snabbdom.VNode @@ -17,6 +38,14 @@ import pl.treksoft.kvision.utils.snClasses import pl.treksoft.kvision.utils.snOpt import pl.treksoft.kvision.utils.snStyle +/** + * Base widget class. The parent of all component classes. + * + * A simple widget is rendered as HTML DIV element. + * + * @constructor Creates basic Widget with given CSS class names. + * @param classes Set of CSS class names + */ @Suppress("TooManyFunctions", "LargeClass") open class Widget(classes: Set = setOf()) : StyledComponent() { @@ -33,22 +62,31 @@ open class Widget(classes: Set = setOf()) : StyledComponent() { field = value if (oldField != field) refresh() } + /** + * A title attribute of generated HTML element. + */ var title: String? = null set(value) { field = value refresh() } + /** + * An ID attribute of generated HTML element. + */ var id: String? = null set(value) { field = value refresh() } + /** + * A role attribute of generated HTML element. + */ var role: String? = null set(value) { field = value refresh() } - var surroundingSpan: Boolean = false + internal var surroundingSpan: Boolean = false set(value) { field = value refresh() @@ -62,7 +100,7 @@ open class Widget(classes: Set = setOf()) : StyledComponent() { private var snOnCache: com.github.snabbdom.On? = null private var snHooksCache: com.github.snabbdom.Hooks? = null - protected fun singleRender(block: () -> T): T { + internal fun singleRender(block: () -> T): T { getRoot()?.renderDisabled = true val t = block() getRoot()?.renderDisabled = false @@ -89,18 +127,38 @@ open class Widget(classes: Set = setOf()) : StyledComponent() { } } + /** + * Renders current component as a Snabbdom vnode. + * @return Snabbdom vnode + */ protected open fun render(): VNode { - return kvh("div") + return render("div") } - protected open fun kvh(s: String): VNode { - return h(s, getSnOpt()) + /** + * Renders current component as a Snabbdom vnode. + * @param elementName HTML element name + * @return Snabbdom vnode + */ + protected open fun render(elementName: String): VNode { + return h(elementName, getSnOpt()) } - protected open fun kvh(s: String, children: Array): VNode { - return h(s, getSnOpt(), children) + /** + * Renders current component as a Snabbdom vnode. + * @param elementName HTML element name + * @param children array of children nodes + * @return Snabbdom vnode + */ + protected open fun render(elementName: String, children: Array): VNode { + return h(elementName, getSnOpt(), children) } + /** + * Generates VNodeData to creating Snabbdom VNode. + * + * Optimizes creating process by keeping configuration attributes in a cache. + */ private fun getSnOpt(): VNodeData { return snOpt { attrs = snAttrs(getSnAttrsInternal()) @@ -143,10 +201,18 @@ open class Widget(classes: Set = setOf()) : StyledComponent() { }() } + /** + * Returns list of CSS class names for current widget in the form of a List. + * @return list of CSS class names + */ protected open fun getSnClass(): List { return classes.map { c -> c to true } + if (visible) listOf() else listOf("hidden" to true) } + /** + * Returns list of element attributes in the form of a List. + * @return list of element attributes + */ protected open fun getSnAttrs(): List { val snattrs = mutableListOf() id?.let { @@ -161,6 +227,10 @@ open class Widget(classes: Set = setOf()) : StyledComponent() { return snattrs } + /** + * Returns list of event handlers in the form of a Snabbdom *On* object. + * @return list of event handlers + */ protected open fun getSnOn(): com.github.snabbdom.On? { return if (internalListeners.size > 0 || listeners.size > 0) { val internalHandlers = on(this) @@ -209,6 +279,10 @@ open class Widget(classes: Set = setOf()) : StyledComponent() { } } + /** + * Returns list of hooks in the form of a Snabbdom *Hooks* object. + * @return list of hooks + */ protected open fun getSnHooks(): com.github.snabbdom.Hooks? { val hooks = hooks() hooks.apply { @@ -236,6 +310,10 @@ open class Widget(classes: Set = setOf()) : StyledComponent() { return hooks } + /** + * @suppress + * Internal function + */ @Suppress("UNCHECKED_CAST") protected fun setInternalEventListener(block: SnOn.() -> Unit): Widget { internalListeners.add(block as SnOn.() -> Unit) @@ -243,12 +321,31 @@ open class Widget(classes: Set = setOf()) : StyledComponent() { return this } + /** + * @suppress + * Internal function + */ protected fun setInternalEventListener(block: SnOn.() -> Unit): Widget { internalListeners.add(block) refresh() return this } + /** + * Sets an event listener for current widget, keeping the actual type of component. + * @param T widget type + * @param block event handler + * @return current widget + * + * Example: + * + * button.setEventListener