CamiTK Action API Change: before/after apply (#20) · Issues · CamiTK / CamiTK Community Edition

CamiTK Action API Change: before/after apply


As a	CamiTK developer
I would like to	homogenize what is done before and after an action is called
So that	I can add useful behaviour (e.g., reset progress bar and wait cursor, auto application refresh is needed) and quickly add new improvement to CamiTK (e.g., automatic multithreading support for Action, better actionstatemachine/history management)
Epic	CamiTK API Cleaning

Follow up of #11

Description / Overview

Apply mechanism

Think about this API change to see it is reasonnable to change this

Merge applyInPipeline() and applyAndRegister() into applySlot()
- note : in applySlot change the cursor and restore it to normal independently of the return value
- note : add thread?
Action::apply() should now be a protected method
No signal should be connected to apply(), but connected to applyInPipeline() or applyAndRegister()

Other things to do when rewriting the `apply` mechanism

Encapsulate GUI update

This is also a great opportunity to add:

    // before apply
    QApplication::setOverrideCursor ( QCursor ( Qt::WaitCursor ) );
    Application::showStatusBarMessage(action->getName() + "...");
    Application::resetProgressBar();

    ...

    // after apply
    Application::resetProgressBar();
    Application::showStatusBarMessage ( "" );
    QApplication::restoreOverrideCursor();

Hide Application refresh

Dev should not have to include the Application headers. The use of Application::refresh() in very frequent actions → It might be a good idea to simplify action development, e.g.:

by adding a setAutoRefresh(bool) method. When called in the Action derived class constructor, Application::refresh() is automatically called after the apply() method... This will also simplify header inclusion (no more #include <Application.h> in action). By default the auto refresh is on (i.e. when the apply() method is finished, the application refreshes automatically)
and/or add a methode triggerApplicationRefresh() that can be called inside the apply() method

Others

There might be other common default things/behaviour/code that could be put before and after the apply() call to simplify the work of the action developer:

e.g. a setTreaded(bool) method that automatically controls if the action is ran in a thread or not...

Acceptance test

there are no Application::resetProgressBar() calls inside action code (in CamiTK CE), and the cursor is modified for all action automatically, and the progressbar is back to 0% at the end of the action.
there are no Application::refresh() calls inside action code
API documentation of class Apply explains pre and post process actions
there is a follow up story to implement multi-threading in action

Follow up of #11

## Description / Overview

### Apply mechanism

Think about this API change to see it is reasonnable to change this
- Merge `applyInPipeline()` and `applyAndRegister()` into `applySlot()`
    - note : in `applySlot` change the cursor and restore it to normal independently of the return value
    - note : add thread?
- `Action::apply()` should now be a protected method
- No signal should be connected to `apply()`, but connected to `applyInPipeline()` or `applyAndRegister()`

### Other things to do when rewriting the `apply` mechanism

#### Encapsulate GUI update

This is also a great opportunity to add:
```cpp
    // before apply
    QApplication::setOverrideCursor ( QCursor ( Qt::WaitCursor ) );
    Application::showStatusBarMessage(action->getName() + "...");
    Application::resetProgressBar();

...

// after apply
    Application::resetProgressBar();
    Application::showStatusBarMessage ( "" );
    QApplication::restoreOverrideCursor();
```

#### Hide Application refresh

Dev should not have to include the `Application` headers.
The use of `Application::refresh()` in very frequent actions
→ It might be a good idea to simplify action development, e.g.:
- by adding a `setAutoRefresh(bool)` method. When called in the `Action` derived class constructor, `Application::refresh()` is automatically called after the `apply()` method...
This will also simplify header inclusion (no more `#include <Application.h>` in action). By default the auto refresh is on (i.e. when the `apply()` method is finished, the application refreshes automatically)
- and/or add a methode `triggerApplicationRefresh()` that can be called inside the `apply()` method

#### Others

There might be other common default things/behaviour/code that could be put before and after the `apply()` call to simplify the work of the action developer:
- e.g. a `setTreaded(bool)` method that automatically controls if the action is ran in a thread or not...

## Acceptance test

- [ ] there are no `Application::resetProgressBar()` calls inside action code (in CamiTK CE), and the cursor is modified for all action automatically, and the progressbar is back to 0% at the end of the action. 
- [ ] there are no `Application::refresh()` calls inside action code
- [ ] API documentation of class `Apply` explains pre and post process actions
- [ ] there is a follow up story to implement multi-threading in action

Edited Jun 12, 2018 by Emmanuel Promayon

Discussion
Designs

The one place for your designs

To enable design management, you'll need to meet the requirements. If you need help, reach out to our support team for assistance.