Commontk - User contributions [en]

Contributing to CTK

2012-09-20T19:55:40Z

Danielle.pace:

The present document aims at describing how a developer should contribute to CTK.

* The source code of CTK is currently hosted on Github [http://github.com]. See http://github.com/commonth/CTK

* It's also assumed the developer is familiar with [http://git-scm.com/ git]. There are countless amount of resources available online. A good start point could the list presented on CMake/git page [http://www.cmake.org/Wiki/CMake/Git#Resources].

* We use a topic-based workflow as documented [http://public.kitware.com/Wiki/Git/Workflow/Topic here] and thus define integration branches:
** '''master''' Release preparation; starting point for new features (default)
** <del>'''next''' Development; new features published here first </del>

* We also accept commit following the more classic rebase workflow. See [http://unethicalblogger.com/2010/04/02/a-rebase-based-workflow.html]

= Prerequisites =
* [https://github.com/signup/free Create an account on github.com]
* Fork http://github.com/commontk/CTK
* Introduce yourself
$ git config --global user.name "Your Name"
$ git config --global user.email "you@yourdomain.com"
* Use correct line endings ([http://help.github.com/dealing-with-lineendings/ more info])
[On Linux] $ git config --global core.autocrlf input
[On Windows] $ git config --global core.autocrlf true

= Checkout your fork =
cd MyProject
git clone git@github.com:'''<MYACCOUNT>'''/CTK.git
cd CTK
git remote add origin git@github.com:'''<MYACCOUNT>'''/CTK.git
git remote add upstream git@github.com:commontk/CTK.git

= Publishing your branch =
* Having your own fork CTK allows you to backup and publish your work avoiding the ''urge to merge'' [http://public.kitware.com/Wiki/Git/Workflow/Topic#Urge_to_Merge]
git checkout -b YYY-new-feature
hack, hack, hack, add, commit
git push origin topic1:refs/heads/YYY-new-feature

* Note that <code>YYY</code> reference an issue entered in the tracker.

* As a shortcut, you could also enter the following. Some useful script are also available [http://git-wt-commit.rubyforge.org/ here]:
git config branch.topic1.remote origin
git config branch.topic1.merge refs/heads/YYY-new-feature

* Then, from the topic branch ''YYY-new-feature'', you could just enter the following to backup/publish your work:
git push

* To delete a branch from your fork:
git push origin :YYY-new-feature

= Checkout a branch from a different fork =
* You may want to collaborate with an other developer and work conjointly on a feature.
* Let's say, ''jcfr'' published the branch ''awesome_feature'' on his fork. You should do the following to check out his branch:
git remote add jcfr git://github.com/jcfr/CTK.git
git fetch jcfr
git checkout -b awesome_feature refs/remotes/jcfr/awesome_feature
or
git checkout -b awesome_feature jcfr/awesome_feature
* You should now have a local branch named awesome_feature. You can now add, commit and publish your work.

= Sync your topic branch =
* If a collaborator previously checked out your published branch, committed some changes, then published a revised branch on his github fork, you may want to grab its changes.
* Different ways:
1) If you didn't work on your branch, you could do the following:
git fetch jcfr
git checkout my_topic
git merge jcfr/my_topic

2) If you worked on your branch while your collaborator was working, you may want to select only the commit your collaborator pushed on his fork:

git fetch jcfr
git checkout my_topic
git cherry-pick <sha1> # sha1 identifying a specific commit

= Integrate your new feature =
* Initially, your feature should be integrated to '''next'''.
* To integrate your change to '''next''', you could follow the steps listed below. More details are also available [http://public.kitware.com/Wiki/Git/Workflow/Topic#New_Topic here].
git fetch upstream # Retrieve change from upstream repository
git checkout next # Checkout your local "next" branch
git merge upstream # Make sure your local branch is up-to-date.
git merge new_feature # Merge locally to "next" - Your changes are now integrated
git push upstream # Publish your change on the official repository
git push origin # Publish your change on your fork

* After it has been validated and tested, it could be integrated to '''master'''. More details [http://public.kitware.com/Wiki/Git/Workflow/Topic#Mature_Topic here].
Repeat the command listed above changing "next" into "master"



= Git Commit Style =

* Write very descriptive and concise first line summary of your commit
** try to stick to 50 characters max (no more than 65)
** do not use 'COMP' 'ENH' etc. (these cut into your 50 characters)
** summary should be a complete English sentence starting with a capital letter (terminating period is optional)
* Include a blank line after the summary and then a more detailed multi-line description (72 character max line length)
* In the body of the commit message, include #123 where 123 is the issue number. If a final commit fixes the issue, include "Fixes #123" or "Closes #123" in the commit message.
* Use <code>git merge --log --no-ff <topicname></code> (this keeps the logs messages of the merged branch)

= CTK Coding Style =
The overall policy is to follow the coding conventions of the parent classes unless there is an accepted CTK exception to improve consistency or usability (to account for inconsistency in the parent class system).

* If you are writing a widget that inherits from QObject, all your code should follow Qt coding conventions.
** Use the [http://www.commontk.org/docs/html/CorePimpl.html Private Implementation approach ("PIMPL")] '''except''' make the member variables of your private class begin with a capital letter. This means that when you create a widget using the QtDesigner, you must rename the widget to a local name that begins with a capital letter (since this will be an instance variable in your private implementation).

* Use ''virtual'' keyword also in derived class. Doing so improve readability of the code.

* Use const reference if it applies. For example:
<syntaxhighlight lang="cpp-qt">
void setName(const QString& newName); // better
void setName(QString newName); // poor
</syntaxhighlight>

* Use ''comment line'' separator. For example:
<syntaxhighlight lang="cpp-qt">
...

//----------------------------------------------------------------------------
void Foo::setName(const QString& newName)
{
Q_D(Foo);
d->Name = newName;
}

//----------------------------------------------------------------------------
QString Foo::name() const
{
Q_D(const Foo);
return d->Name;
}
...
</syntaxhighlight>

* The following statements ''for'', ''while'', ''switch'', ''if'', ''else'', ''try'', ''catch'' should, most of time, be multi-line. The brackets should also be indented with 2 spaces. For example:
<syntaxhighlight lang="cpp-qt">

//----------------------------------------------------------------------------
bool Foo::doSomething(int count)
{
// Better
for(int i=1; i < count; ++i)
{
if (i == 100)
{
qDebug() << "i = 100";
break;
}
}

// Poor
for(int i=1; i < count; ++i)
if (i == 100) { qDebug() << "i = 100"; break; }
}

</syntaxhighlight>
* Within CMakeLists.txt files, source/header file names should be sorted alphabetically. It also applies with inclusion order in header/implementation files
* [http://marcmutz.wordpress.com/effective-qt/prefer-to-use-normalised-signalslot-signatures/ Prefer to use normalised signal/slot signatures]

= FAQ =
* What the meaning of ''fatal: The current branch master is not tracking anything.'' ?

Documentation/ctkWorkflowWidget

2011-01-13T17:46:34Z

Danielle.pace:

== Summary ==

* Image analysis and image guided therapy procedures often have fairly complicated workflows
* CTK's workflow manager and workflow widgets provide a mechanism to construct workflows, display the appropriate user interface for each step, validatee user input and transition appropriately between steps of the workflow
* They use Qt's state machine implementation, with an additional CTK workflow manager layer

== Workflow classes ==
* Core workflow functionality (no widgets):
** [https://github.com/commontk/CTK/tree/master/Libs/Core/ctkWorkflowStep.h ctkWorkflowStep]: a step in the workflow
** [https://github.com/commontk/CTK/tree/master/Libs/Core/ctkWorkflow.h ctkWorkflow]: the workflow
** [https://github.com/commontk/CTK/tree/master/Libs/ctkWorkflowTransition.h ctkWorkflowTransition]: a transition in the workflow
* Workflows associated with widgets:
** [https://github.com/commontk/CTK/tree/master/Libs/Widgets/ctkWorkflowWidgetStep.h ctkWorkflowWidgetStep]: a step in the workflow with a user interface
** [https://github.com/commontk/CTK/tree/master/Libs/Widgets/ctkWorkflowWidget.h ctkWorkflowWidget]: a workflow with a user interface
** [https://github.com/commontk/CTK/tree/master/Libs/Widgets/ctkWorkflowStackedWidget.h ctkWorkflowStackedWidget]: a workflow with a user interface with many pages, based on a QStackedWidget
** [https://github.com/commontk/CTK/tree/master/Libs/Widgets/ctkWorkflowTabWidget.h ctkWorkflowTabWidget]: a workflow with a user interface with many pages, based on a QTabWidget
** [https://github.com/commontk/CTK/tree/master/Libs/Widgets/ctkWorkflowGroupBox.h ctkWorkflowGroupBox]: organizes display of the user interface for a particular step, including a subtitle, pre-text, client area, post-text and error text
** [https://github.com/commontk/CTK/tree/master/Libs/Widgets/ctkWorkflowButtonBoxWidget.h ctkWorkflowButtonBoxWidget]: a widget containing "next", "back" and "jump step" buttons

== To define a new workflow step with a user interface ==
* Method 1: derive ctkWorkflowWidgetStep:
** Implement validate(): evaluates user input and returns true if valid, false if not. Emits validateComplete(int) when finished.
** Implement entryProcessing(): processing that is done when entering the step. Emits entryProcessingComplete() when finished.
** Implement exitProcessing(): processing that is done when exiting the step. Emits exitProcessingComplete() when finished.
** Either:
*** Implement populateStepWidgetsList(QList<QWidget*>& stepWidgetsList): add the step's widgets to the given list; by default they will be displayed vertically in the order in which they were added. Emits populateStepWidgetsListComplete() when finished.
*** Implement showUserInterface() and hideUserInterface(): for more control over the step's UI. Emits showUserInterfaceComplete() and hideUserInterfaceComplete(), respectively, when finished.

* Method 2: use signals and slots
** Create an object that derives QObject
** Implement slots that mimic the functionality of validate() / entryProcessing() / exitProcessing() / populateStepWidgetsList() / showUserInterface() / hideUserInterface(), and which emit a signal when completed
** Use regular ctkWorkflowWidgetSteps in the workflow, and set their hasXXXCommands (ex. hasValidateCommand) to 1
** Connect your object's signals/slots to those of the steps/workflow
** When the workflow runs, it will emit the relevant signals to trigger your QObject's slots, which will then send indicate completion by the signals they send.

== Examples ==

* Examples of how to create a custom workflow step:
** Method 1: [https://github.com/commontk/CTK/tree/master/Libs/Widgets/Testing/Cpp/ctkExampleDerivedWorkflowWidgetStep.h ctkExampleDerivedWorkflowWidgetStep.h] and [https://github.com/commontk/CTK/tree/master/Libs/Widgets/Testing/Cpp/ctkExampleDerivedWorkflowWidgetStep.cpp ctkExampleDerivedWorkflowWidgetStep.cpp]: custom step created by deriving [https://github.com/commontk/CTK/tree/master/Libs/Widgets/ctkWorkflowWidgetStep.h ctkWorkflowWidgetStep]
** Method 2: [https://github.com/commontk/CTK/tree/master/Libs/Widgets/Testing/Cpp/ctkExampleWorkflowWidgetStepUsingSignalsAndSlots.h ctkExampleWorkflowWidgetStepUsingSignalsAndSlots.h] and [hhttps://github.com/commontk/CTK/tree/master/Libs/Widgets/Testing/Cpp/ctkExampleWorkflowWidgetStepUsingSignalsAndSlots.cpp ctkExampleWorkflowWidgetStepUsingSignalsAndSlots.cpp]: custom step created by implementing the step's functionality in a class derived from QObject, and communicating with the workflow using its signal-slot mechanism
* Examples of how to create a workflow:
** Method 1: [https://github.com/commontk/CTK/tree/master/Libs/Widgets/Testing/Cpp/ctkExampleUseOfWorkflowWidgetUsingDerivedSteps.cpp ctkExampleUseOfWorkflowWidgetUsingDerivedSteps]: builds a simple workflow using custom steps that derive ctkWorkflowWidgetStep
** Method 2: [https://github.com/commontk/CTK/tree/master/Libs/Widgets/Testing/Cpp/ctkExampleUseOfWorkflowWidgetUsingSignalsAndSlots.cpp ctkExampleUseOfWorkflowWidgetUsingSignalsAndSlots]: builds a simple workflow using custom steps that communicate with the workflow using its signal-slot mechanism
* Examples of the workflow manager in Slicer 4:
** EM Segmenter module

== Overview of state diagram underlying ctkWorkflow ==
* Processing step = handles user interaction, and supports additional processing (ex. image processing) as well
* Validation step = evaluates the success of the processing step
* Currently supported transitions:
** Transition to the next step
** Transition to the previous step
** Transition to a "finish" step
*** Equivalent to doing "next, next, next, next..." until you hit the finish step: completes all entry/exit processing associated with each step encountered on the way to the finish step, without showing user interface.
*** Success relies on the suitability of the default processing, parameters, etc
*** "Blocking" steps, ex. those requiring user interaction, will prohibit success in transitioning to the finish step
*** On success: transitions back to the step where the attempt to go to the finish step was initiated, so that the user can perform additional customization from there if needed.
*** On failure: remains in the step whose validate() returned failure, and shows its user interface.

== GUI implementation in ctkWorkflowWidget ==
* workflowWidget->addWidget(QWidget* widget): adds a widget to the clientArea
* workflowWidget->showWidget(QWidget* widget): shows the clientArea (i.e. for ctkWorkflowStackedWidget and ctkWorkflowTabWidget, ensures that the correct "page" is shownl

== Examples ==

<pre>
ctkworkflow w;
ctkWorkflowStep s1("select_image");
ctkWorkflowStep s2("input_new_size");
ctkWorkflowStep s3("display_resized_image");

w.addTransition(&s1, &s2);
w.addTransition(&s2, &s3);

</pre>

= Workflow layout =
[[File:workflowWidgetLayout.png]]

= Branching workflows =

<pre>
s3----s4 "simple"
/
s0----s1----s2
\
s5----s6 "advanced"
</pre>
Associated code:
<pre>
ctkWorkflow w;

ctkWorkflowStep s0;
...
ctkWorkflowStep s6;

w.setInitialStep(s0); [Ideally - should be optional]

w.addTransition(s0, s1);
w.addTransition(s1, s2);
w.addTransition(s2, s3, ctkWorkflow::BiDirectionnal, "simple");
w.addTransition(s3, s4);
w.addTransition(s2, s5, ctkWorkflow::BiDirectionnal, "advanced");
w.addTransition(s5, s6);
</pre>

Conditional branching:

<pre>
[signal] void validationComplete(bool isValid, const QString& branchId)
</pre>

* '''ctkWorkflow::validate() doesn't give branchId:'''
** Single transition:
*** transition created without branchId: post transition
*** transition created with branchId: post transition

** Multiple transitions:
*** ''(incorrect usage)'' transitions created with branchIds: use first transition that was added

* '''ctkWorkflow::validate() gives branchId:'''
** Single transition:
*** transition created without branchId: post transition ''(workflow overrides step)''
*** transition created with branchId: conditional transition based on match, if no match then stay in current step
** Multiple transitions:
*** transitions created with branchIds: conditional transition based on match, if no match then stay in current step

Documentation/ctkWorkflowWidget

2011-01-13T17:44:35Z

Danielle.pace:

== Summary ==

* Image analysis and image guided therapy procedures often have fairly complicated workflows
* CTK's workflow manager and workflow widgets provide a mechanism to construct workflows, display the appropriate user interface for each step, validatee user input and transition appropriately between steps of the workflow
* They use Qt's state machine implementation, with an additional CTK workflow manager layer

== Workflow classes ==
* Core workflow functionality (no widgets):
** [https://github.com/commontk/CTK/tree/master/Libs/Core/ctkWorkflowStep.h ctkWorkflowStep]: a step in the workflow
** [https://github.com/commontk/CTK/tree/master/Libs/Core/ctkWorkflow.h ctkWorkflow]: the workflow
** [https://github.com/commontk/CTK/tree/master/Libs/ctkWorkflowTransition.h ctkWorkflowTransition]: a transition in the workflow
* Workflows associated with widgets:
** [https://github.com/commontk/CTK/tree/master/Libs/Widgets/ctkWorkflowWidgetStep.h ctkWorkflowWidgetStep]: a step in the workflow with a user interface
** [https://github.com/commontk/CTK/tree/master/Libs/Widgets/ctkWorkflowWidget.h ctkWorkflowWidget]: a workflow with a user interface
** [https://github.com/commontk/CTK/tree/master/Libs/Widgets/ctkWorkflowStackedWidget.h ctkWorkflowStackedWidget]: a workflow with a user interface with many pages, based on a QStackedWidget
** [https://github.com/commontk/CTK/tree/master/Libs/Libs/Widgets/ctkWorkflowTabWidget.h ctkWorkflowTabWidget]: a workflow with a user interface with many pages, based on a QTabWidget
** [https://github.com/commontk/CTK/tree/master/Libs/Libs/Widgets/ctkWorkflowGroupBox.h ctkWorkflowGroupBox]: organizes display of the user interface for a particular step, including a subtitle, pre-text, client area, post-text and error text
** [https://github.com/commontk/CTK/tree/master/Libs/Libs/Widgets/ctkWorkflowButtonBoxWidget.h ctkWorkflowButtonBoxWidget]: a widget containing "next", "back" and "jump step" buttons

== To define a new workflow step with a user interface ==
* Method 1: derive ctkWorkflowWidgetStep:
** Implement validate(): evaluates user input and returns true if valid, false if not. Emits validateComplete(int) when finished.
** Implement entryProcessing(): processing that is done when entering the step. Emits entryProcessingComplete() when finished.
** Implement exitProcessing(): processing that is done when exiting the step. Emits exitProcessingComplete() when finished.
** Either:
*** Implement populateStepWidgetsList(QList<QWidget*>& stepWidgetsList): add the step's widgets to the given list; by default they will be displayed vertically in the order in which they were added. Emits populateStepWidgetsListComplete() when finished.
*** Implement showUserInterface() and hideUserInterface(): for more control over the step's UI. Emits showUserInterfaceComplete() and hideUserInterfaceComplete(), respectively, when finished.

* Method 2: use signals and slots
** Create an object that derives QObject
** Implement slots that mimic the functionality of validate() / entryProcessing() / exitProcessing() / populateStepWidgetsList() / showUserInterface() / hideUserInterface(), and which emit a signal when completed
** Use regular ctkWorkflowWidgetSteps in the workflow, and set their hasXXXCommands (ex. hasValidateCommand) to 1
** Connect your object's signals/slots to those of the steps/workflow
** When the workflow runs, it will emit the relevant signals to trigger your QObject's slots, which will then send indicate completion by the signals they send.

== Examples ==

* Examples of how to create a custom workflow step:
** Method 1: [https://github.com/commontk/CTK/tree/master/Libs/Widgets/Testing/Cpp/ctkExampleDerivedWorkflowWidgetStep.h ctkExampleDerivedWorkflowWidgetStep.h] and [https://github.com/commontk/CTK/tree/master/Libs/Widgets/Testing/Cpp/ctkExampleDerivedWorkflowWidgetStep.cpp ctkExampleDerivedWorkflowWidgetStep.cpp]: custom step created by deriving [https://github.com/commontk/CTK/tree/master/Libs/Widgets/ctkWorkflowWidgetStep.h ctkWorkflowWidgetStep]
** Method 2: [https://github.com/commontk/CTK/tree/master/Libs/Widgets/Testing/Cpp/ctkExampleWorkflowWidgetStepUsingSignalsAndSlots.h ctkExampleWorkflowWidgetStepUsingSignalsAndSlots.h] and [hhttps://github.com/commontk/CTK/tree/master/Libs/Widgets/Testing/Cpp/ctkExampleWorkflowWidgetStepUsingSignalsAndSlots.cpp ctkExampleWorkflowWidgetStepUsingSignalsAndSlots.cpp]: custom step created by implementing the step's functionality in a class derived from QObject, and communicating with the workflow using its signal-slot mechanism
* Examples of how to create a workflow:
** Method 1: [https://github.com/commontk/CTK/tree/master/Libs/Widgets/Testing/Cpp/ctkExampleUseOfWorkflowWidgetUsingDerivedSteps.cpp ctkExampleUseOfWorkflowWidgetUsingDerivedSteps]: builds a simple workflow using custom steps that derive ctkWorkflowWidgetStep
** Method 2: [https://github.com/commontk/CTK/tree/master/Libs/Widgets/Testing/Cpp/ctkExampleUseOfWorkflowWidgetUsingSignalsAndSlots.cpp ctkExampleUseOfWorkflowWidgetUsingSignalsAndSlots]: builds a simple workflow using custom steps that communicate with the workflow using its signal-slot mechanism
* Examples of the workflow manager in Slicer 4:
** EM Segmenter module

== Overview of state diagram underlying ctkWorkflow ==
* Processing step = handles user interaction, and supports additional processing (ex. image processing) as well
* Validation step = evaluates the success of the processing step
* Currently supported transitions:
** Transition to the next step
** Transition to the previous step
** Transition to a "finish" step
*** Equivalent to doing "next, next, next, next..." until you hit the finish step: completes all entry/exit processing associated with each step encountered on the way to the finish step, without showing user interface.
*** Success relies on the suitability of the default processing, parameters, etc
*** "Blocking" steps, ex. those requiring user interaction, will prohibit success in transitioning to the finish step
*** On success: transitions back to the step where the attempt to go to the finish step was initiated, so that the user can perform additional customization from there if needed.
*** On failure: remains in the step whose validate() returned failure, and shows its user interface.

== GUI implementation in ctkWorkflowWidget ==
* workflowWidget->addWidget(QWidget* widget): adds a widget to the clientArea
* workflowWidget->showWidget(QWidget* widget): shows the clientArea (i.e. for ctkWorkflowStackedWidget and ctkWorkflowTabWidget, ensures that the correct "page" is shownl

== Examples ==

<pre>
ctkworkflow w;
ctkWorkflowStep s1("select_image");
ctkWorkflowStep s2("input_new_size");
ctkWorkflowStep s3("display_resized_image");

w.addTransition(&s1, &s2);
w.addTransition(&s2, &s3);

</pre>

= Workflow layout =
[[File:workflowWidgetLayout.png]]

= Branching workflows =

<pre>
s3----s4 "simple"
/
s0----s1----s2
\
s5----s6 "advanced"
</pre>
Associated code:
<pre>
ctkWorkflow w;

ctkWorkflowStep s0;
...
ctkWorkflowStep s6;

w.setInitialStep(s0); [Ideally - should be optional]

w.addTransition(s0, s1);
w.addTransition(s1, s2);
w.addTransition(s2, s3, ctkWorkflow::BiDirectionnal, "simple");
w.addTransition(s3, s4);
w.addTransition(s2, s5, ctkWorkflow::BiDirectionnal, "advanced");
w.addTransition(s5, s6);
</pre>

Conditional branching:

<pre>
[signal] void validationComplete(bool isValid, const QString& branchId)
</pre>

* '''ctkWorkflow::validate() doesn't give branchId:'''
** Single transition:
*** transition created without branchId: post transition
*** transition created with branchId: post transition

** Multiple transitions:
*** ''(incorrect usage)'' transitions created with branchIds: use first transition that was added

* '''ctkWorkflow::validate() gives branchId:'''
** Single transition:
*** transition created without branchId: post transition ''(workflow overrides step)''
*** transition created with branchId: conditional transition based on match, if no match then stay in current step
** Multiple transitions:
*** transitions created with branchIds: conditional transition based on match, if no match then stay in current step

Documentation/ctkWorkflowWidget

2011-01-13T17:42:28Z

Danielle.pace:

== Summary ==

* Image analysis and image guided therapy procedures often have fairly complicated workflows
* CTK's workflow manager and workflow widgets provide a mechanism to construct workflows, display the appropriate user interface for each step, validatee user input and transition appropriately between steps of the workflow
* They use Qt's state machine implementation, with an additional CTK workflow manager layer

== Workflow classes ==
* Core workflow functionality (no widgets):
** [https://github.com/commontk/CTK/tree/master/Libs/Core/ctkWorkflowStep.h ctkWorkflowStep]: a step in the workflow
** [https://github.com/commontk/CTK/tree/master/Libs/Core/ctkWorkflow.h ctkWorkflow]: the workflow
** [https://github.com/commontk/CTK/tree/master/Libs/ctkWorkflowTransition.h ctkWorkflowTransition]: a transition in the workflow
* Workflows associated with widgets:
** [https://github.com/commontk/CTK/tree/master/Libs/Widgets/ctkWorkflowWidgetStep.h ctkWorkflowWidgetStep]: a step in the workflow with a user interface
** [https://github.com/commontk/CTK/tree/master/Libs/Widgets/ctkWorkflowWidget.h ctkWorkflowWidget]: a workflow with a user interface
** [https://github.com/commontk/CTK/tree/master/Libs/Widgets/ctkWorkflowStackedWidget.h ctkWorkflowStackedWidget]: a workflow with a user interface with many pages, based on a QStackedWidget
** [https://github.com/commontk/CTK/tree/master/Libs/Libs/Widgets/ctkWorkflowTabWidget.h ctkWorkflowTabWidget]: a workflow with a user interface with many pages, based on a QTabWidget
** [https://github.com/commontk/CTK/tree/master/Libs/Libs/Widgets/ctkWorkflowGroupBox.h ctkWorkflowGroupBox]: organizes display of the user interface for a particular step, including a subtitle, pre-text, client area, post-text and error text
** [https://github.com/commontk/CTK/tree/master/Libs/Libs/Widgets/ctkWorkflowButtonBoxWidget.h ctkWorkflowButtonBoxWidget]: a widget containing "next", "back" and "jump step" buttons

== To define a new workflow step with a user interface ==
* Method 1: derive ctkWorkflowWidgetStep:
** Implement validate(): evaluates user input and returns true if valid, false if not. Emits validateComplete(int) when finished.
** Implement entryProcessing(): processing that is done when entering the step. Emits entryProcessingComplete() when finished.
** Implement exitProcessing(): processing that is done when exiting the step. Emits exitProcessingComplete() when finished.
** Either:
*** Implement populateStepWidgetsList(QList<QWidget*>& stepWidgetsList): add the step's widgets to the given list; by default they will be displayed vertically in the order in which they were added. Emits populateStepWidgetsListComplete() when finished.
*** Implement showUserInterface() and hideUserInterface(): for more control over the step's UI. Emits showUserInterfaceComplete() and hideUserInterfaceComplete(), respectively, when finished.

* Method 2: use signals and slots
** Create an object that derives QObject
** Implement slots that mimic the functionality of validate() / entryProcessing() / exitProcessing() / populateStepWidgetsList() / showUserInterface() / hideUserInterface(), and which emit a signal when completed
** Use regular ctkWorkflowWidgetSteps in the workflow, and set their hasXXXCommands (ex. hasValidateCommand) to 1
** Connect your object's signals/slots to those of the steps/workflow
** When the workflow runs, it will emit the relevant signals to trigger your QObject's slots, which will then send indicate completion by the signals they send.

== Examples ==

* examples of how to create a custom workflow step:
** Method 1: [https://github.com/commontk/CTK/tree/master/Libs/Widgets/Testing/Cpp/ctkExampleDerivedWorkflowWidgetStep.h ctkExampleDerivedWorkflowWidgetStep.h] and [https://github.com/commontk/CTK/tree/master/Libs/Widgets/Testing/Cpp/ctkExampleDerivedWorkflowWidgetStep.cpp ctkExampleDerivedWorkflowWidgetStep.cpp]: custom step created by deriving [https://github.com/commontk/CTK/tree/master/Libs/Widgets/ctkWorkflowWidgetStep.h ctkWorkflowWidgetStep]
** Method 2: [https://github.com/commontk/CTK/tree/master/Libs/Widgets/Testing/Cpp/ctkExampleWorkflowWidgetStepUsingSignalsAndSlots.h ctkExampleWorkflowWidgetStepUsingSignalsAndSlots.h] and [hhttps://github.com/commontk/CTK/tree/master/Libs/Widgets/Testing/Cpp/ctkExampleWorkflowWidgetStepUsingSignalsAndSlots.cpp ctkExampleWorkflowWidgetStepUsingSignalsAndSlots.cpp]: custom step created by implementing the step's functionality in a class derived from QObject, and communicating with the workflow using its signal-slot mechanism
* examples of how to create a workflow:
** Method 1: [hhttps://github.com/commontk/CTK/tree/master/Libs/Widgets/Testing/Cpp/ctkExampleUseOfWorkflowWidgetUsingDerivedSteps.cpp ctkExampleUseOfWorkflowWidgetUsingDerivedSteps]: builds a simple workflow using custom steps that derive ctkWorkflowWidgetStep
** Method 2: [https://github.com/commontk/CTK/tree/master/Libs/Widgets/Testing/Cpp/ctkExampleUseOfWorkflowWidgetUsingSignalsAndSlots.cpp ctkExampleUseOfWorkflowWidgetUsingSignalsAndSlots]: builds a simple workflow using custom steps that communicate with the workflow using its signal-slot mechanism

== Overview of state diagram underlying ctkWorkflow ==
* Processing step = handles user interaction, and supports additional processing (ex. image processing) as well
* Validation step = evaluates the success of the processing step
* Currently supported transitions:
** Transition to the next step
** Transition to the previous step
** Transition to a "finish" step
*** Equivalent to doing "next, next, next, next..." until you hit the finish step: completes all entry/exit processing associated with each step encountered on the way to the finish step, without showing user interface.
*** Success relies on the suitability of the default processing, parameters, etc
*** "Blocking" steps, ex. those requiring user interaction, will prohibit success in transitioning to the finish step
*** On success: transitions back to the step where the attempt to go to the finish step was initiated, so that the user can perform additional customization from there if needed.
*** On failure: remains in the step whose validate() returned failure, and shows its user interface.

== GUI implementation in ctkWorkflowWidget ==
* workflowWidget->addWidget(QWidget* widget): adds a widget to the clientArea
* workflowWidget->showWidget(QWidget* widget): shows the clientArea (i.e. for ctkWorkflowStackedWidget and ctkWorkflowTabWidget, ensures that the correct "page" is shownl

== Examples ==

<pre>
ctkworkflow w;
ctkWorkflowStep s1("select_image");
ctkWorkflowStep s2("input_new_size");
ctkWorkflowStep s3("display_resized_image");

w.addTransition(&s1, &s2);
w.addTransition(&s2, &s3);

</pre>

= Workflow layout =
[[File:workflowWidgetLayout.png]]

= Branching workflows =

API:

* addTransition(ctkWorkflowStep* originStep, ctkWorkflowStep* destinationStep, const ctkWorkflow::TransitionType& transitionType, const QString& branchId = "")
** must give a branchId if destinationStep is the 2nd/3rd/4th, etc step added to originStep
<pre>
s3----s4 "simple"
/
s0----s1----s2
\
s5----s6 "advanced"
</pre>
Associated code:
<pre>
ctkWorkflow w;

ctkWorkflowStep s0;
...
ctkWorkflowStep s6;

w.setInitialStep(s0); [Ideally - should be optional]

w.addTransition(s0, s1);
w.addTransition(s1, s2);
w.addTransition(s2, s3, ctkWorkflow::BiDirectionnal, "simple");
w.addTransition(s3, s4);
w.addTransition(s2, s5, ctkWorkflow::BiDirectionnal, "advanced");
w.addTransition(s5, s6);
</pre>

Conditional branching:

<pre>
[signal] void validationComplete(bool isValid, const QString& branchId)
</pre>

* '''ctkWorkflow::validate() doesn't give branchId:'''
** Single transition:
*** transition created without branchId: post transition
*** transition created with branchId: post transition

** Multiple transitions:
*** ''(incorrect usage)'' transitions created with branchIds: use first transition that was added

* '''ctkWorkflow::validate() gives branchId:'''
** Single transition:
*** transition created without branchId: post transition ''(workflow overrides step)''
*** transition created with branchId: conditional transition based on match, if no match then stay in current step
** Multiple transitions:
*** transitions created with branchIds: conditional transition based on match, if no match then stay in current step

File:WorkflowWidgetLayout.png

2011-01-13T17:32:43Z

Danielle.pace:

Documentation/ctkWorkflowWidget

2011-01-13T17:30:03Z

Danielle.pace: Created page with '== Summary == * Image analysis and image guided therapy procedures often have fairly complicated workflows * CTK's workflow manager and workflow widgets provide a mechanism to c…'

== Summary ==

* Image analysis and image guided therapy procedures often have fairly complicated workflows
* CTK's workflow manager and workflow widgets provide a mechanism to construct workflows, display the appropriate user interface for each step, validatee user input and transition appropriately between steps of the workflow
* They use Qt's state machine implementation, with an additional CTK workflow manager layer

== Workflow classes ==
* Core workflow functionality (no widgets):
** [https://github.com/commontk/CTK/tree/master/Libs/Core/ctkWorkflowStep.h ctkWorkflowStep]: a step in the workflow
** [https://github.com/commontk/CTK/tree/master/Libs/Core/ctkWorkflow.h ctkWorkflow]: the workflow
** [https://github.com/commontk/CTK/tree/master/Libs/ctkWorkflowTransition.h ctkWorkflowTransition]: a transition in the workflow
* Workflows associated with widgets:
** [https://github.com/commontk/CTK/tree/master/Libs/Widgets/ctkWorkflowWidgetStep.h ctkWorkflowWidgetStep]: a step in the workflow with a user interface
** [https://github.com/commontk/CTK/tree/master/Libs/Widgets/ctkWorkflowWidget.h ctkWorkflowWidget]: a workflow with a user interface
** [https://github.com/commontk/CTK/tree/master/Libs/Widgets/ctkWorkflowStackedWidget.h ctkWorkflowStackedWidget]: a workflow with a user interface with many pages, based on a QStackedWidget
** [https://github.com/commontk/CTK/tree/master/Libs/Libs/Widgets/ctkWorkflowTabWidget.h ctkWorkflowTabWidget]: a workflow with a user interface with many pages, based on a QTabWidget
** [https://github.com/commontk/CTK/tree/master/Libs/Libs/Widgets/ctkWorkflowGroupBox.h ctkWorkflowGroupBox]: organizes display of the user interface for a particular step, including a subtitle, pre-text, client area, post-text and error text
** [https://github.com/commontk/CTK/tree/master/Libs/Libs/Widgets/ctkWorkflowButtonBoxWidget.h ctkWorkflowButtonBoxWidget]: a widget containing "next", "back" and "jump step" buttons

== To define a new workflow step with a user interface ==
* Method 1: derive ctkWorkflowWidgetStep:
** Implement validate(): evaluates user input and returns true if valid, false if not. Emits validateComplete(int) when finished.
** Implement entryProcessing(): processing that is done when entering the step. Emits entryProcessingComplete() when finished.
** Implement exitProcessing(): processing that is done when exiting the step. Emits exitProcessingComplete() when finished.
** Either:
*** Implement populateStepWidgetsList(QList<QWidget*>& stepWidgetsList): add the step's widgets to the given list; by default they will be displayed vertically in the order in which they were added. Emits populateStepWidgetsListComplete() when finished.
*** Implement showUserInterface() and hideUserInterface(): for more control over the step's UI. Emits showUserInterfaceComplete() and hideUserInterfaceComplete(), respectively, when finished.

* Method 2: use signals and slots
** Create an object that derives QObject
** Implement slots that mimic the functionality of validate() / entryProcessing() / exitProcessing() / populateStepWidgetsList() / showUserInterface() / hideUserInterface(), and which emit a signal when completed
** Use regular ctkWorkflowWidgetSteps in the workflow, and set their hasXXXCommands (ex. hasValidateCommand) to 1
** Connect your object's signals/slots to those of the steps/workflow
** When the workflow runs, it will emit the relevant signals to trigger your QObject's slots, which will then send indicate completion by the signals they send.

== Examples ==

* examples of how to create a custom workflow step:
** Method 1: [https://github.com/commontk/CTK/tree/master/Libs/Widgets/Testing/Cpp/ctkExampleDerivedWorkflowWidgetStep.h ctkExampleDerivedWorkflowWidgetStep.h] and [https://github.com/commontk/CTK/tree/master/Libs/Widgets/Testing/Cpp/ctkExampleDerivedWorkflowWidgetStep.cpp ctkExampleDerivedWorkflowWidgetStep.cpp]: custom step created by deriving [https://github.com/commontk/CTK/tree/master/Libs/Widgets/ctkWorkflowWidgetStep.h ctkWorkflowWidgetStep]
** Method 2: [https://github.com/commontk/CTK/tree/master/Libs/Widgets/Testing/Cpp/ctkExampleWorkflowWidgetStepUsingSignalsAndSlots.h ctkExampleWorkflowWidgetStepUsingSignalsAndSlots.h] and [hhttps://github.com/commontk/CTK/tree/master/Libs/Widgets/Testing/Cpp/ctkExampleWorkflowWidgetStepUsingSignalsAndSlots.cpp ctkExampleWorkflowWidgetStepUsingSignalsAndSlots.cpp]: custom step created by implementing the step's functionality in a class derived from QObject, and communicating with the workflow using its signal-slot mechanism
* examples of how to create a workflow:
** Method 1: [hhttps://github.com/commontk/CTK/tree/master/Libs/Widgets/Testing/Cpp/ctkExampleUseOfWorkflowWidgetUsingDerivedSteps.cpp ctkExampleUseOfWorkflowWidgetUsingDerivedSteps]: builds a simple workflow using custom steps that derive ctkWorkflowWidgetStep
** Method 2: [https://github.com/commontk/CTK/tree/master/Libs/Widgets/Testing/Cpp/ctkExampleUseOfWorkflowWidgetUsingSignalsAndSlots.cpp ctkExampleUseOfWorkflowWidgetUsingSignalsAndSlots]: builds a simple workflow using custom steps that communicate with the workflow using its signal-slot mechanism

== Overview of state diagram underlying ctkWorkflow ==
* Processing step = handles user interaction, and supports additional processing (ex. image processing) as well
* Validation step = evaluates the success of the processing step
* Currently supported transitions:
** Transition to the next step
** Transition to the previous step
** Transition to a "finish" step
*** Equivalent to doing "next, next, next, next..." until you hit the finish step: completes all entry/exit processing associated with each step encountered on the way to the finish step, without showing user interface.
*** Success relies on the suitability of the default processing, parameters, etc
*** "Blocking" steps, ex. those requiring user interaction, will prohibit success in transitioning to the finish step
*** On success: transitions back to the step where the attempt to go to the finish step was initiated, so that the user can perform additional customization from there if needed.
*** On failure: remains in the step whose validate() returned failure, and shows its user interface.

== GUI implementation in ctkWorkflowWidget ==
* workflowWidget->addWidget(QWidget* widget): adds a widget to the clientArea
* workflowWidget->showWidget(QWidget* widget): shows the clientArea (i.e. for ctkWorkflowStackedWidget and ctkWorkflowTabWidget, ensures that the correct "page" is shownl

== Examples ==

<pre>
ctkworkflow w;
ctkWorkflowStep s1("select_image");
ctkWorkflowStep s2("input_new_size");
ctkWorkflowStep s3("display_resized_image");

w.addTransition(&s1, &s2);
w.addTransition(&s2, &s3);

</pre>

= Workflow layout =
[[File:Projects-ARRA-SlicerEM-Developer-EMSegment_workflowWidgetLayout.png]]

= Branching workflows =

API:

* addTransition(ctkWorkflowStep* originStep, ctkWorkflowStep* destinationStep, const ctkWorkflow::TransitionType& transitionType, const QString& branchId = "")
** must give a branchId if destinationStep is the 2nd/3rd/4th, etc step added to originStep
<pre>
s3----s4 "simple"
/
s0----s1----s2
\
s5----s6 "advanced"
</pre>
Associated code:
<pre>
ctkWorkflow w;

ctkWorkflowStep s0;
...
ctkWorkflowStep s6;

w.setInitialStep(s0); [Ideally - should be optional]

w.addTransition(s0, s1);
w.addTransition(s1, s2);
w.addTransition(s2, s3, ctkWorkflow::BiDirectionnal, "simple");
w.addTransition(s3, s4);
w.addTransition(s2, s5, ctkWorkflow::BiDirectionnal, "advanced");
w.addTransition(s5, s6);
</pre>

Conditional branching:

<pre>
[signal] void validationComplete(bool isValid, const QString& branchId)
</pre>

* '''ctkWorkflow::validate() doesn't give branchId:'''
** Single transition:
*** transition created without branchId: post transition
*** transition created with branchId: post transition

** Multiple transitions:
*** ''(incorrect usage)'' transitions created with branchIds: use first transition that was added

* '''ctkWorkflow::validate() gives branchId:'''
** Single transition:
*** transition created without branchId: post transition ''(workflow overrides step)''
*** transition created with branchId: conditional transition based on match, if no match then stay in current step
** Multiple transitions:
*** transitions created with branchIds: conditional transition based on match, if no match then stay in current step

Documentation

2011-01-13T16:48:37Z

Danielle.pace:

[[Main Page|Back to CTK main page]]

=== Architectural Notes ===

Everything is open to discussion at this time.

Topics being discussed include the following
* [[Documentation/Whitepaper|Whitepaper]]
* [[Documentation/Architecture|Architecture ideas]]
* [[Documentation/ctkScene|ctkScene ideas]]
* [[Documentation/Events|Inter- and Intra-process events]]
* [[Documentation/Plugins_And_Modules|Plugins and Modules: pass data, parameters, and results]]
* [[Documentation/Interfacing_Via_OpenGL|Interfacing systems at the OpenGL level (i.e. VTK and OpenInventor)]]
* [[Documentation/Messaging | Messaging service for event management and system integration]]
* [[Documentation/DicomApplicationHosting | DICOM Suppl 118 / WG 23 compliant application hosting]]

=== Widgets ===
* [[Documentation/WidgetPlans|Plans for widgets]]
* [[Documentation/ImageGallery|Image Gallery]]
* [[Documentation/ctkTransferFunctionWidget|Transfer function widgets]]
* [[Documentation/ctkWorkflowWidget|Workflow widgets]]

=== Plugin Framework ===

* [[Documentation/PluginFramework_DesignDoc | Design Document]]
* [[Documentation/PluginFramework_Specifications | Specifications]]

=== Build System ===
* [[Documentation/BuildSystem_Description | Description]]