ground/openpilotgcs/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 QSettings *ICore::settings(QSettings::UserScope scope) const
 177     \brief Returns the application's main settings object.
 178
 179     You can use it to retrieve or set application wide settings
 180     (in contrast to session or project specific settings).
 181
 182     If \a scope is QSettings::UserScope (the default), the
 183     users settings will be read from the users settings, with
 184     a fallback to global settings provided with Qt Creator.
 185
 186     If \a scope is QSettings::SystemScope, only the system settings
 187     shipped with the current version of Qt Creator will be read. This
 188     functionality exists for internal purposes only.
 189
 190     \see settingsDatabase()
 191  */
 192
 193 /*!
 194     \fn SettingsDatabase *ICore::settingsDatabase() const
 195     \brief Returns the application's settings database.
 196
 197     The settings database is meant as an alternative to the regular settings
 198     object. It is more suitable for storing large amounts of data. The settings
 199     are application wide.
 200
 201     \see SettingsDatabase
 202  */
 203
 204 /*!
 205     \fn QString ICore::resourcePath() const
 206     \brief Returns the absolute path that is used for resources like
 207     project templates and the debugger macros.
 208
 209     This abstraction is needed to avoid platform-specific code all over
 210     the place, since e.g. on Mac the resources are part of the application bundle.
 211  */
 212
 213 /*!
 214     \fn QMainWindow *ICore::mainWindow() const
 215     \brief Returns the main application window.
 216
 217     For use as dialog parent etc.
 218  */
 219
 220 /*!
 221     \fn IContext *ICore::currentContextObject() const
 222     \brief Returns the context object of the current main context.
 223
 224     \sa ICore::addAdditionalContext()
 225     \sa ICore::addContextObject()
 226  */
 227
 228 /*!
 229     \fn void ICore::addAdditionalContext(int context)
 230     \brief Register additional context to be currently active.
 231
 232     Appends the additional \a context to the list of currently active
 233     contexts. You need to call ICore::updateContext to make that change
 234     take effect.
 235
 236     \sa ICore::removeAdditionalContext()
 237     \sa ICore::hasContext()
 238     \sa ICore::updateContext()
 239  */
 240
 241 /*!
 242     \fn void ICore::removeAdditionalContext(int context)
 243     \brief Removes the given \a context from the list of currently active contexts.
 244
 245     You need to call ICore::updateContext to make that change
 246     take effect.
 247
 248     \sa ICore::addAdditionalContext()
 249     \sa ICore::hasContext()
 250     \sa ICore::updateContext()
 251  */
 252
 253 /*!
 254     \fn bool ICore::hasContext(int context) const
 255     \brief Returns if the given \a context is currently one of the active contexts.
 256
 257     \sa ICore::addAdditionalContext()
 258     \sa ICore::addContextObject()
 259  */
 260
 261 /*!
 262     \fn void ICore::addContextObject(IContext *context)
 263     \brief Registers an additional \a context object.
 264
 265     After registration this context object gets automatically the
 266     current context object whenever its widget gets focus.
 267
 268     \sa ICore::removeContextObject()
 269     \sa ICore::addAdditionalContext()
 270     \sa ICore::currentContextObject()
 271  */
 272
 273 /*!
 274     \fn void ICore::removeContextObject(IContext *context)
 275     \brief Unregisters a \a context object from the list of know contexts.
 276
 277     \sa ICore::addContextObject()
 278     \sa ICore::addAdditionalContext()
 279     \sa ICore::currentContextObject()
 280    }
 281  */
 282
 283 /*!
 284     \fn void ICore::updateContext()
 285     \brief Update the list of active contexts after adding or removing additional ones.
 286
 287     \sa ICore::addAdditionalContext()
 288     \sa ICore::removeAdditionalContext()
 289  */
 290
 291 /*!
 292     \fn void ICore::openFiles(const QStringList &fileNames)
 293     \brief Open all files from a list of \a fileNames like it would be
 294     done if they were given to the OpenPilot GCS on the command line, or
 295     they were opened via \gui{File|Open}.
 296  */
 297
 298 /*!
 299     \fn ICore::ICore()
 300     \internal
 301  */
 302
 303 /*!
 304     \fn ICore::~ICore()
 305     \internal
 306  */
 307
 308 /*!
 309     \fn void ICore::coreOpened()
 310     \brief Emitted after all plugins have been loaded and the main window shown.
 311  */
 312
 313 /*!
 314     \fn void ICore::saveSettingsRequested()
 315     \brief Emitted to signal that the user has requested that the global settings
 316     should be saved to disk.
 317
 318     At the moment that happens when the application is closed, and on \gui{Save All}.
 319  */
 320
 321 /*!
 322     \fn void ICore::optionsDialogRequested()
 323     \brief Signal that allows plugins to perform actions just before the \gui{Tools|Options}
 324     dialog is shown.
 325  */
 326
 327 /*!
 328     \fn void ICore::coreAboutToClose()
 329     \brief Plugins can do some pre-end-of-life actions when they get this signal.
 330
 331     The application is guaranteed to shut down after this signal is emitted.
 332     It's there as an addition to the usual plugin lifecycle methods, namely
 333     IPlugin::shutdown(), just for convenience.
 334  */
 335
 336 /*!
 337     \fn void ICore::contextAboutToChange(Core::IContext *context)
 338     \brief Sent just before a new \a context becomes the current context
 339     (meaning that its widget got focus).
 340  */
 341
 342 /*!
 343     \fn void ICore::contextChanged(Core::IContext *context)
 344     \brief Sent just after a new \a context became the current context
 345     (meaning that its widget got focus).
 346  */