From ce010c1aa5ae3f6243dc08aafaba650341022d59 Mon Sep 17 00:00:00 2001
From: minjaesong <alswo9628@gmail.com>
Date: Sun, 17 Feb 2019 18:17:30 +0900
Subject: [PATCH] doc update for UICanvas and UIItem

---
 src/net/torvald/terrarum/ui/UICanvas.kt | 23 +++++++++++++++++++++--
 src/net/torvald/terrarum/ui/UIItem.kt   | 17 ++++++++++++++---
 2 files changed, 35 insertions(+), 5 deletions(-)

diff --git a/src/net/torvald/terrarum/ui/UICanvas.kt b/src/net/torvald/terrarum/ui/UICanvas.kt
index 3051424bf..bf4cce94d 100644
--- a/src/net/torvald/terrarum/ui/UICanvas.kt
+++ b/src/net/torvald/terrarum/ui/UICanvas.kt
@@ -11,9 +11,28 @@ import net.torvald.terrarum.roundInt
 
 
 /**
- * UIItems must be added manually at the init!
+ * ## UI Items
  *
- * FIXME: Bad design!!
+ * UI can contain one or more UI elements (called UIItem). Each UIItem can have one or more events programmed to it.
+ * Events have their own listener are governed by their GDX event handlers (e.g. mouseMoved).
+ * These GDX handlers are what makes the our own handler to work.
+ *
+ * UIItems have following event handlers: updateLister, keyDownListener, mouseMovedListener, touchDraggedListener, touchDownListener, touchUpListener, scrolledListener, and clickOnceListener.
+ * (perhaps clickOnceListener is the one most useful)
+ *
+ * To make them work without any hassle on your part,
+ * all the UIItems must be added to this UICanvas's ```uiItems``` list.
+ *
+ * See also: [net.torvald.terrarum.ui.UIItem]
+ *
+ * ## Sub UIs
+ *
+ * Sub UIs are UICanvases that is child of this UICanvas. They are also managed internally to lessen your burden.
+ * Just add all the Sub UIs using ```addSubUI()``` method.
+ *
+ * ## Position variables
+ *
+ * PosX/Y and relativeMouseX/Y are explained in ```work_files/terrarum_ui_elements_coord_explained.png```
  *
  * Created by minjaesong on 2015-12-31.
  */
diff --git a/src/net/torvald/terrarum/ui/UIItem.kt b/src/net/torvald/terrarum/ui/UIItem.kt
index 830d5dc75..af28f0960 100644
--- a/src/net/torvald/terrarum/ui/UIItem.kt
+++ b/src/net/torvald/terrarum/ui/UIItem.kt
@@ -3,6 +3,7 @@ package net.torvald.terrarum.ui
 import com.badlogic.gdx.Gdx
 import com.badlogic.gdx.graphics.Camera
 import com.badlogic.gdx.graphics.g2d.SpriteBatch
+import com.badlogic.gdx.utils.Disposable
 import net.torvald.terrarum.AppLoader
 import net.torvald.terrarum.Terrarum
 
@@ -27,16 +28,26 @@ import net.torvald.terrarum.Terrarum
  * For example:
  *
  * ```
- * <<some_name>>.clickOnceListener = { mouseX, mouseY, button ->
+ * Kotlin:
+ * <<identifier>>.clickOnceListener = { mouseX, mouseY, button ->
  *     println("Bo-ing!")
  * }
+ *
+ * Java:
+ * <<identifier>>.setClickOnceListener((mouseX, mouseY, button) -> {
+ *     System.out.println("Bo-ing!");
+ *     return null;
+ * });
  * ```
  *
  * This listener will print out 'Bo-ing!' whenever it's clicked.
  *
+ * As mentioned in [UICanvas], UIItems must be added to the Canvas to make listeners work without implementing
+ * everything by yourself.
+ *
  * Created by minjaesong on 2015-12-31.
  */
-abstract class UIItem(var parentUI: UICanvas) { // do not replace parentUI to UIHandler!
+abstract class UIItem(var parentUI: UICanvas): Disposable { // do not replace parentUI to UIHandler!
 
     // X/Y Position relative to the containing canvas
     abstract var posX: Int
@@ -214,6 +225,6 @@ abstract class UIItem(var parentUI: UICanvas) { // do not replace parentUI to UI
         return false
     }
 
-    abstract fun dispose()
+    abstract override fun dispose()
 
 }