From 479bd775884b4ac0df35eb0d27279e3fbcf823db Mon Sep 17 00:00:00 2001 From: Arjan Molenaar Date: Sat, 12 Dec 2020 17:10:16 +0100 Subject: [PATCH] Update API docs --- docs/api.rst | 4 ++-- docs/api/connections.rst | 2 +- docs/api/handles.rst | 35 ++++++++++++++++++++++++++++++++ docs/api/model.rst | 38 +++++++++++++++++++++++++++++++++++ docs/api/painters.rst | 3 +++ docs/api/protocols.rst | 18 ----------------- docs/api/tools.rst | 5 ++++- docs/{api => }/decorators.rst | 0 docs/index.rst | 1 + 9 files changed, 84 insertions(+), 22 deletions(-) create mode 100644 docs/api/handles.rst create mode 100644 docs/api/model.rst delete mode 100644 docs/api/protocols.rst rename docs/{api => }/decorators.rst (100%) diff --git a/docs/api.rst b/docs/api.rst index cbc174c..0fec3af 100644 --- a/docs/api.rst +++ b/docs/api.rst @@ -6,8 +6,8 @@ API reference :caption: View :maxdepth: 1 - api/protocols api/view + api/model api/painters api/tools @@ -17,6 +17,7 @@ The central part for Gaphas is the View. That's the class that ensures stuff is :caption: Connections :maxdepth: 1 + api/handles api/connections api/variable @@ -28,6 +29,5 @@ One of Gaphas' USP is it's the way it handles connections and the constraint sol api/matrix api/geometry - api/decorators Finally there are classes and modules that make up the building blocks on which Gaphas is built: diff --git a/docs/api/connections.rst b/docs/api/connections.rst index 6edb60e..7fee6ff 100644 --- a/docs/api/connections.rst +++ b/docs/api/connections.rst @@ -1,7 +1,7 @@ Connections =========== -The ``Connections`` class can be used to manage any type of constraint. +The ``Connections`` class can be used to manage any type of constraint within, and between items. .. autoclass:: gaphas.connections.Connections :members: \ No newline at end of file diff --git a/docs/api/handles.rst b/docs/api/handles.rst new file mode 100644 index 0000000..41fbcb9 --- /dev/null +++ b/docs/api/handles.rst @@ -0,0 +1,35 @@ +Handles and Ports +================= + +To connect one item to another, you need something to connect, and something to connect to. +These roles are fulfilled by ``Handle`` and ``Port``. + +The Handle is an item you normally see on screen as a small square, eiter green or red. +Although the actual shape depends on the Painter_ used. + +Ports represent the receiving side. A port decides if it wants a connection with a handle. +If it does, a constraint can be created and this constraint will be managed by a Connections_ instance. +It is not uncommon to create special ports to suite your application's behavior, whereas Handles are rarely subtyped. + +Handle +------ + +.. autoclass:: gaphas.connector.Handle + :members: + +Port +---- + +The ``Port`` class. There are two default implementations: ``LinePort`` and ``PointPort``. + +.. autoclass:: gaphas.connector.Port + :members: + +.. autoclass:: gaphas.connector.LinePort + :members: + +.. autoclass:: gaphas.connector.PointPort + :members: + +.. _Painter: painters.html#gaphas.painter.HandlePainter +.. _Connections: connections.html \ No newline at end of file diff --git a/docs/api/model.rst b/docs/api/model.rst new file mode 100644 index 0000000..def37b8 --- /dev/null +++ b/docs/api/model.rst @@ -0,0 +1,38 @@ + +Model +===== + +Protocols +--------- + +Although ``gaphas.Canvas`` can be used as a default model, any class that adhere's to the Model protocol can be used as a model. + +.. autoclass:: gaphas.view.model.Model + :members: + +An item should implement these methods, so it can be rendered by the View. Not that painters or tools can require additional methods. + +.. autoclass:: gaphas.item.Item + :members: + +Default implementations +----------------------- + +Canvas +~~~~~~ + +The default implementation for a ``Model``, is a class called ``Canvas``. + +.. autoclass:: gaphas.canvas.Canvas + :members: + +Items +~~~~~ + +Gaphas provides two default items, an box-like element and a line shape. + +.. autoclass:: gaphas.item.Element + :members: + +.. autoclass:: gaphas.item.Line + :members: diff --git a/docs/api/painters.rst b/docs/api/painters.rst index 6c004fa..f42d649 100644 --- a/docs/api/painters.rst +++ b/docs/api/painters.rst @@ -3,6 +3,9 @@ Painters Painters are used to draw the view. +Protocols +--------- + Each painter adheres to the ``Painter`` protocol. .. autoclass:: gaphas.painter.Painter diff --git a/docs/api/protocols.rst b/docs/api/protocols.rst deleted file mode 100644 index 6485cd6..0000000 --- a/docs/api/protocols.rst +++ /dev/null @@ -1,18 +0,0 @@ - -Protocols -========= - -Although ``gaphas.Canvas`` can be used as a default model, any class that adhere's to the Model protocol can be used as a model. - -.. autoclass:: gaphas.view.model.Model - :members: - -An item should implement these methods, so it can be rendered by the View. Not that painters or tools can require additional methods. - -.. autoclass:: gaphas.item.Item - :members: - -The view should support just thise one protocol, which will allow update requests to -propagate to the view: - -.. automethod:: gaphas.view.model.View.request_update diff --git a/docs/api/tools.rst b/docs/api/tools.rst index 6eae0d2..2b1fd0e 100644 --- a/docs/api/tools.rst +++ b/docs/api/tools.rst @@ -3,7 +3,7 @@ Tools Tools are used to interact with the view. -Each tool is basically a function that produces a ``Gtk.EventController``. +Each tool is basically a function that produces a Gtk.EventController_. The event controllers are already configured. .. autofunction:: gaphas.tool.hover_tool @@ -12,3 +12,6 @@ The event controllers are already configured. .. autofunction:: gaphas.tool.rubberband_tool .. autofunction:: gaphas.tool.scroll_tool .. autofunction:: gaphas.tool.zoom_tool + + +.. _Gtk.EventController: https://lazka.github.io/pgi-docs/#Gtk-3.0/classes/EventController.html \ No newline at end of file diff --git a/docs/api/decorators.rst b/docs/decorators.rst similarity index 100% rename from docs/api/decorators.rst rename to docs/decorators.rst diff --git a/docs/index.rst b/docs/index.rst index b0cb001..8cbaacf 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -61,6 +61,7 @@ Table of Contents quadtree table tree + decorators .. _Cairo: https://cairographics.org .. _Model-View-Controller: https://en.wikipedia.org/wiki/Model%E2%80%93view%E2%80%93controller