Add mini-writeup on how to write components.

This commit is contained in:
kenkeiras 2018-01-24 23:56:21 +01:00
parent 2f58d1d609
commit 168ed17fb2

65
HowToWriteAComponent.md Normal file
View File

@ -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.