diff options
Diffstat (limited to 'lib/interfaces/kdevcore.h')
-rw-r--r-- | lib/interfaces/kdevcore.h | 387 |
1 files changed, 387 insertions, 0 deletions
diff --git a/lib/interfaces/kdevcore.h b/lib/interfaces/kdevcore.h new file mode 100644 index 00000000..cdc5ca87 --- /dev/null +++ b/lib/interfaces/kdevcore.h @@ -0,0 +1,387 @@ +/* This file is part of the KDE project + Copyright (C) 2001-2002 Matthias Hoelzer-Kluepfel <[email protected]> + Copyright (C) 2001-2002 Bernd Gehrmann <[email protected]> + Copyright (C) 2001 Sandy Meier <[email protected]> + Copyright (C) 2002 Daniel Engelschalt <[email protected]> + Copyright (C) 2002 Simon Hausmann <[email protected]> + Copyright (C) 2002-2003 Roberto Raggi <[email protected]> + Copyright (C) 2003 Mario Scalas <[email protected]> + Copyright (C) 2003 Harald Fernengel <[email protected]> + Copyright (C) 2003 Hamish Rodda <[email protected]> + Copyright (C) 2004 Alexander Dymo <[email protected]> + + This library is free software; you can redistribute it and/or + modify it under the terms of the GNU Library General Public + License as published by the Free Software Foundation; either + version 2 of the License, or (at your option) any later version. + + This library is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Library General Public License for more details. + + You should have received a copy of the GNU Library General Public License + along with this library; see the file COPYING.LIB. If not, write to + the Free Software Foundation, Inc., 59 Temple Place - Suite 330, + Boston, MA 02111-1307, USA. +*/ +#ifndef KDEVCORE_H +#define KDEVCORE_H + +/** +@file kdevcore.h +The interface to the application core and context menu classes. +*/ + +#include <qstringlist.h> +#include <qdict.h> +#include <qobject.h> + +#include <kurl.h> + +class KDialogBase; +class KDevPlugin; +class CodeModelItem; +class ProjectModelItem; + +namespace KParts +{ + class Part; +} + +class QStatusBar; +class QPopupMenu; + +/** +Base class for every context. +Think of a Context-based class as "useful +info associated to a context menu". Several context menu can be defined, +each defining different information: because of these context menus being +used in many modules, they are defined here. + +When context menu with a certain "context" associated appears, KDevelop core +sends a notification signal and all plugins which receive this signal have +the ability to add own items into the menu. For example, VCS plugin could +add "commit" and "update" menu items to the context menu of a file. + +<b>How to use context from a plugin:</b> +-# Create a popup menu in context menu event handler: @code KPopupMenu menu(this); @endcode +-# Create a context: @code MyContext context(param). @endcode +-# Fill a context menu: @code core()->fillContextMenu(&menu, &context); @endcode +-# Show the popup menu: @code menu.exec(event->globalPos()); @endcode +. +In this example @em event is an object of QContextMenuEvent class which you have access +to if you reimplement QWidget::contextMenuEvent method. + +<b>How to fill context menu from a plugin:</b> +-# Create a @code contextMenu(QPopupMenu *, const Context *) @endcode slot in your plugin class. +-# Connect KDevCore::contextMenu(QPopupMenu *, const Context *) signal to that slot in +the constructor of your plugin:\n +@code +connect(core(), SIGNAL(contextMenu(QPopupMenu *, const Context *)), + this, SLOT(contextMenu(QPopupMenu *, const Context *))); +@endcode +-# Fill the menu in the slot you created, for example:\n +@code +if (context->hasType(Context::EditorContext)) +{ + const EditorContext *econtext = static_cast<const EditorContext*>(context); + int id = popup->insertItem(i18n("My Menu Item 1"), this, SLOT(myMenuAction1())); + popup->setWhatsThis(id, i18n("What's this for my menu item 1")); +} +else if context->hasType(MyContext)) +{ + int id = popup->insertItem(... + ... +} +... +@endcode +*/ +class Context +{ +public: + /**Pre-defined context types. More may be added so it is possible to add custom + contexts. <strong>We reserve enum values until 1000 (yeah, it is one thousand ) + for kdevelop official context types.</strong>*/ + enum Type + { + EditorContext, /**<Editor context menu.*/ + DocumentationContext, /**<Documentation browser context menu.*/ + FileContext, /**<File context menu.*/ + ProjectModelItemContext, /**<Project tree context menu.*/ + CodeModelItemContext /**<Class tree context menu.*/ + }; + + /**Implement this in the context so we can provide rtti.*/ + virtual int type() const = 0; + + /**@return The type of this Context, so clients can discriminate + between different file contexts.*/ + virtual bool hasType(int type) const; + +protected: + /**Constructor.*/ + Context(); + + /**Destructor.*/ + virtual ~Context(); +}; + +/**A context for the popup menu in the editor.*/ +class EditorContext: public Context +{ +public: + /**Builds a context for an editor part. + @param url The url of a file in the editor. + @param line The line number where the cursor is. + @param col The column number where the cursor is. + @param linestr The content of the line where the cursor is. + @param wordstr The current word under the cursor.*/ + EditorContext(const KURL &url, int line, int col, + const QString &linestr, const QString &wordstr); + + /**Destructor.*/ + virtual ~EditorContext(); + + virtual int type() const; + + /**@return The url for the file which this context was invoked for.*/ + const KURL &url() const; + + /**@return The line number for the cursor position.*/ + int line() const; + + /**@return The column number for the cursor position.*/ + int col() const; + + /**@return A QString with the content of the line which this context was + invoked for.*/ + QString currentLine() const; + + /**@return A QString containing the word near to the cursor when this + context object was created.*/ + QString currentWord() const; + +private: + class Private; + Private *d; + + EditorContext( const EditorContext &); + EditorContext &operator=( const EditorContext &); +}; + + +/** +A context for the popup menu in the documentation browser widget. +*/ +class DocumentationContext: public Context +{ +public: + + /**Builds a DocumentationContext. + @param url The URL that the context will be for. + @param selection Selected text.*/ + DocumentationContext(const QString &url, const QString &selection ); + + /**Copy constructor.*/ + DocumentationContext(const DocumentationContext &); + DocumentationContext &operator=(const DocumentationContext &); + + /**Destructor.*/ + virtual ~DocumentationContext(); + + virtual int type() const; + + /**@return The url of the document this context was invoked for.*/ + QString url() const; + + /**@return The selected text in the document.*/ + QString selection() const; + +private: + class Private; + Private *d; +}; + +/** +A context for the popup menu in file views and other parts that show files. +Context allows multiple selections of files. +*/ +class FileContext : public Context +{ +public: + /**Builds the file context using a @ref KURL::List + @param someURLs The list of selected files URLs.*/ + FileContext(const KURL::List &someURLs); + + /**Destructor.*/ + virtual ~FileContext(); + + virtual int type() const; + + /**@return A reference to the selected of URLs.*/ + const KURL::List &urls() const; + +private: + class Private; + Private *d; + + FileContext( const FileContext &); + FileContext &operator=( const FileContext &); +}; + +/** +A context for the popup menu in class views. +*/ +class CodeModelItemContext: public Context +{ +public: + /**Builds the context. + @param item Selected code model item representation. Usually a symbol from the code + like class, function, etc.*/ + CodeModelItemContext(const CodeModelItem* item); + + /**Destructor.*/ + virtual ~CodeModelItemContext(); + + virtual int type() const; + + /**@return The code model item for the selected item.*/ + const CodeModelItem* item() const; + +private: + class Private; + Private *d; + + CodeModelItemContext( const CodeModelItemContext &); + CodeModelItemContext &operator=( const CodeModelItemContext &); +}; + +/** +A context for the popup menu in project views. +*/ +class ProjectModelItemContext : public Context +{ +public: + /**Builds the context. + @param item The item to build the context from.*/ + ProjectModelItemContext(const ProjectModelItem* item); + + /**Destructor.*/ + virtual ~ProjectModelItemContext(); + + virtual int type() const; + + /**@return The code model item for the selected item.*/ + const ProjectModelItem* item() const; + +private: + class Private; + Private *d; + + ProjectModelItemContext( const ProjectModelItemContext &); + ProjectModelItemContext &operator=( const ProjectModelItemContext &); +}; + + + + +/** +A KDevCore class defines an object which takes care about the cooperation +between the various plug-in which compose KDevelop. +It defines: +- signals that can be captured for menu customization; +- notifications about opening / closing projects; +- methods to access functionality of KDevelop core; +- requests to fill project and global settings widgets; +- etc. +. +*/ +class KDevCore: public QObject +{ + Q_OBJECT +public: + /**Constructor + @param parent The QObject that's the parent of this class. + @param name The name of the class.*/ + KDevCore(QObject *parent=0, const char *name=0); + + /**Destructor.*/ + virtual ~KDevCore(); + + /**Fills the context menu. + This method should be called by a part that wants to show a + context menu. The parameter @p context should be filled with + information about the context in which this happens (see + EditorContext, DocumentationContext, ClassContext, ...). + Essentially, this method emits the signal contextMenu() + which other parts can use to hook in. + @sa Context for a detailed explanation of context menu initializations and usage. + @param popup The popup menu to fill. + @param context The pointer to a Context object of this popup menu.*/ + virtual void fillContextMenu(QPopupMenu *popup, const Context *context) = 0; + + /**Closes the current project and open the new one. You cannot use the @ref KDevPlugin::project() + * method right after opening a new project, as it will return a null pointer. + *You must wait for the eventloop to be reentered, so use a signleshot timer + *to do the job needed after the project is opened or connect a slot to the + *@ref projectOpened signal. + * @param projectFileName The file name of the project to open.*/ + virtual void openProject(const QString& projectFileName) = 0; + + /**Marks the component as running (or not running). As long as at least one + component is running, the stop button is enabled. When it is pressed, + component get a stopButtonClicked(). This is usable for plugins which + run certain commands and want KDevelop core to be notified of that. + If core is notified, it can allow the user to stop(interrupt) the command + manually by means of stop button. + @param which The plugin to mark. + @param runs true if plugin is running something, false if it is not.*/ + virtual void running(KDevPlugin *which, bool runs) = 0; + +signals: + /**Emitted after the core has done all initializations and + the main window has been shown.*/ + void coreInitialized(); + + /**A project has been opened.*/ + void projectOpened(); + + /**The project is about to be closed.*/ + void projectClosed(); + + /**The language support part has been changed.*/ + void languageChanged(); + + /**The user has clicked the stop button. + If all actions should be cancelled, pass 0 to @p which + @param which The KDevPlugin object to stop.*/ + void stopButtonClicked(KDevPlugin *which); + + /**A context menu has been requested somewhere. Components + may hook some entries into it. More information on the + context can be obtained by looking for the type of + @p context and casting it accordingly. + @sa Context for a detailed explanation of context menu initializations and usage. + @param popupMenu The popup menu to fill. + @param context The Context of this popup menu.*/ + void contextMenu(QPopupMenu *popupMenu, const Context *context); + + /**Expects that a configuration page for use in the + KDevelop settings dialog is created by the component. + The configuration page is not demand-loading, it will be created before + global settings dialog is shown. Use @ref ConfigWidgetProxy in your plugin + to create demand-loading configuration pages. + @param dlg The dialog which the configuration widget should be added to.*/ + void configWidget(KDialogBase *dlg); + + /**Expects that a configuration page for use in the + Project settings dialog is created by the component. + The configuration page is not demand-loading, it will be created before + project settings dialog is shown. Use @ref ConfigWidgetProxy in your plugin + to create demand-loading configuration pages. + @param dlg The dialog which the configuration widget should be added to.*/ + void projectConfigWidget(KDialogBase *dlg); +}; + +#endif |