-
Notifications
You must be signed in to change notification settings - Fork 1k
API Overview
The MonoDevelop API is extensive and still changing. This article provides an overview of this API, explaining where to find the most important services and how to use them.
The API is split in three layers:
- The Core layer provides basic services such as logging, progress monitoring or file management which are used through the whole IDE.
- The Projects layer implements the project object model. It provides methods for reading, writing and building projects, as well as a parsing service.
- The top layer is the IDE itself.
It is worth noting that the Core and Projects layers are not tied to the IDE application, so it is possible to create independent applications which make use of those services.
The add-in engine API is explained in detail in the Mono.Addins Reference Manual.
The object MonoDevelop.Core.Runtime.SystemAssemblyService provides methods for getting installed frameworks and runtimes. Once you have a TargetRuntime object you can query information about installed packages and add-ins. Using this API you can:
- Get a list of installed runtimes.
- Get a list of installed frameworks, for each runtime.
- Get a list of packages installed for a given runtime.
- Get the list of assemblies of a package
- Given an assembly name, find the location of the assembly, or the package providing it
- Given a partial assembly name, get the full name
Here are some classes you can use:
| Type | Description |
|---|---|
|
MonoDevelop.Core Runtime.SystemAssemblyService |
Provides methods for getting installed frameworks and runtimes. |
|
MonoDevelop.Core.Assemblies TargetRuntime |
Information about a runtime. Provides methods for getting installed packages and assemblies |
|
MonoDevelop.Core.Assemblies TargetFramework |
Information about a framework |
|
MonoDevelop.Core.Assemblies SystemAssembly |
Information about an assembly, including name, version and location. |
Add-ins must use add-in localizers for translating strings in the code. See the Getting Localized Strings of the Mono.Addins reference manual to learn how to do it.
The class MonoDevelop.Core.GettextCatalog can be used to get translated strings in the main IDE solution.
| Type | Description |
|---|---|
|
MonoDevelop.Core GettextCatalog |
This class can be used to get translated strings in the main IDE solution. |
|
Mono.Addins AddinManager.CurrentLocalizer |
To be used in add-ins to get translated strings. |
| Type | Description |
|---|---|
|
MonoDevelop.Core LoggingService |
This class provides methods for logging debug, information, warning and error messages. Those messages are written to the console from which MD started and also to an internal log shown in the Message Log pad (View/Other Windows/Message Log). |
| Type | Description |
|---|---|
|
MonoDevelop.Core PropertyService |
This class can be used to store global configuration properties. Add-ins can use it to store custom configuration information (although that information won't be removed if the add-in is uninstalled). The PropertyService class also has a ConfigPath property for getting the path where all configuration information is stored, so add-ins can also store create configuration files there. |
|
MonoDevelop.Core Properties |
Allows creating nested groups of properties. |
The MonoDevelop.Core.StringParserService class can be used to parse strings which contain tags and replace them with actual values. For example:
var values = new Dictionary<string,object> ();
values ["name"] = "Novell Inc";
values ["year"] = 2010;
string result = StringParserService.Parse ("Copyright (c) ${year} ${name)", values);
// The result will be: "Copyright (c) 2010 Novell Inc"This service is explained in detail in the String Parser Service article.
The object MonoDevelop.Core**.Runtime.ProcessService** offers several ways of starting processes.
ProcessService has many overloads of the method StartProcess which allows running a process. Those overloads make it easier to collect output from the process.
To execute an assembly, instead of starting a "mono" process, the best option is to use the TargetRuntime.ExecuteAssembly method. For example:
Runtime.SystemAssemblyService.CurrentRuntime.ExecuteAssembly ("someAssembly.exe", "some args");This method allows running an assembly using a specific runtime, and will work both for Mono and MS.NET runtimes.
The CreateExternalProcessObject method can be used to create an object which runs outside the main MonoDevelop process. ProcessService takes care of creating the external process and setting up the remote comunication. The methods takes as parameter the type of the object to create, which must be of type ***MonoDevelop.Core.Execution.***RemoteProcessObject.
| Type | Description |
|---|---|
|
MonoDevelop.Core FileService |
Provides methods for managing files and directories. It is important to notice that file operations done through this class are monitorized by the IDE and by add-ins. FileService has several events which are fired when files are modified, moved, deleted, etc. So for example, if you need to delete a file, you have to do it through FileService if you want the IDE to react to the deletion (e.g. the IDE would automaticaly close the file if it is opened). |
|
MonoDevelop.Core FilePath |
This struct represents a file or directory path. All API using paths must use this class, because it takes into account file system particularities of the running platform. For example, path comparisons on windows will be case insensitive. |
The MonoDevelop.Projects.Text namespace has several classes which help working with text files.
| Type | Description |
|---|---|
|
MonoDevelop.Projects.Text TextFile |
This class can be used to load/save a text file using a specific encoding or automatically detecting it, and provides methods for accessing the content, such as for example file/column to offset conversion. |
|
MonoDevelop.Projects.Text TextFileReader |
A text reader with the same encoding detection that the TextFile class supports. |
|
MonoDevelop.Projects.Text TextFormatter |
This class can be used to format a block of text with some provided formatting options. It could be used for example to generate a text of file using a tab sice of 4 and limiting lines to 80 columns. The formatting can take care of converting tabs to spaces and wrapping long lines. |
Many methods in the MonoDevelop API take as parameter a progress monitor, an object implementing IProgressMonitor. Those are usually methods which perform long operations and which use this object to provide feedback about the progress of the operation.
There are also several methods in the API which execute asynchronously. Those methods sometimes take an IProgressMonitor as parameter (where progess will be reported) and return an IAsyncOperation object, which the caller can use to control the execution of the operation. For example, it allows canceling the operation or waiting until completed.
The MonoDevelop.Core.ProgressMonitoring and MonoDevelop.Core.Gui.ProgressMonitoring namespaces provide several useful classes for implementing progress monitors and for combining them.
| Type | Description |
|---|---|
|
MonoDevelop.Core.ProgressMonitoring NullProgressMonitor |
This is the most basic implementation of a progress monitor. It doesn't report progress anywere, although it is fully functional. For example, you can get an IAsyncOperation object from the AsyncOperation property you can use to cancel the operation. This class can be also used as a base class for more complex progress monitors. |
|
MonoDevelop.Core.ProgressMonitoring SimpleProgressMonitor |
A simple progress monitor which keeps track of progress in a ProgressTracker object, acessible through a protected property. It is useful as a base class for implementing progress monitors. |
|
MonoDevelop.Core.ProgressMonitoring ConsoleProgressMonitor |
A progress monitor which logs output to the standard output. |
|
MonoDevelop.Core.ProgressMonitoring SynchronizedProgressMonitor |
A progress monitor that wraps another progress monitor and makes it thread safe. |
|
MonoDevelop.Core.ProgressMonitoring AggregatedProgressMonitor |
This class can be used to aggregate several progress monitor in a single one. For example, you can use it to show the progress in several monitors at the same time, such as a log window and the status bar. You would create an AggregatedProgressMonitor instance, and then you would register the other monitors on it. Then you would provide the aggregated monitor to the method running the operation. |
|
MonoDevelop.Core.ProgressMonitoring **AsyncOperation |
An implementation of IAsyncOperation. You can use it when implementing your own progress monitor. |
|
MonoDevelop.Core.ProgressMonitoring LogTextWriter |
This TextWriter subclass allow chaining several text writers. All text written to the writter will be replicated to all chained writters. |
|
MonoDevelop.Core.ProgressMonitoring AggregatedOperationMonitor |
This class can be used to synchronize asynchronous operations. For example, when implementing a method which takes an IProgressMonitor as parameter and which needs to internally execute an asynchronous operation and wait for it to complete. You would do something like this: |
public void DoLongLastingOperation (IProgressMonitor monitor) {
// ...
AggregatedOperationMonitor om = new AggregatedOperationMonitor (monitor);
IAsyncOperation aop = StartSomeAsyncOperation ();
om.AddOperation (aop);
om.WaitForCompleted ();
om.Dispose ();
// ....
}In this example, DoLongLastingOperation needs to internally execute an async operation. The AggregatedOperationMonitor object wraps the progress monitor of the method, and will propagate cancel requests to the child async operations.
MonoDevelop provides a data serializer which can be used by add-ins to serialize data to files. This serializer is also used by the project service to read and write projects and solutions. This API is available in the MonoDevelop.Core.Serialization namespace.
See Using The Data Serializer for more information.
| Type | Description |
|---|---|
|
MonoDevelop.Core.Gui DesktopService |
This class can be used to query some platform-specific information such as mime type data and installed applications. |
|
MonoDevelop.Core.Gui DesktopApplication |
Provides information about an installed |
The class MonoDevelop.Core.Gui.ImageService provides several methods for managing images and stock icons:
| Type | Description |
|---|---|
| GetPixbuf (), GetColourBlock (), GetImage () | Get a Gdk.Pixbuf or Gtk.Image from an icon name and size |
| GetStockId (), GetStockIdFromResource () | Get an icon name for a file or resource containing an image |
The class MonoDevelop.Core.Gui.MessageService provides methods for showing alert and other message dialogs.
Here are some of the most useful methods:
| Type | Description |
|---|---|
| ShowException () | Shows an error message with detailed information about an exception (this information is hidden by default, but it can be made visible by the user). |
| ShowError () | Shows an error message. |
| ShowWarning () | Shows a warning message. |
| Confirm () | Shows a confirmation message to the user. The message dialog will have two buttons: Cancel and an AlertButton provided by the caller. |
| AskQuestion () | Shows a message dialog asking a question to the user, and offers a set of AlertButtons the user can click on to answer. |
| GetTextResponse () | Presents a question and an entry to the user. |
Some of those methods take a MonoDevelop.Core.Gui.AlertButton as parameter. There are several pre-defined alert buttons, such as AlertButton.Ok, AlertButton.Close, AlertButton.Cancel, etc (all defined as static members of AlertButton). You can also create your own AlertButton instances with custom icons and response codes.
The arguments for the Confirm and AskQuestion methods can also be provided using objects of type ConfirmationMessage and QuestionMessage respectively. Using those objects it is possible to specify the same arguments available in the other overloads, but they allow specifying additional options:
| Type | Description |
|---|---|
| AllowApplyToAll | When set, the message dialog will show a checkbox with the message "Apply to all". If the user activates it, subsequent calls to Confirm or AskQuestion will automatically return the value selected when the option was activated. |
| AddOption () | Adds an additional option to the dialog, which is shown as a checkbox. |
| GetOptionValue () | Returns the value of an option. |
| SetOptionValue () | Sets the value of an option. |
Here is an example:
public static void DeleteFiles (string[] files)
{
// Creates the confirmation dialog data object and specifies that
// it has to show the "Apply to all" checkbox
ConfirmationMessage msg = new ConfirmationMessage ();
msg.ConfirmButton = AlertButton.Delete;
msg.ApplyToAllButton = true;
foreach (string file in files) {
// Shows the confirmation dialog to the user
// If the user activated the "Apply to all" checkbox,
// this call will not show the dialog and will return the value
// selected when the option was activated.
msg.Text = string.Format ("Do you want to delete the file '{0}'?", file);
if (MessageService.Confirm (msg))
File.Delete (file);
}
}There are also a couple of dialogs which can be used to display messages:
| Type | Description |
|---|---|
|
MonoDevelop.Core.Gui.Dialogs ErrorDialog |
A generic error dialog. |
|
MonoDevelop.Core.Gui.Dialogs MultiMessageDialog |
A dialog which allows displaying a set of messages (errors or warnings). It can be used for to show a list of errors and warnings reported through a progress monitor. |
MonoDevelop implements several widgets which can be reused by add-ins:
| Type | Description |
|---|---|
|
MonoDevelop.Component FileEntry |
An entry with a button which allows selecting a file. |
|
MonoDevelop.Components FolderEntry |
An entry with a button which allows selecting a folder |
|
MonoDevelop.Components ListView |
A simple list view which shows an icon and a label for every item. |
|
MonoDevelop.Components TooltipWindow |
Abstract class which implements most of the functionality required for displaying custom tooltip windows. |
|
MonoDevelop.Components DataGrid |
A simple data grid (used for example to display database query results). |
|
MonoDevelop.Components.Chart BasicChart |
A simple chart. |
|
MonoDevelop.Components.PropertyGrid PropertyGrid |
A property grid which can automatically show and allows editing the properties of an object (based on System.ComponentModel). |
| MonoDevelop.Ide.Gui.Components* ExtensibleTreeView | A tree view whose behavior can be customized and extended by add-ins. |
The Projects layer implements the project object model. It provides methods for reading, writing and building projects, as well as a parsing service.
|
MonoDevelop.Projects.Services
MonoDevelop.Ide.Gui |
This class provides several methods for:
|
|
MonoDevelop.Projects.CodeGeneration CodeRefactorer |
This class can be used to generate code in new or existing classes. The api is language-agnostic, although not all operations are available for all languages. The most important operations are:
|
| Type | Description |
|---|---|
|
MonoDevelop.Core.Gui DesktopService |
This class can be used to query some platform-specific information such as mime type data and installed applications. |
|
MonoDevelop.Core.Gui DesktopApplication |
Provides information about an installed |
| Type | Description |
|---|---|
|
MonoDevelop.Projects.Dom.Parser ProjectDomService |
|
|
MonoDevelop.Projects.Dom.Parser ProjectDom |
| Type | Description |
|---|---|
|
MonoDevelop.Projects LanguageBindingService |
The obect MonoDevelop.Ide.Gui.IdeApp.Workbench provides all you need to show and manage information in the main window of the IDE. It allows opening and managing documents (files), pads (such as the solution pad or the errors pad), and the main window layout.
The obect MonoDevelop.Ide.Gui.IdeApp.Workbench provides several operations for working with documents:
| Member | Description |
|---|---|
| Documents | This property returns a list of all documents (files) opened in the IDE. |
| ActiveDocument | Returns the document that has the keyboard focus. |
| GetDocument () | Returns the document for the given file name. |
| SaveAll () | Saves all documents. |
| CloseAllDocuments () | Closes all documents. |
| GetFileViewers () | Given a file name, returns a set of FileViewer objects which can be used to open the file. |
| OpenDocument () | Opens a document. It has several overloads, which allow opening a document from a file, or using a specific view implementation. If the file is already opened, the document will be activated. |
| NewDocument () | Creates a new unsaved document. |
| GetFileViewers () | Returns a list of FileViewer objects you can use to open a given file. |
To access the content of a document you need to get a MonoDevelop.Ide.Gui.Document object. You can get it using some of the properties and methods of the MonoDevelop.Ide.Gui.IdeApp.Workbench object (see above).
Here are some of the most useful methods and properties of the Document class:
| Member | Description |
|---|---|
| Name | Display name of the document |
| FileName | Name of the file that the document represents. |
| IsFile | Returns true if the document is a file (for example, the welcome page is a document, but it doesn't represent a file). |
| IsDirty | Gets or sets the modified flag of the document |
| Project | Project to which the file is bound (can be null). |
| TextEditor | If the document is a text editor, returns an object which can be used to manipulate the content of the editor (null otherwise). |
| GetContent (Type) | Given an interface type, it returns an implementation of that interface, provided by the view showing the document. |
| Select () | Brings the document to the front and gives it the focus. |
| Save () | Saves the document, asking for the file name if not set. |
The Workbench object provides the following methods for managing pads:
| Member | Description |
|---|---|
| Pads | A collection of all pads (visible or not) |
| ShowPad () | Registers a new pad and shows it in the main window. |
| AddPad () | Same as ShowPad, but it doesn't show the pad. The pad will be available in the View menu, but it won't be visible by default. |
| GetPad<T> () | Returns a pad which has an object of the given type as content. |
The obect MonoDevelop.Ide.Gui.IdeApp.Workbench.StatusBar provides several operations for showing information in the status bar:
| Member | Description |
|---|---|
| ShowMessage () | Displays a message and an optional icon in the status bar. |
| ShowError () | Displays an error message in the status bar. |
| ShowWarning () | Displays an warning message in the status bar. |
| ShowStatusIcon () | Shows an icon at the right of the status bar. This method returns a StatusIcon object you can use to manage and get events from that icon. For example, you can set the tooltip, make it blink, or get an EventBox which will fire mouse events for the icon. |
| CreateContext () | Creates a new status bar context (see below) |
It is also possible to show a progress bar in the status bar by using a status bar progress monitor. You can get such monitor from MonoDevelop.Ide.Gui.IdeApp.Workbench.ProgressMonitors.GetStatusProgressMonitor ().
The CreateContext() method returns an object of type StatusBarContext which can be used to show messages in the status bar, just like when you call ShowMessage directly on the status bar. The difference is that when the StatusBarContext object is disposed, the message shown through the context will be cleared, restoring any message previous to the context creation.
Status bar contexts are useful for example to display temporary progress status, or to show some information while the user is hovering over some visual component.
Here is an example:
// Display "Ready" in the status bar
IdeApp.Workbench.StatusBar.ShowMessage ("Ready");
StatusBarContext ctx = IdeApp.Workbench.StatusBar.CreateContext ();
using (ctx) {
ctx.ShowMessage ("Doing some work");
// The status bar now shows "Doing some work"
...
}
// When the context is disposed, the old message is restored,
// so the status bar will now show "Ready" againThe following methods are defined in the MonoDevelop.Ide.Gui.IdeApp.Workbench object.
| Member | Description |
|---|---|
| CurrentLayout | This property allows getting or setting the current layout of the main window. |
| Layouts | Returns a list of all defined layouts. |
| LockGui () | Disables all menus and toolbar buttons. |
| UnlockGui () | After calling LockGui, enables again all menus and toolbar buttons. |
The MonoDevelop.Ide.Gui.IdeApp.Workspace object provides many methods, properties and events for working with the current loaded solution (or solutions, since MonoDevelop allows opening several solutions at once). Here are some of the most important members:
| Member | Description |
|---|---|
| ActiveConfiguration | The configuration currently selected by the user. |
| IsOpen | Returns true if there is any solution open in the IDE. |
| Items | A list of all top level solutions or workspaces opened in the IDE. |
| GetAllItems<T> (), GetAllProjects (), GetAllSolutionItems<T> (), GetAllSolutions () | Those methods can be used to get a list of workspaces, solutions or solution items loaded in the IDE. It looks recursively through all workspaces and solutions. |
| OpenWorkspaceItem () | Loads a workspace or solution. |
The Project Object Model provides methods for loading, building and do all sort of operations with projects and solutions. However, those are low level operations which don't provide direct feedback to the user.
The MonoDevelop.Ide.Gui.IdeApp.ProjectOperations object provides several methods for doing the same set of operations, and it provides feedback to the user through the status bar, output pads, or other IDE resources.
The most important operations you can do with this object are:
| Member | Description |
|---|---|
| Build () | Builds a project, solution or file. Progress is shown in the status bar. Output is written in the Build Output pad. |
| Execute () | Executes a project, solution or file. The output of the process is shown in an Output pad if the Use External Console option is not set. |
| ShowOptions () | Shows the options dialog for a given project or solution. |
| Save () | Saves a project or solution. Progess is shown in the status bar. Errors and warnings are shown in a dialog. |
| AddSolutioItem () | Shows the Add Project dialog, so the user can select a project type. Then creates the project and adds it to the solution. |
Some of those operations (such as Build) are asynchronous. All asynchronous operation return an IAsyncOperation object that can be used to control the operation. It can be used for example to cancel it or to wait until it is complete.
If you need to perform a long operation in the background, the IDE offers several stock progress monitors you can use to show feedback to the user. Those progress monitors are provided by the MonoDevelop.Ide.Gui.IdeApp.Workbench.ProgressMonitors object. You can use the following methods to create new monitors:
| Member | Description |
|---|---|
| GetBuildProgressMonitor () | Creates a monitor for build operations. Progress is shown in the status bar. Output is written in the Build Output pad. |
| GetRunProgressMonitor () | Creates a monitor for execution operations. Output is written in the Application Output pad. |
| GetOutputProgressMonitor () | Creates a monitor which writes the output in an Output pad. |
| GetLoadProgressMonitor () | Creates a monitor for load operations. Progress is shown in the status bar. Errors and warnings are shown in a dialog when the operation is completed. |
| GetSaveProgressMonitor () | Creates a monitor for save operations. Progress is shown in the status bar. Errors and warnings are shown in a dialog when the operation is completed. |
| GetSearchProgressMonitor () | Creates a monitor for search operations. Progress and results of the search are shown in a Search Results pad. It supports multiple search instances. |
| GetStatusProgressMonitor () | Creates a monitor which shows progress in the status bar. |
| GetBackgroundProgressMonitor () | Creates a monitor which shows an icon in the status bar. The tooltip of the icon is the current task description. |
There are also other classes which can be used to show progress in a dialog:
| Type | Description |
|---|---|
|
MonoDevelop.Core.Gui.ProgressMonitoring MessageDialogProgressMonitor |
Shows the progress in a dialog which has a progress bar and an optional expandable output view. |
|
MonoDevelop.Core.Gui.ProgressMonitoring MultiTaskDialogProgressMonitor |
Shows the progress in a dialog which has a list of progress bars, one for each top-level task. |
The MonoDevelop.Ide.Gui.IdeApp.Preferences object has several properties for getting and setting IDE preferences. It has also events which are fired when preferences are changed.
Bulding and Running
Writing Add-ins
MonoDevelop API
MonoDevelop Design and Architecure
- The Project Model
- Error and Exception Handling
- The Command System
- The Service Model
- The Document/View Model
MonoDevelop Coding Guides