Merge pull request #2 from cowboy-coders/feature/docs

Nim/Docs/NimQml.txt

@@ -7,7 +7,7 @@
 
 Introduction
 -----------
-The NimQml module add Qt Qml bindings to the Nim programming language
+The NimQml module adds Qt Qml bindings to the Nim programming language
 allowing you to create new modern UI by mixing the Qml declarative syntax
 and the Nim imperative language.
 
@@ -22,7 +22,7 @@ the libDOtherSide exported symbols in Nim
 Building
 --------
 At the time of writing the DOtherSide C++ library must be compiled
-installed manually from source.
+and installed manually from source.
 
 First clone the DOtherSide git repo
 ::
@@ -36,7 +36,7 @@ than you can proceed with the common CMake build steps
   cmake ..
   make
 
-If everything goes correctly you'll have build both
+If everything goes correctly, you'll have built both
 the DOtherSide C++ library and the Nim examples
 
 Installation
@@ -63,7 +63,7 @@ Example 1: HelloWorld
 As usual lets start with an HelloWorld example.
 Most of the NimQml projects are made by one or more nim and qml
 files. Usually the .nim files contains your app logic and data
-layer. The qml files contains the presentation layer and expose
+layer. The qml files contain the presentation layer and expose
 the data in your nim files.
 
 ``Examples/HelloWorld/main.nim``
@@ -87,8 +87,8 @@ Example 2: exposing data to Qml
 The previous example shown you how to create a simple application
 window and how to startup the Qt event loop.
 
-Is time to explore how to pass to to Qml, but first lets see the
-example code:
+It's time to explore how to pass data to Qml, but lets see the
+example code first:
 
 ``Examples/SimpleData/main.nim``
 
@@ -100,13 +100,13 @@ example code:
 .. code-block:: qml
    :file: ../Examples/SimpleData/main.qml
    
-The following example shows how to expose simple data to Qml:
-1. Create a QVariant and sets the its internal value. 
+The following example shows how to expose simple data types to Qml:
+1. Create a QVariant and set its internal value. 
 2. Create a property in the Qml root context with a given name.
 
-Once a a property is set through the ``setContextProperty`` proc its available
-globally in all the Qml script loaded by the current engine (see the Qt doc
-for more details about engine and context)
+Once a property is set through the ``setContextProperty`` proc, it's available
+globally in all the Qml script loaded by the current engine (see the official Qt 
+documentation for more details about the engine and context objects)
 
 At the time of writing the QVariant class support the following types:
 * int
@@ -116,21 +116,21 @@ At the time of writing the QVariant class support the following types:
 
 Example 3: exposing complex data and procedures to Qml
 ----------------------------------------------------------
-As seen by the second example simple data is fine. However most
+As seen by the second example, simple data is fine. However most
 applications need to expose complex data, functions and
-update the view when something change in the data layer.
+update the view when something changes in the data layer.
 This is achieved by creating an object that derives from QObject.
 
 A QObject is made of :
-1. ``Slots``: slots are function that could both be called from the qml engine and connected to Qt signals
+1. ``Slots``: slots are functions that could be called from the qml engine and/or connected to Qt signals
 2. ``Signals``: signals allow the sending of events and be connected to slots
-3. ``Properties``: properties allows the passing of data to
+3. ``Properties``: properties allow the passing of data to
    the Qml view and make it aware of changes in the data layer
 
 A QObject property is made of three things:
-* a read slot, a method that return the current value of the property
-* a write slot, a method that set the value of the property
-* a notify signal for telling that the current value of the property has been changed
+* a read slot: a method that returns the current value of the property
+* a write slot: a method that sets the value of the property
+* a notify signal: emitted when the current value of the property is changed
 
 We'll start by looking at the main.nim file
 
@@ -139,24 +139,25 @@ We'll start by looking at the main.nim file
 .. code-block:: nim
    :file: ../Examples/SlotsAndProperties/main.nim
 
-Here's nothing special happen except:
+Here, nothing special happens except:
 1. The creation of Contact object
 2. The injection of the Contact object to the Qml root context
    using the ``setContextProperty`` as seen in the previous
    example
 
-The Qml file is as follow:
+The Qml file is as follows:
 
 ``Examples/SlotsAndProperties/main.qml``
 
 .. code-block:: qml
    :file: ../Examples/SlotsAndProperties/main.qml
 
-The qml is made by a Label, a TextInput and a button.
-The label display the contact name and automatically udpates when
-the concat name changes.
+The qml is made up of: a Label, a TextInput widget, and a button.
+The label displays the contact name - this automatically updates when
+the contact name changes.
 
-The button update the contact name with the TextInput text when clicked.
+When clicked, the button updates the contact name with the text from 
+the TextInput widget.
 
 So where's the magic?
 
@@ -167,37 +168,37 @@ The magic is in the Contact.nim file
 .. code-block:: nim
    :file: ../Examples/SlotsAndProperties/Contact.nim
 
-What First we declare a QObject subclass and provide a simple
-new method where:
+First we declare a QObject subclass and provide a simple
+new method where we:
 1. invoke the ``create()`` procedure. This invoke the C++ bridge and allocate
 a QObject instance
 2. register a slot ``getName`` for reading the Contact name field
-3. register a slot `` setName`` for writing the Contact name
+3. register a slot ``setName`` for writing the Contact name
 4. register a signal ``nameChanged`` for notify the contact name changes
 5. register a property called ``name`` of type ``QString`` with the given
    read, write slots and notify signal
 
-The two slots method implementation are trivial and consist in standard
-nim methods. However ``setName`` slot method shows how to emit a signal
-by using the ``emit`` method.
+Looking at the ``getName`` and ``setName`` methods, you can see that slots, as defined in Nim,
+are nothing more than standard methods. The method corresponding to the ``setName`` slot 
+demonstrates how to use the ``emit`` method to emit a signal.
 
-The last thing to condider is the override of the ``onSlotCalled`` method.
-This method is called by the NimQml library when an invokation occur from
-the Qml side for one of the QObject slot.
-The usual implementation for the onSlotCalled method consists in a
-switch statement that forward the arguments to the correct slot.
-If the invoked slot has a return value this is always in the index position
+The last thing to consider is the override of the ``onSlotCalled`` method.
+This method is called by the NimQml library when an invocation occurs from
+the Qml side for one of the slots belonging to the QObject.
+The usual implementation for the onSlotCalled method consists of a
+switch statement that forwards the arguments to the correct slot.
+If the invoked slot has a return value, this is always in the index position
 0 of the args array.
 
 
 Example 4: QtObject macro
 -------------------------
-The previous example shows how to create simple QObject however writing
+The previous example shows how to create a simple QObject, however writing
 all those ``register`` procs and writing the ``onSlotCalled`` method
-become boring pretty soon.
+becomes boring pretty soon.
 
 Furthermore all this information can be automatically generated.
-For this purpose you can import the NimQmlMacros module that provide
+For this purpose you can import the NimQmlMacros module that provides
 the QtObject macro.
 
 Let's begin as usual with both the main.nim and main.qml files
@@ -213,8 +214,8 @@ Let's begin as usual with both the main.nim and main.qml files
 .. code-block:: qml
    :file: ../Examples/QtObjectMacro/main.qml
 
-Nothing new in both the ``main.nim`` and ``main.qml`` in respect to
-the previous example. What changed is the Contact object
+Nothing is new in both the ``main.nim`` and ``main.qml`` with respect to
+the previous example. What changed is the Contact object:
 
 ``Examples/QtObjectMacro/Contact.nim``
 
@@ -223,8 +224,8 @@ the previous example. What changed is the Contact object
 
 In details:
 1. Each QObject is defined inside the QtObject macro
-2. Each slot is annotated with the ``{.slot.}`` macro
-3. Each signal is annotated with the ``{.signal.}`` macro
+2. Each slot is annotated with the ``{.slot.}`` pragma
+3. Each signal is annotated with the ``{.signal.}`` pragma
 4. Each property is created with the ``QtProperty`` macro
 
 The ``QtProperty`` macro has the following syntax