ground/gcs/src/plugins/coreplugin/icore.cpp

   1 /**
   2  ******************************************************************************
   3  *
   4  * @file       icore.cpp
   5  * @author     The OpenPilot Team, http://www.openpilot.org Copyright (C) 2010.
   6  *             Parts by Nokia Corporation (qt-info@nokia.com) Copyright (C) 2009.
   7  * @addtogroup GCSPlugins GCS Plugins
   8  * @{
   9  * @addtogroup CorePlugin Core Plugin
  10  * @{
  11  * @brief The Core GCS plugin
  12  *****************************************************************************/
  13 /*
  14  * This program is free software; you can redistribute it and/or modify
  15  * it under the terms of the GNU General Public License as published by
  16  * the Free Software Foundation; either version 3 of the License, or
  17  * (at your option) any later version.
  18  *
  19  * This program is distributed in the hope that it will be useful, but
  20  * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
  21  * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
  22  * for more details.
  23  *
  24  * You should have received a copy of the GNU General Public License along
  25  * with this program; if not, write to the Free Software Foundation, Inc.,
  26  * 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
  27  */
  28
  29 #include "icore.h"
  30
  31 /*!
  32     \namespace Core
  33     \brief The Core namespace contains all classes that make up the Core plugin
  34     which constitute the basic functionality of the OpenPilot GCS.
  35  */
  36
  37 /*!
  38     \namespace Core::Internal
  39     \internal
  40  */
  41
  42 /*!
  43     \class Core::ICore
  44     \brief The ICore class allows access to the different part that make up
  45     the basic functionality of the OpenPilot GCS.
  46
  47     You should never create a subclass of this interface. The one and only
  48     instance is created by the Core plugin. You can access this instance
  49     from your plugin through \c{Core::instance()}.
  50
  51     \mainclass
  52  */
  53
  54 /*!
  55     \fn QStringList ICore::showNewItemDialog(const QString &title,
  56                                       const QList<IWizard *> &wizards,
  57                                       const QString &defaultLocation = QString())
  58     \brief Opens a dialog where the user can choose from a set of \a wizards that
  59     create new files/classes/projects.
  60
  61     The \a title argument is shown as the dialogs title. The path where the
  62     files will be created (if the user doesn't change it) is set
  63     in \a defaultLocation. It defaults to the path of the file manager's
  64     current file.
  65
  66     \sa Core::FileManager
  67  */
  68
  69 /*!
  70     \fn bool ICore::showOptionsDialog(const QString &group = QString(),
  71                                const QString &page = QString())
  72     \brief Opens the application options/preferences dialog with preselected
  73     \a page in a specified \a group.
  74
  75     The arguments refer to the string IDs of the corresponding IOptionsPage.
  76  */
  77
  78 /*!
  79     \fn bool ICore::showWarningWithOptions(const QString &title, const QString &text,
  80                                    const QString &details = QString(),
  81                                    const QString &settingsCategory = QString(),
  82                                    const QString &settingsId = QString(),
  83                                    QWidget *parent = 0);
  84
  85     \brief Show a warning message with a button that opens a settings page.
  86
  87     Should be used to display configuration errors and point users to the setting.
  88     Returns true if the settings dialog was accepted.
  89  */
  90
  91
  92 /*!
  93     \fn ActionManager *ICore::actionManager() const
  94     \brief Returns the application's action manager.
  95
  96     The action manager is responsible for registration of menus and
  97     menu items and keyboard shortcuts.
  98  */
  99
 100 /*!
 101     \fn FileManager *ICore::fileManager() const
 102     \brief Returns the application's file manager.
 103
 104     The file manager keeps track of files for changes outside the application.
 105  */
 106
 107 /*!
 108     \fn UniqueIDManager *ICore::uniqueIDManager() const
 109     \brief Returns the application's id manager.
 110
 111     The unique ID manager transforms strings in unique integers and the other way round.
 112  */
 113
 114 /*!
 115     \fn MessageManager *ICore::messageManager() const
 116     \brief Returns the application's message manager.
 117
 118     The message manager is the interface to the "General" output pane for
 119     general application debug messages.
 120  */
 121
 122 /*!
 123     \fn ExtensionSystem::PluginManager *ICore::pluginManager() const
 124     \brief Returns the application's plugin manager.
 125
 126     The plugin manager handles the plugin life cycles and manages
 127     the common object pool.
 128  */
 129
 130 /*!
 131     \fn EditorManager *ICore::editorManager() const
 132     \brief Returns the application's editor manager.
 133
 134     The editor manager handles all editor related tasks like opening
 135     documents, the stack of currently open documents and the currently
 136     active document.
 137  */
 138
 139
 140 /*!
 141     \fn VariableManager *ICore::variableManager() const
 142     \brief Returns the application's variable manager.
 143
 144     The variable manager is used to register application wide string variables
 145     like \c MY_PROJECT_DIR such that strings like \c{somecommand ${MY_PROJECT_DIR}/sub}
 146     can be resolved/expanded from anywhere in the application.
 147  */
 148
 149 /*!
 150     \fn ThreadManager *ICore::threadManager() const
 151     \brief Returns the application's thread manager.
 152
 153     The thread manager is used to manage application wide QThread objects,
 154     allowing certain critical objects to synchronize directly within the same
 155     real time thread - anywhere in the application.
 156  */
 157
 158 /*!
 159     \fn ModeManager *ICore::modeManager() const
 160     \brief Returns the application's mode manager.
 161
 162     The mode manager handles everything related to the instances of IMode
 163     that were added to the plugin manager's object pool as well as their
 164     buttons and the tool bar with the round buttons in the lower left
 165     corner of the OpenPilot GCS.
 166  */
 167
 168 /*!
 169     \fn MimeDatabase *ICore::mimeDatabase() const
 170     \brief Returns the application's mime database.
 171
 172     Use the mime database to manage mime types.
 173  */
 174
 175 /*!
 176     \fn SettingsDatabase *ICore::settingsDatabase() const
 177     \brief Returns the application's settings database.
 178
 179     The settings database is meant as an alternative to the regular settings
 180     object. It is more suitable for storing large amounts of data. The settings
 181     are application wide.
 182
 183     \see SettingsDatabase
 184  */
 185
 186 /*!
 187     \fn QString ICore::resourcePath() const
 188     \brief Returns the absolute path that is used for resources like
 189     project templates and the debugger macros.
 190
 191     This abstraction is needed to avoid platform-specific code all over
 192     the place, since e.g. on Mac the resources are part of the application bundle.
 193  */
 194
 195 /*!
 196     \fn QMainWindow *ICore::mainWindow() const
 197     \brief Returns the main application window.
 198
 199     For use as dialog parent etc.
 200  */
 201
 202 /*!
 203     \fn IContext *ICore::currentContextObject() const
 204     \brief Returns the context object of the current main context.
 205
 206     \sa ICore::addAdditionalContext()
 207     \sa ICore::addContextObject()
 208  */
 209
 210 /*!
 211     \fn void ICore::addAdditionalContext(int context)
 212     \brief Register additional context to be currently active.
 213
 214     Appends the additional \a context to the list of currently active
 215     contexts. You need to call ICore::updateContext to make that change
 216     take effect.
 217
 218     \sa ICore::removeAdditionalContext()
 219     \sa ICore::hasContext()
 220     \sa ICore::updateContext()
 221  */
 222
 223 /*!
 224     \fn void ICore::removeAdditionalContext(int context)
 225     \brief Removes the given \a context from the list of currently active contexts.
 226
 227     You need to call ICore::updateContext to make that change
 228     take effect.
 229
 230     \sa ICore::addAdditionalContext()
 231     \sa ICore::hasContext()
 232     \sa ICore::updateContext()
 233  */
 234
 235 /*!
 236     \fn bool ICore::hasContext(int context) const
 237     \brief Returns if the given \a context is currently one of the active contexts.
 238
 239     \sa ICore::addAdditionalContext()
 240     \sa ICore::addContextObject()
 241  */
 242
 243 /*!
 244     \fn void ICore::addContextObject(IContext *context)
 245     \brief Registers an additional \a context object.
 246
 247     After registration this context object gets automatically the
 248     current context object whenever its widget gets focus.
 249
 250     \sa ICore::removeContextObject()
 251     \sa ICore::addAdditionalContext()
 252     \sa ICore::currentContextObject()
 253  */
 254
 255 /*!
 256     \fn void ICore::removeContextObject(IContext *context)
 257     \brief Unregisters a \a context object from the list of know contexts.
 258
 259     \sa ICore::addContextObject()
 260     \sa ICore::addAdditionalContext()
 261     \sa ICore::currentContextObject()
 262    }
 263  */
 264
 265 /*!
 266     \fn void ICore::updateContext()
 267     \brief Update the list of active contexts after adding or removing additional ones.
 268
 269     \sa ICore::addAdditionalContext()
 270     \sa ICore::removeAdditionalContext()
 271  */
 272
 273 /*!
 274     \fn void ICore::openFiles(const QStringList &fileNames)
 275     \brief Open all files from a list of \a fileNames like it would be
 276     done if they were given to the OpenPilot GCS on the command line, or
 277     they were opened via \gui{File|Open}.
 278  */
 279
 280 /*!
 281     \fn ICore::ICore()
 282     \internal
 283  */
 284
 285 /*!
 286     \fn ICore::~ICore()
 287     \internal
 288  */
 289
 290 /*!
 291     \fn void ICore::coreOpened()
 292     \brief Emitted after all plugins have been loaded and the main window shown.
 293  */
 294
 295 /*!
 296     \fn void ICore::saveSettingsRequested()
 297     \brief Emitted to signal that the user has requested that the global settings
 298     should be saved to disk.
 299
 300     At the moment that happens when the application is closed, and on \gui{Save All}.
 301  */
 302
 303 /*!
 304     \fn void ICore::optionsDialogRequested()
 305     \brief Signal that allows plugins to perform actions just before the \gui{Tools|Options}
 306     dialog is shown.
 307  */
 308
 309 /*!
 310     \fn void ICore::coreAboutToClose()
 311     \brief Plugins can do some pre-end-of-life actions when they get this signal.
 312
 313     The application is guaranteed to shut down after this signal is emitted.
 314     It's there as an addition to the usual plugin lifecycle methods, namely
 315     IPlugin::shutdown(), just for convenience.
 316  */
 317
 318 /*!
 319     \fn void ICore::contextAboutToChange(Core::IContext *context)
 320     \brief Sent just before a new \a context becomes the current context
 321     (meaning that its widget got focus).
 322  */
 323
 324 /*!
 325     \fn void ICore::contextChanged(Core::IContext *context)
 326     \brief Sent just after a new \a context became the current context
 327     (meaning that its widget got focus).
 328  */