From 168ed17fb244e92c706349544b7d39838e4c1c60 Mon Sep 17 00:00:00 2001
From: kenkeiras <kenkeiras@codigoparallevar.com>
Date: Wed, 24 Jan 2018 23:56:21 +0100
Subject: [PATCH] Add mini-writeup on how to write components.

---
 HowToWriteAComponent.md | 65 +++++++++++++++++++++++++++++++++++++++++
 1 file changed, 65 insertions(+)
 create mode 100644 HowToWriteAComponent.md

diff --git a/HowToWriteAComponent.md b/HowToWriteAComponent.md
new file mode 100644
index 0000000..588b03b
--- /dev/null
+++ b/HowToWriteAComponent.md
@@ -0,0 +1,65 @@
+# How to write a new component
+
+This is a work in progress used for internal reference. It asumes you have some practice coding in
+Java. Hopefully a more polished version will be written :)
+
+## 1. Create a new Part class
+
+Inside the [app/src/main/java/com/codigoparallevar/minicards/parts](app/src/main/java/com/codigoparallevar/minicards/parts)
+directory, in the appropiate subdirectory, create a new Java class which `implements Part`.
+Part as in `com.codigoparallevar.minicards.types.Part`.
+
+Create a constructor for the class, probably you'll want information like the following:
+
+* PartGrid `partGrid`: environment where the component will be placed.
+* int `left`, `top`, `right`, `bottom`: Left(/top/right/bottom)-most coordinate of your component,
+  needed to draw the element.
+
+## 2. Fill all the needed methods
+
+Inside the class, instruct your IDE to implement the interface methods, each method responsibility
+follows:
+
+* `void moveEnd(int x, int y)`: Update the position of the component so it's centerd on this point.
+
+* `void drop(int x, int y)`: Update the position of the component so it's centerd on this point.
+This can be done just by calling moveEnd. The separation between drop and moveEnd might sound absurd
+but it'll come handy on some occasions.
+
+* `boolean containsPoint(int x, int y)`: True if a x,y coordinate is contained inside the component.
+* `Moveable getMoveable()`: Just `return this`.
+
+* `void unlink()`: Remove all input connections attached to the component.
+
+* `void draw(ScrolledCanvas canvas, boolean devMode)`: Draw the component on the canvas.
+
+* `int getLeft()`: Return the leftmost coordinate of the component.
+* `int getRight()`: Return the rightmost coordinate of the component.
+* `int getTop()`: Return the topmost coordinate of the component.
+* `int getBottom()`: Return the bottommost coordinate of the component.
+
+* `void touched()`: The user touched the component, do what you must.
+
+* `List<InputConnector> getSignalInputConnectors()`: Return all the input connectors.
+
+* `List<OutputConnector> getOutputConnectors()`: Return all the output connectors.
+
+* `JSONObject serialize()`: Return a JSON-serialized version of the component.
+* `void sendSignal(RoundInputConnector roundInputConnector)`: This will be removed, just ignore it.
+
+* `String getId()`: Return an unique ID for the component.
+
+* `String getConnectorId(InputConnector inputConnector)`: Return an unique ID for an input connector.
+
+* `InputConnector getConnectorWithId(String inputConnectorId)`: Obtain the component ID with the given connector.
+
+* `void resume()`: Called when the component is on an active card.
+* `void pause()`: Called when the component card stops being active.
+
+## 3. Add component to the parts holder
+
+You'll need to give it a name and create a static `getInstantiator()` method inside your class. Check the ones working for examples.
+
+## 4. Add deserialization method
+
+Look for the `deserializeObject()` method on the `CardFile` class and add a condition to deserialize your class.