doc update for UICanvas and UIItem

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.
  */

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()
 
 }