# Drawing and Graphical Interactions

## Introduction

* Whenever relevant, the **eVision** tools provide methods `Draw` to render their contents and/or configuration. This is, for instance, the contents of an `EImage` or the frame of an `EROI`.
* A given tool can have multiple methods `Draw`, usually one for each feature available.
* The `Draw` methods take an instance of [`EDrawAdapter`](../../doxygen_cpp/classeVision_1_1EDrawAdapter.html) [<sub>.NET</sub>](../../doxygen_cs/classeVision_1_1EDrawAdapter.html) [<sub>Python</sub>](../../doxygen_python/classeVision_1_1EDrawAdapter.html) as their main parameter, and additional parameters for zoom and pan:

  `Tool.Draw(EDrawAdapter* adapter, float zoomX, float zoomY, float panX, float panY);`
  * `zoomX` and `zoomY` are expressed in percentage, 1 is the default value and means no zoom.
  * It can be different in the horizontal and vertical directions (which can be useful in the case of non-square pixels for instance).
  * If you don’t provide a vertical zoom, or set it to 0, it will be set identical to the horizontal one.
  * `panX` and `panY` are expressed in pixels, but in image coordinates. It means that the value you pass to `panX` and `panY` are multiplied by the corresponding zoom before being applied.

Example: How to draw an image and a ROI frame on a window in C++ under Windows:

```c
EImageBW8 image;
EROIBW8 roi;
EWindowsDrawAdapter adapter(windowHdc);
image.Draw(adapter);
roi.DrawFrame(adapter);
```

## Graphical interactions

* You can configure some of the **eVision** tools graphically and use the provided methods to put your configuration in place.
* Graphical Interaction-enabled tools provide special parameters to some of their methods `Draw` to draw handles on the tool representation.
* To capture the user interactions with those handles, these tools also provide two specialized methods:
  * `HitTest` detects if a handle is under the mouse when providing it with the current cursor coordinates. You typically use this test during a mouse button down event.
  * `Drag` moves the detected handle to the given coordinates. This in turn modifies the tool configuration to match the new handle position. `Drag` is typically associated with the mouse button up event.

  #### NOTE
  `HitTest` and `Drag` use the same zoom and pan parameters as `Draw`. You must set them the same way (with the same values) to achieve the desired result.
* Use [`Easy::GetHandleSize`](../../doxygen_cpp/classeVision_1_1Easy.html#ac44de38a44253d25ae8da454bac056a0) [<sub>.NET</sub>](../../doxygen_cs/classeVision_1_1Easy.html#ad1482696d2235789c5dfe7c48b6c7c4d) [<sub>Python</sub>](../../doxygen_python/classeVision_1_1Easy.html#ad4d68bfb0c661864c0e1671619b9272f) to change the handle size.
  * This value influences the drawing and the hit area.
  * By default, the handle size is equal to 8 pixels.

## Draw adapters

* The draw adapters are objects that, in addition to representing the context in which to draw, provide methods to draw the selected primitives in that context.
* They are initialized by providing the targeted context to the constructor.
* Some of the drawing methods provided by the draw adapters are (but are not limited to):
  * [`EDrawAdapter::Line`](../../doxygen_cpp/classeVision_1_1EDrawAdapter.html#aca27509b509ada30bb57981b987a9434) [<sub>.NET</sub>](../../doxygen_cs/classeVision_1_1EDrawAdapter.html#a853bc1d9319d91bd5a098ab5e4d83980) [<sub>Python</sub>](../../doxygen_python/classeVision_1_1EDrawAdapter.html#aaee796951b1bf140f6fdbdcf3d1b2fd0) / [`EDrawAdapter::Line`](../../doxygen_cpp/classeVision_1_1EDrawAdapter.html#aca27509b509ada30bb57981b987a9434) [<sub>.NET</sub>](../../doxygen_cs/classeVision_1_1EDrawAdapter.html#a853bc1d9319d91bd5a098ab5e4d83980) [<sub>Python</sub>](../../doxygen_python/classeVision_1_1EDrawAdapter.html#aaee796951b1bf140f6fdbdcf3d1b2fd0) draws one or more lines on the context
  * [`EDrawAdapter::Rectangle`](../../doxygen_cpp/classeVision_1_1EDrawAdapter.html#ab4c1a33f7962e0810d60fd327cfe4bcd) [<sub>.NET</sub>](../../doxygen_cs/classeVision_1_1EDrawAdapter.html#a3352c5438f88290d05f108fecb9fa3e8) [<sub>Python</sub>](../../doxygen_python/classeVision_1_1EDrawAdapter.html#abf8428df0a51e76ba786e04b25870c55) / [`EDrawAdapter::FilledRectangle`](../../doxygen_cpp/classeVision_1_1EDrawAdapter.html#a68578ba928468636fed418b81abd14a8) [<sub>.NET</sub>](../../doxygen_cs/classeVision_1_1EDrawAdapter.html#acf140c6de5497fca1b423ee565f974ff) [<sub>Python</sub>](../../doxygen_python/classeVision_1_1EDrawAdapter.html#a85c647e8a572dd04e69942e39682500c) draws a rectangle, filled or not, on the context
  * [`EDrawAdapter::Ellipse`](../../doxygen_cpp/classeVision_1_1EDrawAdapter.html#a109b7cfc5f7b21f90150f5659af0e1a1) [<sub>.NET</sub>](../../doxygen_cs/classeVision_1_1EDrawAdapter.html#a8de20b4fc545a0f8db8251922b10d785) [<sub>Python</sub>](../../doxygen_python/classeVision_1_1EDrawAdapter.html#a81b31d43de2a55956fb9ffd3ed76ed3e) / [`EDrawAdapter::FilledEllipse`](../../doxygen_cpp/classeVision_1_1EDrawAdapter.html#a45b09b0a2223d823eb8ec1d794efbe7c) [<sub>.NET</sub>](../../doxygen_cs/classeVision_1_1EDrawAdapter.html#a4ac663135e43b607ddca88f0bdd09454) [<sub>Python</sub>](../../doxygen_python/classeVision_1_1EDrawAdapter.html#ace6ad0248ef527ef5ef6f80af8fe5d46) draws an ellipse, filled or not, in the context
  * [`EDrawAdapter::Text`](../../doxygen_cpp/classeVision_1_1EDrawAdapter.html#a984f04de86845405575f33992a7d3279) [<sub>.NET</sub>](../../doxygen_cs/classeVision_1_1EDrawAdapter.html#a57d60055a67d8d857c2890e5174fb711) [<sub>Python</sub>](../../doxygen_python/classeVision_1_1EDrawAdapter.html#a5f03c973b826945c6cad75f5a53a7803) / [`EDrawAdapter::BackedText`](../../doxygen_cpp/classeVision_1_1EDrawAdapter.html#a5e47bc04ed79bff6dd1f81c04408bac9) [<sub>.NET</sub>](../../doxygen_cs/classeVision_1_1EDrawAdapter.html#a4182d7aa2a319eba32bdaf77dcac7314) [<sub>Python</sub>](../../doxygen_python/classeVision_1_1EDrawAdapter.html#abf535a5c825d4b14593b9f9688087c82) renders a text in the context, with or without background
  * [`EDrawAdapter::Image`](../../doxygen_cpp/classeVision_1_1EDrawAdapter.html#a3212e737fc15d706d870ece4c4d6f363) [<sub>.NET</sub>](../../doxygen_cs/classeVision_1_1EDrawAdapter.html#ae354df2358072d5576be31622f07a2d5) [<sub>Python</sub>](../../doxygen_python/classeVision_1_1EDrawAdapter.html#a49de18122c8bc820557816e3480083d3) renders an image in the context
* For more information about the drawing primitives provided by the draw adapters, please refer to the reference documentation.
* To set the color of the primitives, provide a pen and/or a brush and use the methods [`EDrawAdapter::GetPen`](../../doxygen_cpp/classeVision_1_1EDrawAdapter.html#afcd8feaba3aedc66c7afdc88866dc39d) [<sub>.NET</sub>](../../doxygen_cs/classeVision_1_1EDrawAdapter.html#a187d7736e9c416688fb7ff744b21ebb5) [<sub>Python</sub>](../../doxygen_python/classeVision_1_1EDrawAdapter.html#a9375054e278f726262aeee6132921e5d) and [`EDrawAdapter::GetBrush`](../../doxygen_cpp/classeVision_1_1EDrawAdapter.html#a6cde134369af812642fe826b4461d3a4) [<sub>.NET</sub>](../../doxygen_cs/classeVision_1_1EDrawAdapter.html#a578afc3cce5de16dcc03b063a22f9430) [<sub>Python</sub>](../../doxygen_python/classeVision_1_1EDrawAdapter.html#a12e2f6c9360101f8386bd01cb6641382).
  * If you do not provide a pen and/or a brush, the default colors are used.
* The set the font of the text, provide a font with the method [`EDrawAdapter::GetFont`](../../doxygen_cpp/classeVision_1_1EDrawAdapter.html#a8a37a6d4ab1ed9298f413513033a6348) [<sub>.NET</sub>](../../doxygen_cs/classeVision_1_1EDrawAdapter.html#a9d26d5851cff03fc920fa055ce90d1de) [<sub>Python</sub>](../../doxygen_python/classeVision_1_1EDrawAdapter.html#a8c6ee93e198e77a8d6383de3696e702d).

## Standard draw adapters

**eVision** provides a set of off-the-shelf draw adapters that you can use in different situations:

* [`EWindowsDrawAdapter`](../../doxygen_cpp/classeVision_1_1EWindowsDrawAdapter.html) [<sub>.NET</sub>](../../doxygen_cs/classeVision_1_1EWindowsDrawAdapter.html) [<sub>Python</sub>](../../doxygen_python/classeVision_1_1EWindowsDrawAdapter.html) allows to draw on **Windows** systems. To draw on a window, provide the window’s HDC to its constructor, or, to draw in an `EImage` buffer, provide that `EImage`.
  * It relies on GDI and GDI+ to provide its services.
  * This is the preferred way to draw on **Windows** using C++.
* [`ESystemDrawingDrawAdapter`](../../doxygen_cs/classeVision_1_1ESystemDrawingDrawAdapter.html)allows to draw on **Windows** systems using .NET. To draw on a window, provide the window’s `Graphics` object to its constructor.
  * This is the preferred way to draw on **Windows** when using .NET.
* `QtDrawAdapter` allows you to draw using **Qt** on a QPainter context. To draw on a QPainter context, provide the QPainter to the constructor, or, to draw on an `EImage` buffer, provide that `EImage`.
  * You can use the `QtDrawAdapter` both on **Windows** and **Linux**.
  * This is the preferred way to draw on **Linux**.

    #### NOTE
    `QtDrawAdapter` is using an external resource (namely **Qt**) and as such is provided as source code in its own header rather than in the global **eVision** header. For more information about external and custom draw adapters, see below.
* [`EGenericDrawAdapter`](../../doxygen_cpp/classeVision_1_1EGenericDrawAdapter.html) [<sub>.NET</sub>](../../doxygen_cs/classeVision_1_1EGenericDrawAdapter.html) [<sub>Python</sub>](../../doxygen_python/classeVision_1_1EGenericDrawAdapter.html) is a draw adapter that can only render on an `EImage`, but it can do it in a consistent manner on all supported OSes.
  * It is available on both **Windows** and **Linux**.

## Drawing in an `EImage`

* As said above, you can draw in an `EImage` (usually an `EImageBW8` or `EImageC24A`) by initializing a draw adapter with that image and using either the **eVision** methods `Draw` or the draw adapter drawing primitives. [`EGenericDrawAdapter`](../../doxygen_cpp/classeVision_1_1EGenericDrawAdapter.html) [<sub>.NET</sub>](../../doxygen_cs/classeVision_1_1EGenericDrawAdapter.html) [<sub>Python</sub>](../../doxygen_python/classeVision_1_1EGenericDrawAdapter.html) is the recommended way to draw in an image.

```c
EImageC24A image;
EMatrixCode code;
EGenericDrawAdapter adapter(image);
code.DrawPosition(adapter);
```