Documentation/CLI Support in CTK: Difference between revisions

From Commontk
Jump to navigationJump to search
mNo edit summary
 
(10 intermediate revisions by 4 users not shown)
Line 1: Line 1:
This page is a working draft and does not contain final information.
Command Line Interface (CLI) support in CTK will primarly focus on providing an API for working with existing CLI modules. Providing utilities and tools for creating CLI modules from scratch is a desired addition but there are no concrete plans for this yet. See [[Documentation/Command_Line_Interface]] for more general information about CLI modules.


Command Line Interface (CLI) support in CTK will primarly focus on providing an API for working with existing CLI modules. Providing utiltities and tools for creating CLI modules from scratch is a desired addition but there are no concrete plans for this yet.
=== Getting the Code ===


The code is available in the CTK master:


=== Experimental Code ===
https://github.com/commontk/CTK
 
Some experimental code can be found here:
 
https://github.com/commontk/CTK/tree/cli-module-support


Enable the following CMake options to be able to play with the code:
Enable the following CMake options to be able to play with the code:


* '''BUILD_TESTING''' (for creating CLI test modules)
* '''BUILD_TESTING''' (for creating CLI test modules)
* '''CTK_APP_ctkCommandLineModuleExplorer''' (small program allowing you to test-drive CLI modules using the CTK CLI module API)
* '''CTK_APP_ctkCommandLineModuleExplorer''' (small program allowing you to test-drive CLI modules using the CTK CLI module API, enables all the options below)
* '''CTK_BUILD_QTDESIGNER_PLUGINS''' (needed by the ctkCLIPluginExplorer to create a Qt GUI from the generated .ui files at runtime)
* '''CTK_LIB_CommandLineModules/Core''' (the CTK library providing the core CLI module API)
* '''CTK_LIB_CommandLineModules''' (the CTK library providing the CLI module API)
* '''CTK_LIB_CommandLineModules/Frontend/QtGui''' (the CTK library providing GUI generation using the Qt widgets)
* '''CTK_LIB_Widgets''' (used by the ctkCLIPluginExplorer to create a Qt GUI for the CLI module from the .ui file)
* '''CTK_LIB_CommandLineModules/Backend/LocalProcess''' (the CTK library for executing local executable files as command line modules)


=== API Design ===
=== API Design ===
This is a partially overview of the API design, showing the GUI generation process for the Qt front-end.


<graphviz>
<graphviz>
Line 47: Line 46:
   ];
   ];
   "ctkCLIModuleDescription" [
   "ctkCLIModuleDescription" [
   label = "{<f0> ctkCLIModuleDescription| <f1>}"
   label = "{<f0> ctkCmdLineModuleDescription| <f1>}"
   shape = "record"
   shape = "record"
   ];
   ];
Line 61: Line 60:
}
}
"xmlFile":f0:e -> "xmlFile":f0:ne [label = "XSD file check" ];
"xmlFile":f0:e -> "xmlFile":f0:ne [label = "XSD file check" ];
"xmlFile":f1 -> "uiFile":f0 [label = "XSL file" ];
"xmlFile":f1 -> "uiFile":f0 [label = "QtGui XSL file" ];
"xmlFile":f1 -> "uiFile":f0 [label = "" style=invis];
"xmlFile":f1 -> "uiFile":f0 [label = "" style=invis];
"xmlFile":f1 -> "ctkCLIModuleDescription":f0 [label=ctkModuleDescriptionParser];
"xmlFile":f1 -> "ctkCLIModuleDescription":f0 [label=ctkCmdLineModuleXmlParser];
"xmlFile":f1 -> "vtkMRMLParametersNode":f0 [label=ModuleDescriptionParser];
"ctkCLIModuleDescription":f1 -> "vtkMRMLParametersNode":f0 [label=create];
"uiFile":f1 -> "gui":f0 [label = QUILoader];
"uiFile":f1 -> "gui":f0 [label = QUiLoader];
"ctkCLIModuleDescription":f1:e -> "vtkMRMLParametersNode":f1:w [dir = both label=synchronize constraint=false];
"gui":f1:e -> "vtkMRMLParametersNode":f1:w [dir = both label=synchronize constraint=false];
"ctkCLIModuleDescription":f1 -> "gui":f0 [dir = both label=synchronize constraint=false];
}
}
</graphviz>
</graphviz>


Overview of some central classes and their scope:
Overview of some central classes and their scope.
 
Please see the full [file:///opt/ctk-builds/CTK-debug-gcc/CTK-build/Documentation/html/group__CommandLineModulesCore__API.html Core API] for a list of available classes and their documentation.


==== ctkCmdLineModuleDescription ====
==== ctkCmdLineModuleDescription ====
Line 85: Line 85:
* Get ctkCmdLineModuleDescription class
* Get ctkCmdLineModuleDescription class
* Convenient meta-data access (module location etc.)
* Convenient meta-data access (module location etc.)
* Used to get actual ctkCmdLineModuleInstance instances from ctkCmdLineModuleManager
* Used to crate actual ctkCmdLineModuleFrontend instances from specific ctkCmdLineModuleFrontendFactory implementations


==== ctkCmdLineModuleInstance ====
==== ctkCmdLineModuleFrontend ====


Represents an invokable command line module and its current parameter values.
Represents an invokable command line module and its current parameter values.
Line 95: Line 95:
* Set/Get individual parameter values or all at once
* Set/Get individual parameter values or all at once
* Reset to default parameters
* Reset to default parameters
* Get GUI representation (QObject*)
* Get parameter value change notifications
==== ctkCmdLineModuleFuture ====
Returned by the ctkCmdLineModuleManager run method and used to communicate with a running module.
* Run/Abort  
* Run/Abort  
* Status
* Status
* Progress reporting
* Progress reporting
* Get GUI representation (QObject*)
* Get parameter value change notifications
   
   
==== ctkCmdLineModuleManager ====
==== ctkCmdLineModuleManager ====


Responsible for instantiating other ctkCmdLineModule* classes.
Responsible for managing and running other ctkCmdLineModule* classes.
   
   
* Register factory for customizing GUI generation
* Register specific back-ends for handling different types of modules
* Register/Unregister modules
* Register/Unregister modules
* Get ctkCmdLineModuleReference objects
* Get ctkCmdLineModuleReference objects
* Create/List ModuleInstance objects
* Run ctkCmdLineModuleFrontend objects


=== Customizability ===
=== Customizability ===


==== Qt Widget related ====
==== Qt Widget related ====
See also the [http://www.commontk.org/docs/html/classctkCmdLineModuleFrontendQtGui.html ctkCmdLineModuleFrontendQtGui] class for customization information.


* Use parameters for the default XSLT file to customize widget class names for argument types
* Use parameters for the default XSLT file to customize widget class names for argument types
* Use your own XSLT file for custom transformations of XML to UI
* Use your own XSLT file for custom transformations of XML to UI
* Use your own QUILoader to control instantiation of certain widget types
* Use your own QUiLoader to control instantiation of certain widget types


==== General ====
==== General ====


* Use a custom ''factory'' to create your own GUI based on a ctkCmdLineModuleDescription instance.
* Use a custom ''factory'' to create your own GUI based on a ctkCmdLineModuleDescription instance.

Latest revision as of 05:57, 5 November 2014

Home < Documentation < CLI Support in CTK

Command Line Interface (CLI) support in CTK will primarly focus on providing an API for working with existing CLI modules. Providing utilities and tools for creating CLI modules from scratch is a desired addition but there are no concrete plans for this yet. See Documentation/Command_Line_Interface for more general information about CLI modules.

Getting the Code

The code is available in the CTK master:

https://github.com/commontk/CTK

Enable the following CMake options to be able to play with the code:

  • BUILD_TESTING (for creating CLI test modules)
  • CTK_APP_ctkCommandLineModuleExplorer (small program allowing you to test-drive CLI modules using the CTK CLI module API, enables all the options below)
  • CTK_LIB_CommandLineModules/Core (the CTK library providing the core CLI module API)
  • CTK_LIB_CommandLineModules/Frontend/QtGui (the CTK library providing GUI generation using the Qt widgets)
  • CTK_LIB_CommandLineModules/Backend/LocalProcess (the CTK library for executing local executable files as command line modules)

API Design

This is a partially overview of the API design, showing the GUI generation process for the Qt front-end.

This is a graph with borders and nodes. Maybe there is an Imagemap used so the nodes may be linking to some Pages.

Overview of some central classes and their scope.

Please see the full [file:///opt/ctk-builds/CTK-debug-gcc/CTK-build/Documentation/html/group__CommandLineModulesCore__API.html Core API] for a list of available classes and their documentation.

ctkCmdLineModuleDescription

C++ API for accessing the command line arguments meta-data defined in the XML description.

This class is read-only.

ctkCmdLineModuleReference

A handle to a command line module.

  • Get ctkCmdLineModuleDescription class
  • Convenient meta-data access (module location etc.)
  • Used to crate actual ctkCmdLineModuleFrontend instances from specific ctkCmdLineModuleFrontendFactory implementations

ctkCmdLineModuleFrontend

Represents an invokable command line module and its current parameter values.

Multiple instances for the same ModuleReference may exist.

  • Set/Get individual parameter values or all at once
  • Reset to default parameters
  • Get GUI representation (QObject*)
  • Get parameter value change notifications

ctkCmdLineModuleFuture

Returned by the ctkCmdLineModuleManager run method and used to communicate with a running module.

  • Run/Abort
  • Status
  • Progress reporting

ctkCmdLineModuleManager

Responsible for managing and running other ctkCmdLineModule* classes.

  • Register specific back-ends for handling different types of modules
  • Register/Unregister modules
  • Get ctkCmdLineModuleReference objects
  • Run ctkCmdLineModuleFrontend objects

Customizability

Qt Widget related

See also the ctkCmdLineModuleFrontendQtGui class for customization information.

  • Use parameters for the default XSLT file to customize widget class names for argument types
  • Use your own XSLT file for custom transformations of XML to UI
  • Use your own QUiLoader to control instantiation of certain widget types

General

  • Use a custom factory to create your own GUI based on a ctkCmdLineModuleDescription instance.
Retrieved from "http://www.commontk.org/index.php?title=Documentation/CLI_Support_in_CTK&oldid=2250"