Continue README, eg. add API description

1 files changed, 126 insertions, 7 deletions

diff --git a/README.md b/README.md
index 99859b8..84e8f0f 100644
--- a/README.md
+++ b/README.md
@@ -1,15 +1,134 @@
 
 ## what is it for?
--for implementing cursor navigation on QML UIs
--define items as cursor navigable, CursorNavigation backend registers items and takes care of the navigation
--based on UI geometry, no need to define navigation paths or item relations
--2 ways of spatial navigation: 4 way and 360. 4 way simple and good for rectangular structured UIs, 360 allows stepless movement to any direction
 
-## install
--distributed as a qt plugin
--build and make install
+Cursor is an indicator for the target of user interactions in a GUI. In this case, it's more specifically a selector for individual UI elements, such as buttons, and not completely freely moving, like a mouse pointer. The purpose of the CursorNavigation plugin is to provide a generic way of enabling cursor navigation in QML UIs with minimal configuration and ease of use in mind. Minimal configuration, in this case, would be in comparison to eg. qt's existing key navigation, where the navigation path has to be defined explicitly on a per element basis. CursorNavigation ships as a plugin for Qt and is loaded by simply importing it in QML, usable right from the beginning of the ui development.
 
 
+## How does it work?
+
+CursorNavigation works by allowing the developer to define individual QML elements as navigable. The framework's backend keeps track of the navigable items and their parent-child relations and position and geometry on the UI. Moving the cursor is handled by algorithms, and is based just on the location and geometry of the items. There are 2 algorithm for spatial navigation: 4-way and free-directional. The simpler 4-way navigation is well suited for traditional, rectangular and structured UIs, while the 360-algorithm allows moving freely to any direction.
+
+There may be one instance of the CursorNavigation backend per window and one item per window having the cursor. Moving the cursor is also moving the active focus between the items. This means that inputs are directed on the item that has the cursor and that the cursor movement can be refined using Qt's FocusScopes.
+
+By default, CursorNavigation uses they keyboard as input, but it also provides an API for using any kind of input source for control.
+
+
+## Installing
+
+CursorNavigation is distributed as a Qt QML plugin. Build the plugin and the demo application by building the project CursorNavigation.pro. Run make install in the build directory to install the plugin to Qt's plugins directory. After installing the plugin is available to any project using that version of Qt.
+
+
+## Interface
+
+### Properties
+
+Set this to true to include the item for cursor navigation.
+```
+bool acceptsCursor
+```
+
+Indicates if the item itself, or one of its non-navigable children has the active focus.
+```
+bool hasCursor
+```
+
+Set this to true to limit the cursor's movement to this item and its children. In order to move the cursor out of the item's scope, force active focus somewhere outside or define an escape target.
+```
+bool trapsCursor
+```
+
+Set a target for moving to cursor to in case of the escape-input.
+```
+QQuickItem* escapeTarget
+```
+
+### Methods
+
+Just for passing forward information of intended movement, eg. analog joystick movement. Does not affect the cursor in any way. Changes are received by the item that currently has the cursor.
+```
+void setMagnitude(qreal angle, qreal magnitude);
+void setMagnitude(QVector2D vector);
+```
+
+Move the cursor to the given direction using the given tolerance. Items that are exactly in the direction are preferred over items that just fall within the tolerance. The item that had the cursor will have its moved-signal emitted. If there is no item to be found, nothing happens.
+```
+void move(qreal angle, qreal tolerance = 0);
+void move(QVector2D vector, qreal tolerance = 0);
+```
+
+Finds the next item, without moving the cursor. If there is no item to be found, returns a null.
+```
+QQuickItem *find(qreal angle, qreal tolerance = 0);
+QQuickItem *find(QVector2D vector, qreal tolerance = 0);
+```
+
+Moves the cursor up, down, right or left using the 4-way algorithm. The item that had the cursor will have its corresponding signal emitted. If there is no item to move to, does nothing.
+```
+void moveUp();
+void moveDown();
+void moveRight();
+void moveLeft();
+```
+
+The item that currently has the cursor, will have its activated signal emitted. Does not affect the cursor position.
+```
+void activate();
+```
+
+Not yet implemented. Would do the tab- back-tab style of navigation.
+```
+void moveForward();
+void moveBack();
+```
+
+Move the cursor to the escape target defined to this item. If no escape target is defined, cursor is passed to item's parent. The item that had the cursor will have its escaped-signal emitted.
+```
+void escape();
+```
+
+### Signals
+
+```
+void magnitudeChanged(qreal angle, qreal magnitude);
+void moved(qreal angle, qreal tolerance);
+void movedUp();
+void movedDown();
+void movedRight();
+void movedLeft();
+void activated();
+void movedForward();
+void movedBack();
+void escaped();
+```
+
+## Using CursorNavigation
+
+The way to define items as cursor navigable, is done via CursorNavigation's attached propert'acceptsCursor'. Use the read-only property 'hasCursor' to test if the item is selected. The example below shows how to define a button that is navigable:
+
+```
+// CNButton.qml
+// This is a button that supports cursor navigation
+
+import QtQuick 2.0
+import QtQuick.Controls 2.2
+import CursorNavigation 1.0
+
+Button {
+    id: button
+    CursorNavigation.acceptsCursor: true
+
+    //visualize selection with a bright border
+    Rectangle {
+        border.width: 2
+        border.color: "red"
+        anchors.fill: parent
+        visible: parent.CursorNavigation.hasCursor
+    }
+}
+```
+
+As CursorNavigation is about moving the active focus, it is possible to use FocusScopes with it. FocusScopes are useful when focus needs to be proxied to Item's children. The example below show how to have a "cursor scope", an item that accepts the cursor, but passes it on to the child items. It is also possible to limit the cursor's movement to the children using the CursorNavigation.trapsCursor property. To leave a scope that traps the cursor, define a escape target with the CursorNavigation.escapeTarget property.
+
 use:
 -import in QML
 -defining item as navigable