Commit 5cf53a53 authored by NICLAUSSE Nicolas's avatar NICLAUSSE Nicolas

add documentation for dtkWidgets, plus document all dtkApplications classes

parent 57368e86
......@@ -28,8 +28,7 @@ set(dtk_INCLUDE_DIRS
"@CMAKE_INSTALL_PREFIX@/include/dtkLog"
"@CMAKE_INSTALL_PREFIX@/include/dtkMath"
"@CMAKE_INSTALL_PREFIX@/include/dtkMeta"
"@CMAKE_INSTALL_PREFIX@/include/dtkTest"
"@CMAKE_INSTALL_PREFIX@/include/dtkWidgets")
"@CMAKE_INSTALL_PREFIX@/include/dtkTest")
set(CMAKE_MODULE_PATH
${CMAKE_MODULE_PATH} "@CMAKE_INSTALL_PREFIX@/@CMAKE_INSTALL_LIBDIR@/cmake/dtk/")
......
......@@ -77,6 +77,20 @@ add_custom_target(dtkLog-doc
add_dependencies(dtkLog-doc dtk-doc)
## ###################################################################
## dtkWidgets
## ###################################################################
configure_file(${CMAKE_CURRENT_SOURCE_DIR}/dtkWidgets/dtkwidgets.qdocconf.in ${CMAKE_CURRENT_BINARY_DIR}/dtkwidgets.qdocconf IMMEDIATE @ONLY)
add_custom_target(dtkWidgets-doc
WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
COMMAND ${DTK_QDOC_EXECUTABLE} dtkwidgets.qdocconf
COMMAND ${QT5_QHGN_EXECUTABLE} ${dtk_INSTALL_DOCS}/dtkwidgets/dtkwidgets.qhp -o ${dtk_INSTALL_DOCS}/dtkwidgets.qch
COMMENT "-- Generating dtkWidgets documentation")
add_dependencies(dtkWidgets-doc dtk-widgets)
## ###################################################################
## dtkCore
## ###################################################################
......@@ -129,7 +143,7 @@ add_custom_target(doc
COMMAND ${QT5_QHGN_EXECUTABLE} ${dtk_INSTALL_DOCS}/dtkdoc/dtkdoc.qhp -o ${dtk_INSTALL_DOCS}/dtkdoc.qch
COMMENT "-- Generating dtk documentation")
add_dependencies(doc dtkMeta-doc dtkLog-doc dtkCore-doc dtkDistributed-doc dtkComposer-doc)
add_dependencies(doc dtkMeta-doc dtkLog-doc dtkWidgets-doc dtkCore-doc dtkDistributed-doc dtkComposer-doc)
######################################################################
### CMakeLists.txt ends here
......@@ -49,6 +49,7 @@ indexes = \
@dtk_INSTALL_DOCS@/dtkmeta/dtkmeta.index \
@dtk_INSTALL_DOCS@/dtkcore/dtkcore.index \
@dtk_INSTALL_DOCS@/dtkcomposer/dtkcomposer.index \
@dtk_INSTALL_DOCS@/dtkwidgets/dtkwidgets.index \
@dtk_INSTALL_DOCS@/dtkdistributed/dtkdistributed.index \
@dtk_INSTALL_DOCS@/dtkio/dtkio.index \
@dtk_INSTALL_DOCS@/dtklinearalgebradense/dtklinearalgebradense.index \
......
......@@ -42,6 +42,9 @@
\row
\li \l{Log Module} {Log}
\li Logging framework.
\row
\li \l{Widgets Module} {Widgets}
\li Widgets framework.
\endtable
\section1 dtk Applicative Layers
......
......@@ -19,7 +19,7 @@
\brief Provides fundamental concepts and related tools.
dtkCore, is the foundation layer in dtk, the one that reflects its
dtkCore is the foundation layer in dtk, the one that reflects its
intents as well as it's design. Other layers provided with dtk
rely on the core, and essentially provide thematic add-ons to
manipulate the fundamental concepts found in dtkCore such as data,
......
## Version: $Id$
##
######################################################################
##
### Commentary:
##
######################################################################
##
### Change Log:
##
######################################################################
##
### Code:
include(@dtk_CONFIG_DOCS@/dtk-config.qdocconf)
project = dtkWidgets
description = dtkWidgets Reference Documentation
url = ../dtkwidgets
qhp.projects = dtkWidgets
qhp.dtkWidgets.file = dtkwidgets.qhp
qhp.dtkWidgets.namespace = fr.inria.dtk.dtkwidgets
qhp.dtkWidgets.virtualFolder = dtkwidgets
qhp.dtkWidgets.indexTitle = Widgets Module
qhp.dtkWidgets.indexRoot =
qhp.dtkWidgets.filterAttributes = dtkwidgets
qhp.dtkWidgets.customFilters.dtk.name = dtkWidgets
qhp.dtkWidgets.customFilters.dtk.filterAttributes = dtkwidgets
qhp.dtkWidgets.subprojects = classes
qhp.dtkWidgets.subprojects.classes.title = C++ Classes
qhp.dtkWidgets.subprojects.classes.indexTitle = Widgets C++ Classes
qhp.dtkWidgets.subprojects.classes.selectors = class fake:headerfile
qhp.dtkWidgets.subprojects.classes.sortPages = true
headerdirs += ../../../src/dtkWidgets
sourcedirs += ../../../src/dtkWidgets \
../../../doc/dtkWidgets/src
exampledirs += ../../../doc/dtkWidgets/snp
imagedirs += ../../../doc/dtkWidgets/img
excludedirs += ../../../doc/dtkWidgets/snp
navigation.landingpage = "Widgets Module"
navigation.cppclassespage = "Widgets C++ Classes"
outputdir = @dtk_INSTALL_DOCS@/dtkwidgets
indexes = \
@QT5_DOCUMENTATION_D@/qtcore/qtcore.index \
@dtk_INSTALL_DOCS@/dtkwidgets/dtkwidgets.index
######################################################################
### dtkwidgets.qdocconf.in ends here
// Version: $Id$
//
//
// Commentary:
//
//
// Change Log:
//
//
// Code:
/*!
\page dtkwidgets-index.html
\title Widgets Module
\brief The dtkWidgets module is part of dtk's essential \l {All Modules} {modules}.
\section1 Reference
These are links to the API reference materials.
\list
\li \l{Widgets C++ Classes}{C++ Classes API}
\endlist
\sa {All Modules}
*/
//
// dtkwidgets-index.qdoc ends here
// Version: $Id$
//
//
// Commentary:
//
//
// Change Log:
//
//
// Code:
/*!
\module dtkWidgets
\title Widgets C++ Classes
\ingroup dtk-allAPI
\brief Widgets
*/
//
// dtkwidgets.qdoc ends here
......@@ -16,28 +16,117 @@
#include "dtkCoreApplication.h"
#include "dtkApplicationPrivate.h"
/*!
\class dtkCoreApplication
\inmodule dtkCore
\brief This class is used by non-GUI applications to provide their event loop. It is based on QCoreApplication, and adds a few command line options to setup settings and dtkLog. For GUI applications, see dtkApplication in dtkWidgets.
\code
int main(int argc, char *argv[])
{
dtkCoreApplication application(argc, argv);
application.setApplicationName("myApp");
application.setApplicationVersion("1.0.0");
application.setOrganizationName("inria");
application.setOrganizationDomain("fr");
QCommandLineParser *parser = application.parser();
parser->setApplicationDescription("my first DTK based application.");
QCommandLineOption myOption("myopt", "enable myopt");
parser->addOption(myOption);
application.initialize();
if (!parser->isSet(myOption)) {
// do something
}
return application.exec();
}
\endcode
If you run this application, --help gives you:
\code
Usage: ./bin/myApp [options]
my first DTK based application.
Options:
--myopt enable myopt
-h, --help Displays this help.
-v, --version Displays version information.
--settings <filename> main settings file
--verbose verbose plugin initialization
--nw, --no-window non GUI application (no window)
--loglevel <level> log level used by dtkLog (default is info),
available: trace|debug|info|warn|error|fatal
--logfile <filename | console> log file used by dtkLog; default is:
/user/nniclaus/home/.local/share/inria/myApp/m
yApp.log
--logfilemax <size> log file max size (in MB); default is: 3072
(3GB)
\endcode
*/
/*! \fn dtkCoreApplication::dtkCoreApplication(int &argc, char **argv)
Constructs a dtkCoreApplication. Core applications are applications without a graphical user interface. Such applications are used at the console or as server processes.
The argc and argv arguments are processed by the application, and made available in a more convenient form by the arguments() function.
Warning: The data referred to by argc and argv must stay valid for the entire lifetime of the dtkCoreApplication object. In addition, argc must be greater than zero and argv must contain at least one valid character string.
*/
dtkCoreApplication::dtkCoreApplication(int &argc, char **argv): QCoreApplication(argc, argv)
{
d = new dtkApplicationPrivate;
d->setApplication(this);
}
/*! \fn dtkCoreApplication::~dtkCoreApplication(void)
Destroys the dtkCoreApplication object.
*/
dtkCoreApplication::~dtkCoreApplication(void)
{
delete d;
d = NULL;
}
/*! \fn Qsettings dtkCoreApplication::settings(void)
Return the main QSettings.
*/
QSettings *dtkCoreApplication::settings(void)
{
return d->settings;
}
/*! \fn QCommandLineParser *dtkCoreApplication::parser(void)
Return the main QCommandLineParser used by the application. It can be used to app specific options for your application.
*/
QCommandLineParser *dtkCoreApplication::parser(void)
{
return d->parser;
}
/*! \fn void dtkCoreApplication::initialize(void)
Initialize the command line parser. Should be called once all the specific options of your application are added in the parser.
\sa parser
*/
void dtkCoreApplication::initialize(void)
{
d->initialize();
......
......@@ -26,8 +26,57 @@
/*!
\class dtkDistributedApplication
\inmodule dtkDistributed
\brief dtkDistributedApplication ...
\brief This class is used to start non GUI applications that use the dtkDistributed framework. The distributed option (plugins, number of process/threads, ...) can be configured on the command line, and also setup settings and dtkLog.
\code
int main(int argc, char **argv)
{
dtkDistributedApplication *app = dtkDistributed::create(argc, argv);
app->setOrganizationName("inria");
app->setOrganizationDomain("fr");
app->setApplicationName("myApp");
app->setApplicationVersion("0.1.0");
QCommandLineParser *parser = app->parser();
parser->setApplicationDescription("my dtk distributed app.");
QCommandLineOption myOption("myopt", "enable myopt", "default val");
parser->addOption(myOption);
app->initialize();
// ------------ check parameters
if (!parser->isSet(myOption)) {
qFatal("Error: input are not correctly set! you have to set : --myopt <val>") ;
return 1;
}
// /////////////////////////////////////////////////////////////////
// Launch the execution
// ////////////////////////////////////////////////////////////////
myRunnableClass torun;
torun.myarg = parser->value(myOption);
app->spawn();
app->exec(&torun);
app->unspawn();
return 0;
}
\endcode
\sa dtkDistributedGuiApplication
*/
/*! \fn dtkDistributedApplication::dtkDistributedApplication(int &argc, char **argv)
Constructs a dtkDistributedApplication.
The \a argc and \a argv arguments are processed by the application, and made available in a more convenient form by the arguments() function.
Warning: The data referred to by \a argc and \a argv must stay valid for the entire lifetime of the dtkCoreApplication object. In addition, argc must be greater than zero and argv must contain at least one valid character string.
*/
dtkDistributedApplication::dtkDistributedApplication(int &argc, char **argv): QCoreApplication(argc, argv)
......@@ -36,54 +85,116 @@ dtkDistributedApplication::dtkDistributedApplication(int &argc, char **argv): QC
d = new dtkDistributedApplicationPrivate;
}
/*! \fn dtkDistributedApplication::~dtkDistributedApplication(void)
Destroys the dtkDistributedApplication object.
*/
dtkDistributedApplication::~dtkDistributedApplication(void)
{
delete d;
d = NULL;
}
/*! \fn void dtkDistributedApplication::initialize(void)
Initialize the command line parser. Should be called once all the specific options of your application are added in the parser.
\sa parser
*/
void dtkDistributedApplication::initialize(void)
{
d->initialize();
}
/*! \fn void dtkDistributedApplication::exec(QRunnable *task)
execute the given QRunnable \a task on the spawned processes/threads. Must be called after spawn()
\sa spawn
*/
void dtkDistributedApplication::exec(QRunnable *task)
{
d->policy.communicator()->exec(task);
}
/*! \fn void dtkDistributedApplication::spawn (QMap <QString,QString> options)
Spawn processes/threads on one or several hosts (depending on the implementation). This step can be bypassed if the --no-spawn argument is given. This can be useful when you are using an mpi communicator and your mpi implementation or scheduler does not handle the \a Mpi_comm_Spawn gracefully. Will you have to use an external tool to spawn the application (mpirun , srun , ...)
*/
void dtkDistributedApplication::spawn(QMap<QString,QString> options)
{
d->spawn();
}
/*! \fn void dtkDistributedApplication::unspawn(void)
unspawn processes/threads
*/
void dtkDistributedApplication::unspawn(void)
{
d->unspawn();
}
/*! \fn QCommandLineParser *dtkDistributedApplication::parser(void)
Return the main QCommandLineParser used by the application. It can be used to app specific options for your application.
*/
QCommandLineParser *dtkDistributedApplication::parser(void)
{
return d->parser;
}
/*! \fn dtkDistributedPolicy *dtkDistributedApplication::policy(void)
Return the current policy
*/
dtkDistributedPolicy *dtkDistributedApplication::policy(void)
{
return &(d->policy);
}
/*! \fn dtkDistributedCommunicator *dtkDistributedApplication::communicator(void)
Return the main communicator.
\sa dtkDistributedCommunicator
*/
dtkDistributedCommunicator *dtkDistributedApplication::communicator(void)
{
return d->policy.communicator();
}
/*! \fn bool dtkDistributedApplication::isMaster(void)
Return true if the calling process/thread is the master (rank 0)
*/
bool dtkDistributedApplication::isMaster(void)
{
return (d->policy.communicator()->rank() == 0);
}
/* always returns true: just to be compatible with dtkDistributedGuiApplication */
/*! \fn void dtkDistributedApplication::noGui(void)
Always returns true: just to be compatible with dtkDistributedGuiApplication
\sa spawn
*/
/* */
bool dtkDistributedApplication::noGui(void)
{
return true;
......
......@@ -38,12 +38,6 @@ public:
public:
QCommandLineParser *parser(void);
public:
static dtkDistributedApplication *create(int &argc, char *argv[])
{
return new dtkDistributedApplication(argc, argv);
}
public:
bool isMaster(void);
virtual bool noGui(void);
......
......@@ -16,33 +16,136 @@
#include "dtkApplication.h"
#include <dtkCore/dtkApplicationPrivate.h>
/*!
\class dtkApplication
\inmodule dtkWidgets
\brief This class is used by GUI applications to provide their event loop. It is based on QApplication, and adds a few command line options to setup settings and dtkLog. It can also be used to start a non GUI appliation if the \tt{-nw} argument is given and the create method is called (it won't work if you use new directly)
\code
int main(int argc, char *argv[])
{
dtkApplication *application = dtkApplication::create(argc, argv);
application->setApplicationName("myApp");
application->setApplicationVersion("1.0.0");
application->setOrganizationName("inria");
application->setOrganizationDomain("fr");
QCommandLineParser *parser = application->parser();
parser->setApplicationDescription("my first DTK based application.");
QCommandLineOption myOption("myopt", "enable myopt");
parser->addOption(myOption);
application->initialize();
if (!parser->isSet(myOption)) {
// do something
}
return application->exec();
}
\endcode
If you run this application, \tt{--help} gives you:
\code
Usage: ./bin/myApp [options]
my first DTK based application.
Options:
--myopt enable myopt
-h, --help Displays this help.
-v, --version Displays version information.
--settings <filename> main settings file
--verbose verbose plugin initialization
--nw, --no-window non GUI application (no window)
--loglevel <level> log level used by dtkLog (default is info),
available: trace|debug|info|warn|error|fatal
--logfile <filename | console> log file used by dtkLog; default is:
/user/nniclaus/home/.local/share/inria/myApp/m
yApp.log
--logfilemax <size> log file max size (in MB); default is: 3072
(3GB)
\endcode
*/
/*! \fn dtkApplication::dtkApplication(int &argc, char **argv)
Constructs a dtkApplication. Initializes the window system and constructs an application object with argc command line arguments in argv.
The argc and argv arguments are processed by the application, and made available in a more convenient form by the arguments() function.
Warning: The data referred to by \a argc and \a argv must stay valid for the entire lifetime of the dtkCoreApplication object. In addition, argc must be greater than zero and argv must contain at least one valid character string.
*/
dtkApplication::dtkApplication(int &argc, char **argv): QApplication(argc, argv)
{
d = new dtkApplicationPrivate;
d->setApplication(this);
}
/*! \fn dtkApplication::~dtkApplication(void)
Destroys the dtkApplication object.
*/
dtkApplication::~dtkApplication(void)
{
delete d;
d = NULL;
}
/*! \fn dtkApplication *create(int &argc, char *argv[])
Helper function to create an instance of a dtkApplication. If the \tt{--nw} option is set, it will use a \e{minimal} \tt{QT_QPA_PLATFORM}. \a argc and \a argv are the usual parameters of a QCoreApplication.
*/
/*! \fn Qsettings dtkApplication::settings(void)
Return the main QSettings.
*/
QSettings *dtkApplication::settings(void)
{
return d->settings;
}
/*! \fn bool dtkApplication::noGui(void)
Return true if the application is not a GUI application (ie. the \tt{-nw} was used in the command line)
*/
bool dtkApplication::noGui(void)
{
return !(qApp && qobject_cast<QGuiApplication *>(qApp) && (QGuiApplication::platformName() != "minimal")) ;
}
/*! \fn QCommandLineParser *dtkApplication::parser(void)
Return the main QCommandLineParser used by the application. It can be used to app specific options for your application.
*/
QCommandLineParser *dtkApplication::parser(void)
{
return d->parser;
}
/*! \fn void dtkApplication::initialize(void)
Initialize the command line parser. Should be called once all the specific options of your application are added in the parser.
\sa parser
*/
void dtkApplication::initialize(void)
{
d->initialize();
......