///
/// Copyright © 2003-2008 JetBrains s.r.o.
/// You may distribute under the terms of the GNU General Public License, as published by the Free Software Foundation, version 2 (see License.txt in the repository root folder).
///
using System;
using System.Collections;
using System.IO;
using System.Drawing;
using System.Windows.Forms;
using System.Xml;
namespace JetBrains.Omea.OpenAPI
{
///
/// Specifies a format of a plain or rich text string.
///
public enum TextFormat
{
///
/// The string contains plain text.
///
PlainText,
///
/// The string is a valid HTML fragment.
///
Html,
///
/// The string contains rich text in the RTF format.
///
Rtf
};
// -- Interfaces that are implemented by plugins -----------------------------------
///
/// The main interface that must be implemented by every Omea plugin. Manages
/// plugin startup and shutdown.
///
/// If there are several classes which implement IPlugin in an assembly,
/// all of them are loaded as plugins.
public interface IPlugin
{
///
/// Registers the plugin resource types, actions and other services.
///
/// This is the first method called after the plugin is loaded. It should
/// be used to register any resource types or services that could be used by other plugins.
/// To access the services provided by the core, methods of the static class
/// can be used. All core services are already available when this
/// method is called.
///
void Register();
///
/// Performs the longer initialization activities of the plugin and starts up
/// background activities, if any are necessary.
///
/// This is the second method called in the plugin startup sequence.
/// It is called after the method has already been called for
/// all plugins, so the code in this method can use the services provided by other
/// plugins.
/// To access the services provided by the core, methods of the static class
/// can be used. All core services are already available when this
/// method is called.
///
void Startup();
///
/// Terminates the plugin.
///
/// If the plugin needs any shutdown activities (like deleting temporary
/// files), these should be performed in these method. All services
/// are still available when the method is called.
void Shutdown();
}
///
/// The interface which must be implemented by plugins which display their resources
/// in the resource browser preview pane.
///
/// Implementations of this interface are registered through
/// .
public interface IResourceDisplayer
{
///
/// Creates a display pane for displaying resources of a specific type.
///
/// The type of resources to be displayed.
/// The instance of the display pane, or null if displaying resources of
/// that type is not supported.
/// The instance of the display pane is used while the user is viewing
/// resources of the same type and disposed when the user switches to a resource
/// of different type.
IDisplayPane CreateDisplayPane( string resourceType );
}
///
/// Allows a component to execute commands related to its current state.
///
/// IDs of some standard commands are defined in the
/// class. Additional command IDs can be supported by different components.
public interface ICommandProcessor
{
///
/// Checks if the command with the specified ID can be executed in the current state
/// of the control.
///
/// The ID of the command.
/// true if the ID of the command is known to the control and can be
/// executed; false otherwise.
bool CanExecuteCommand( string command );
///
/// Executes the command with the specified ID.
///
/// ID of the command to execute.
void ExecuteCommand( string command );
}
///
/// The interface of the classes which manage the displaying of plugin resources.
///
/// Implementations of this interface are returned from
/// .
public interface IDisplayPane: ICommandProcessor
{
///
/// Returns the instance of the control which is embedded in the preview pane
/// when the resource is displayed.
///
/// The control used to display the resource.
Control GetControl();
///
/// Shows the data of the specified resource in the display pane.
///
/// The resource to display.
void DisplayResource( IResource resource );
///
/// Highlights the specified search result words in the resource text.
///
/// The array of references to words to be highlighted.
///
/// The array is sorted by section and then by offset within the section.
/// Use the overload to load the resource and request words highlighting with a single call. This provides for the optimized highlighting implementation which applies at the stage of loading the resource.
///
[ Obsolete( "Use the IDisplayPane2.HighlightWords(IResource, WordPtr[]) overload instead.", false ) ]
void HighlightWords( WordPtr[] words );
///
/// Ends the display of the specific resource in the display pane.
///
/// The resource which was displayed in the pane.
/// After EndDisplayResource is called, if the user switches to a resource
/// of the same type, is called to display the resource in the
/// same display pane instance. If the user switches to a resource of a different type,
/// is called to dispose of the pane.
void EndDisplayResource( IResource resource );
///
/// Disposes of the display pane.
///
/// After the core has called DisposePane, it no longer uses the pane instance.
/// If a resource of the same type needs to be displayed again, a new pane instance is created
/// by a call to .
void DisposePane();
///
/// Returns the text currently selected in the display pane as an RTF, HTML or plain-text
/// string.
///
/// The format in which the method returns the string.
/// The selected text, or null if there is no selection.
string GetSelectedText( ref TextFormat format );
///
/// Returns the text currently selected in the display pane as a plain-text string.
///
/// The selected text in plain-text format, or null if there is no selection.
string GetSelectedPlainText();
}
///
/// Defines additional functions for display panes.
///
/// 2.0
public interface IDisplayPane2: IDisplayPane
{
///
/// Shows the data of the specified resource in the display pane and highlights
/// the specified words in its text.
///
/// The resource to display.
/// The array of references to words to be highlighted. May be null, which means that no words should be highlighted and Display Pane's behavior should default to .
///
/// The array is sorted by section and then by offset within the section.
/// This overload incapsulates the behavior of and in order to provide the optimized performance.
///
void DisplayResource( IResource resource, WordPtr[] wordsToHighlight );
}
///
/// The interface of the classes which return the text of the resources for plain-text indexing.
///
public interface IResourceTextProvider
{
///
/// Passes the text of the resource as a series of plain-text fragments to the specified
/// consumer.
///
/// The resource for which the text is retrieved.
/// The consumer which accepts the text fragments.
/// true if the text was retrieved successfully, false if it was not possible
/// to retrieve the text.
/// The plugin may decide to return or not return the text based on the purpose
/// of the text request (). For example, if
/// retrieving the text takes a long time, the plugin can decide to return the text for
/// indexing and not to return the text for search result context display (and return
/// false in this case).
bool ProcessResourceText( IResource res, IResourceTextConsumer consumer );
}
///
/// Allows to disable text indexing for specific resources.
///
/// Used internally to disable indexing of file resources after a file folder has been
/// excluded from indexing.
/// 2.0
public interface IResourceTextIndexingPermitter
{
///
/// Checks if indexing the specified resource is allowed.
///
/// The resource to be indexed.
/// true if the resource should be indexed, false if the request for indexing the
/// resource should be discarded.
bool CanIndexResource( IResource res );
}
///
/// Provides icons for a specified resource type.
///
/// Implementations of this interface are registered through
/// .
public interface IResourceIconProvider
{
///
/// Returns the icon for the current state of the specified resource.
///
/// The resource for which the icon is returned.
/// The icon, or null if the default icon should be used.
Icon GetResourceIcon( IResource resource );
///
/// Returns the default icon for resources of the specified type.
///
/// The resource type.
/// The icon, or null if the default icon should be used.
Icon GetDefaultIcon( string resType );
}
///
/// Provides overlay icons that are drawn over the standard icons for the specified resource type.
///
/// Implementations of this interface are registered through
/// .
/// Implementations of this interface are chained - all overlay icon providers registered for
/// the specified resource type are queried for icons, and all icons returned by them are shown.
/// 2.0
public interface IOverlayIconProvider
{
///
/// Returns the list of icons that should be overlaid on the specified resource.
///
/// The resource for which the icons are requested.
/// The array of icons, or null if no overlay icons are available.
Icon[] GetOverlayIcons( IResource res );
}
///
/// Allows a source resource to return data streams for resources coming from this source.
///
/// An example source resource is FileFolder. If a file resource has a link with
/// the flag to a FileFolder resource,
/// when the system needs to retrieve the contents of the file, it invokes the IStreamProvider
/// registered for the FileFolder resource type and passes the file resource to its GetResourceStream
/// method.
/// Implementations of this interface are registered through
/// .
public interface IStreamProvider
{
///
/// Returns the stream containing the contents of the specified resource.
///
/// The resource for which the contents are retrieved.
/// The stream containing the resource contents, or null if it was impossible
/// to retrieve the contents.
Stream GetResourceStream( IResource resource );
}
///
/// IDs of the standard commands which can be executed through .
///
public class DisplayPaneCommands
{
///
/// Go back (in the History). Applies either to the Web browser history, or (in case it is empty) to Omea views.
///
public const string Back = "Back";
///
/// Go forward.
///
public const string Forward = "Forward";
///
/// Find a token in the resource currently being displayed.
///
public const string FindInPage = "FindInPage";
///
/// Cut to Clipboard.
///
public const string Cut = "Cut";
///
/// Copy to Clipboard.
///
public const string Copy = "Copy";
///
/// Paste from Clipboard.
///
public const string Paste = "Paste";
///
/// Print the resource currently being displayed.
///
public const string Print = "Print";
///
/// Scroll the content displayed in the preview pane one page down.
///
public const string PageDown = "PageDown";
///
/// Select all the content in the current view.
///
/// 2.0
public const string SelectAll = "SelectAll";
///
/// In-place edit the item currently selected in the current view.
///
/// 2.0
public const string RenameSelection = "RenameSelection";
///
/// Navigate to the next search result within the document.
///
/// 2.0
public const string NextSearchResult = "NextSearchResult";
///
/// Navigate to the previous search result within the document.
///
/// 2.0
public const string PrevSearchResult = "PrevSearchResult";
}
///
/// Allows to handle a number of user interface events in ,
/// resource browser and other places.
///
/// Implementations of this interface are registered through
/// .
public interface IResourceUIHandler
{
///
/// Called when the specified resource is selected in a sidebar pane.
///
/// The resource which is selected.
/// The typical action for this method is to call
/// with the list of resources
/// somehow linked to the selected resource.
void ResourceNodeSelected( IResource res );
///
/// Checks if in-place rename for the specified resource is available.
///
/// The resource which is renamed.
/// true if the rename is possible, false otherwise.
/// The in-place rename can be performed both from the resource tree view
/// and the resource browser.
bool CanRenameResource( IResource res );
///
/// Processes the in-place rename for the specified resource.
///
/// The resource which was renamed.
/// The string entered by the user as the new name of the resource.
/// true if the rename was successful, false otherwise (for example, if the
/// string entered by the user is not a legal name for the resource).
/// The in-place rename can be performed both from the resource tree view
/// and the resource browser.
bool ResourceRenamed( IResource res, string newName );
///
/// Checks if the specified resources can be dropped on the specified target resource.
///
/// The target resource for the drop, or null if
/// the handler is registered as a handler for dropping on empty space.
/// The dragged resources.
/// true if the drop is allowed, false otherwise.
bool CanDropResources( IResource targetResource, IResourceList dragResources );
///
/// Processes the drop of the specified resources on the specified target resource.
///
/// The target resource for the drop, or null if
/// the handler is registered as a handler for dropping on empty space.
/// The dropped resources.
void ResourcesDropped( IResource targetResource, IResourceList droppedResources );
}
///
/// Allows to perform complete handling of resource drag and drop in
/// , resource browser and other places. This
/// interface takes precedence over - if a
/// drag and drop handler is registered, the UI handler is not called to
/// process drag and drop.
///
/// Implementations of this interface are registered through
/// .
/// 2.0
public interface IResourceDragDropHandler
{
///
/// Called to supply data in additional formats when the specified resources are being dragged.
///
/// The dragged resources.
/// The drag data object.
void AddResourceDragData( IResourceList dragResources, IDataObject dataObject );
///
/// Called to return the drop effect when the specified data object is dragged over the
/// specified resource.
///
/// The resource over which the drag happens.
/// The containing the dragged data.
/// The drag-and-drop operations which are allowed by the
/// originator (or source) of the drag event.
/// The current state of the SHIFT, CTRL, and ALT keys,
/// as well as the state of the mouse buttons.
/// The target drop effect.
DragDropEffects DragOver( IResource targetResource, IDataObject data, DragDropEffects allowedEffect,
int keyState );
///
/// Called to handle the drop of the specified data object on the specified resource.
///
/// The drop target resource.
/// The containing the dragged data.
/// The drag-and-drop operations which are allowed by the
/// originator (or source) of the drag event.
/// The current state of the SHIFT, CTRL, and ALT keys,
/// as well as the state of the mouse buttons.
void Drop( IResource targetResource, IDataObject data, DragDropEffects allowedEffect, int keyState );
}
///
/// Allows to perform complete handling of resource rename in
/// , resource browser and other places. This
/// interface takes precedence over - if a
/// rename handler is registered, the UI handler is not called to
/// process renames.
///
/// Implementations of this interface are registered through
/// .
/// 2.0
public interface IResourceRenameHandler
{
///
/// Checks if in-place rename for the specified resource is available.
///
/// The resource which is renamed.
/// The text to be displayed in the in-place edit box.
/// true if the rename is possible, false otherwise.
bool CanRenameResource( IResource res, ref string editText );
///
/// Processes the in-place rename for the specified resource.
///
/// The resource which was renamed.
/// The string entered by the user as the new name of the resource.
/// true if the rename was successful, false otherwise (for example, if the
/// string entered by the user is not a legal name for the resource).
bool ResourceRenamed( IResource res, string newName );
}
///
/// The reason for expanding a thread in a threaded view.
///
/// 2.0
public enum ThreadExpandReason
{
///
/// The expand is requested during enumeration of items in the list view (going to
/// next unread item, Select All, or a similar operation). No expensive operations like
/// comment download should be performed.
///
Enumerate,
///
/// The expand is requested because the user clicked on the [+] button in the thread.
/// All operations required to get the children need to be performed.
///
Expand
}
///
/// Allows a plugin to control how a threaded list is built from its resources.
///
/// 2.0
public interface IResourceThreadingHandler
{
///
/// Returns the resource which is a parent of the specified resource in the thread,
/// or null if the resource is a thread root.
///
/// The resource for which the parent is returned.
/// The thread parent.
IResource GetThreadParent( IResource res );
///
/// Returns the list of resources which are children of the specified resource
/// in the thread, or an empty resource list if the resource has no children.
///
/// The resource for which the children are returned.
/// The list of children.
IResourceList GetThreadChildren( IResource res );
///
/// Checks if the specified change to a resource caused it to move to a different thread.
///
/// The resource which has changed.
/// The description of changes to the resource.
/// true if the thread has changed, false otherwise.
bool IsThreadChanged( IResource res, IPropertyChangeSet changeSet );
///
/// Checks if the specified resource can be expanded even if it does not contain
/// actual children in the resource list.
///
/// The resource to check.
/// A reason for expanding the resource defined by the
/// enumeration members. Possible reasons include UI expanding of the branch and enumeration of node children.
/// true if the resource can be expanded, false otherwise.
bool CanExpandThread( IResource res, ThreadExpandReason reason );
///
/// Called when the thread starting at the specified resource is first
/// expanded. Can be used to add real children to nodes which had only
/// virtual children.
///
/// The resource representing a node that is expanded.
/// A reason for expanding the resource defined by the
/// enumeration members. Possible reasons include UI expanding of the branch and enumeration of node children.
/// If expansion is considered to be a costly operation (for example, supposes downloading of additional resources),
/// it should not be actually initiated by enumeration operations (eg, only if user explicitly orders to expand the node should
/// the download occur). This parameter provides for judging such cases.
/// true if the expand was handled, false if the expand with that reason
/// was not handled and the expand can be requested again later.
/// 2.0
bool HandleThreadExpand( IResource res, ThreadExpandReason reason );
}
///
/// Allows to perform custom painting and event handling for a column in the resource browser.
///
/// Implementations of this interface are registered through
/// .
public interface ICustomColumn
{
///
/// Draws the value of the column for the specified resource.
///
/// The resource for which the value is drawn.
/// The Graphics on which the drawing is performed.
/// The rectangle in which the value is drawn.
void Draw( IResource res, Graphics g, Rectangle rc );
///
/// Draws the header of the column.
///
/// The Graphics on which the drawing is performed.
/// The rectangle in which the value is drawn.
void DrawHeader( Graphics g, Rectangle rc );
///
/// Handles the click of the left mouse button in the column.
///
/// The resource on which the mouse is clicked.
/// The coordinates, relative to the top left corner of the
/// column rectangle for the specified resource, where the mouse was clicked.
void MouseClicked( IResource res, Point pt );
///
/// Allows to show a custom context menu for the column.
///
/// The action context for the context menu actions.
/// The control owning the context menu.
/// The coordinates, relative to the control, where the context
/// menu should be shown.
/// true if a custom menu was shown; false if the standard menu should be shown.
bool ShowContextMenu( IActionContext context, Control ownerControl, Point pt );
///
/// Returns the tooltip for the column value of specified resource.
///
/// The resource for which the tooltip is retrieved.
/// The tooltip text or null if no tooltip is required.
string GetTooltip( IResource res );
}
///
/// Specifies possible modes of serializing properties to the XML representation of resources.
///
public enum SerializationMode
{
///
/// The serialization mode specified by property type flags
/// and is used.
///
Default,
///
/// The value of the property is not included in the XML serialization.
///
NoSerialize,
///
/// A checkbox for the property is shown in the "Send Resources" dialog, and the property value
/// is serialized if the checkbox is checked by the user.
///
AskSerialize,
///
/// The value of the property is included in the XML serialization.
///
Serialize
}
///
/// Allows to perform custom serialization and deserialization of resources in the XML format.
///
/// Implementations of this interface are registered through
/// .
/// The XML serialization of resources is used by the "Send Resources" feature to transmit
/// resources between different Omea database instances.
public interface IResourceSerializer
{
///
/// Called after the properties of a resource have been serialized to the specified XML node.
///
/// The parent in the serialization tree of the resource being
/// serialized.
/// The resource which has been serialized.
/// The node to which the resource has been serialized.
/// The method can be used to perform custom serialization of property values
/// which are not serialized by default, or to serialize data (like e-mail bodies) which
/// is not stored in the resource properties.
void AfterSerialize( IResource parentResource, IResource res, XmlNode node );
///
/// Called to match a temporary resource received from XML to an existing resource in the
/// Omea database, and to restore the custom data which was serialized by .
///
/// The parent in the serialization tree of the resource being
/// serialized.
/// The temporary representation of the resource which has been restored
/// from the XML serialization.
/// The XML node containing the serialization of the resource.
/// The received resource res, or an existing resource in the Omea database
/// which matches the received resource.
/// If the received resource matches a resource already existing in the Omea database
/// (for example, there is already a news article with the same ID), the method should copy
/// new information (for example, properties which do not exist) to the existing resource and return
/// it. If the resource doesn't match any existing resources, the received instance should be
/// returned from the method.
IResource AfterDeserialize( IResource parentResource, IResource res, XmlNode node );
///
/// Allows to specify the serialization mode of resource properties on per-resource basis.
///
/// The resource the properties of which are being serialized.
/// The name of the type of the property which is being serialized.
/// The serialization mode.
SerializationMode GetSerializationMode( IResource res, string propertyType );
}
///
/// Allows to perform "semantic delete" of resources, to move resources to the Deleted Items
/// view and to recover them from that view.
///
/// Implementations of this interface are registered through
/// .
/// 2.0
public interface IResourceDeleter
{
///
/// Shows a dialog to confirm the deletion of the specified resources.
///
/// The resources to delete.
/// If true, confirmation for permanent delete is requested.
/// If true, the delete confirmation dialog should include
/// the "Cancel" button.
/// DialogResult.Yes if the resources should be deleted, DialogResult.No if the
/// deletion of these resources should be skipped, DialogResult.Cancel if the entire delete
/// operation is cancelled.
DialogResult ConfirmDeleteResources( IResourceList resources, bool permanent, bool showCancel );
///
/// Checks if deleting of the specified resource is allowed.
///
/// The resource to delete. Can be null, in that case checks whether deletion of arbitrary resource in specified mode is allowed.
/// Mode of requested resource deletion (permanent or non-permanent).
/// true if the delete is allowed, false if the delete action should be disabled.
bool CanDeleteResource( IResource res, bool permanent );
///
/// Answers whether non-permanent deletion can be ignored. This is the general mechanism
/// to exclude potentially dangerous behavior if permanent deletion performs unrevertable results
/// like cleaning information on remote server. This has two effects - user explicitely has to
/// press "Shift" key for permanent deletion and rules can not blindly call permanent deletion.
///
/// true if the non-permanent deletion can be ignored.
/// 2.1
bool CanIgnoreRecyclebin();
///
/// Deletes the specified resource.
///
/// The resource to delete.
/// If the resource is currently not in the Deleted Items view, moves it to the Deleted
/// Items view. If the resource is already in the Deleted Items view, deletes it permanently.
void DeleteResource( IResource res );
///
/// Deletes the specified resource permanently.
///
/// The resource to delete.
void DeleteResourcePermanent( IResource res );
///
/// Moves the specified resource from the Deleted Items view to its original view.
///
/// The resource to undelete.
void UndeleteResource( IResource res );
}
///
/// Allows to define the HTML representation of the resources of a particular plugin.
///
/// 2.0
public interface INewspaperProvider
{
///
/// Returns the text that is included in the styles section of the header for the
/// specified resource type.
///
/// The resource type for which the styles are being requested.
/// Writer to which the additional styles should be submitted. If no additional styles are required, leave it intact.
void GetHeaderStyles( string resourceType, TextWriter writer );
///
/// Returns the complete HTML representation of the specified item, including its title, body, and footer (if any).
///
/// The item to show as HTML.
/// A writer to which the HTML representation of the given item should be dumped.
void GetItemHtml( IResource item, TextWriter writer );
}
///
/// A generic delegate for calling a function with one parameter of type .
///
public delegate void ResourceDelegate( IResource res );
///
/// A generic delegate for calling a function with one parameter of type .
///
public delegate void ResourceListDelegate( IResourceList resList );
// -- Interfaces that are implemented by the core and can be used by plugins -----
///
/// Identifies a pane of the status bar which presents status and progress messages related to a specific category of tasks (UI, resource, network, etc).
///
///
/// To write messages to the status bar, you need to obtain an instance of the status bar writer for the specific status bar pane by calling the method of the interface which can be obtained from .
///
public enum StatusPane
{
///
/// A status bar pane that displays the UI descriptions and hints.
///
UI,
///
/// A status bar pane to display the network-related messages, such as download progress and status.
///
Network,
///
/// A status bar pane to display the resource operations details.
///
ResourceBrowser
};
//-------------------------------------------------------------------------
///
/// Implements custom calculation of unread counts for a view.
///
/// Implementations of this interface are registered through
/// .
public interface IUnreadCountProvider
{
///
/// Returns the list of resources in the specified view.
///
/// The returned list of resources is intersected with the list of resources
/// which have the IsUnread flag.
///
/// The view for which the unread count is calculated.
/// The list of resources matching the view.
IResourceList GetResourcesForView( IResource viewResource );
}
///
/// Manages the updating of unread counts for resources.
///
public interface IUnreadManager
{
///
/// Registers a provider of unread counts for the specified resource type.
///
/// Providers are used when the unread counts are computed in a more
/// complicated way than simply counting resources with the IsUnread property
/// linked to the resource. For example, resources of type SearchView have an
/// unread count provider.
/// The resource type for which the unread count provider
/// is registered.
/// The unread count provider implementation.
void RegisterUnreadCountProvider( string resType, IUnreadCountProvider provider );
///
/// Returns the unread counter which is displayed for the specified resource
/// in the current unread state.
///
/// The resource to get the count for.
/// The count of unread resources for the specified resource.
int GetUnreadCount( IResource res );
///
/// Invalidates unread counters of all states for the specified resource,
/// forcing them to be recalculated when they are next accessed.
///
/// The resource for which the counters are invalidated.
void InvalidateUnreadCounter( IResource res );
}
///
/// Controls the progress window which is displayed at program startup and when
/// is used.
///
public interface IProgressWindow
{
///
/// Displays the specified text in the progress window.
///
/// The percentage to be shown in the progress bar (0 to 100).
/// The message to be displayed in the first line of the progress window.
/// The message to be displayed in the second line of the progress window,
/// after the "Elapsed Time" indicator, or null if no custom message should be displayed in the second line.
void UpdateProgress( int percentage, string message, string timeMessage );
}
///
/// Represents a facility for writing messages into the Omea main window status bar. Use to obtain this interface.
///
///
/// A status writer is thread-safe and may be invoked from any thread.
/// The functions won't do synchronous cross-thread calls or somehow else allow a reentrancy to occur.
/// When a status writer (an object providing the interface) is created with , it gets bound to a specific status bar pane, as specified by a enumeration member passed to the method. Generally, the status pane should be used for displaying status messages related to actions originating directly from user input. Background tasks should occupy the other panes, depending on their type (resource-processing-related or network-operations-related), or the thread they are executing on.
/// The status writers should not be shared between different simultaneous tasks, instead, should be called individually, each time producing a new instance of the status writer with a particular task set as owner.
/// It's important to understand the Omea status bar usage model which significantly differs from one of the orthodox "Application.StatusBar" property. In the case of that property you would just throw it a new value to be displayed immediately, and forget about it. The value would be shown until some other caller supplied an alternative.
/// The Omea Status Writer was specially designed for simultaneous use by many consumers. It struggles for the status bar display time for you. Once given a string, it then tries to show it again and again when the status bar is not occupied by another task. Other status bar consumers may override your value, but as soon as they need the status bar no more, your setting will return to view. Due to this, you must explicitly resign your use of status bar (by calling ) when you don't need to display the text any more, so that others could display their information. Also, failure to do this will result in infinite persistence of your message in the status bar because it will not be overwritten by other statusbar consumers.
///
///
///
/// // Get (create) a status bar writer
/// // Attach to this class, display in the Network pane
/// IStatusWriter sw = Core.UIManager.GetStatusWriter( this, StatusPane.Network );
///
/// // Submit a message to the status bar
/// sw.ShowStatus( "Downloading…" );
///
/// Trace.WriteLine( sw.LastMessage ); // Should print "Downloading…"
///
/// // Do some lengthy operation (possibly by running async jobs)
/// …
/// …
///
/// // Resign use of status bar
/// // Unless you do it, your message will be kept in status bar infinitely
/// sw.ClearStatus();
///
/// Trace.WriteLine( sw.LastMessage == null ); // Should be True
///
///
public interface IStatusWriter
{
///
/// Shows a status bar message in the appropriate status bar pane.
///
/// Message to be displayed in the status bar. May be Null.
///
/// Don't forget to call when you need the submitted message no more so that other tasks could display their messages as well.
/// The pane to which the messages go is defined at the status writer creation, see for details.
/// If is Null or an empty string (""), the status writer clears its text in the status bar the way would do.
///
///
///
/// // Get (create) a status bar writer
/// // Attach to this class, display in the Network pane
/// IStatusWriter sw = Core.UIManager.GetStatusWriter( this, StatusPane.Network );
///
/// // Submit a message to the status bar
/// sw.ShowStatus( "Downloading…" );
///
/// Trace.WriteLine( sw.LastMessage ); // Should print "Downloading…"
///
/// // Do some lengthy operation (possibly by running async jobs)
/// …
/// …
///
/// // Resign use of status bar
/// // Unless you do it, your message will be kept in status bar infinitely
/// sw.ClearStatus();
///
/// Trace.WriteLine( sw.LastMessage == null ); // Should be True
///
///
void ShowStatus( string message );
///
/// Shows a status bar message in the appropriate status bar pane and optionally forces it to redraw immediately.
///
/// Message to be displayed in the status bar. May be Null.
/// Forces the status bar to repaint and display the updated text immediately.
/// May be useful if a lengthy operation is running on the UI thread and the application has no chance to process the painting messages normally.
///
/// Don't forget to call when you need the submitted message no more so that other tasks could display their messages as well.
/// The pane to which the messages go is defined at the status writer creation, see for details.
/// If is Null or an empty string (""), the status writer clears its text in the status bar the way would do.
///
///
///
/// // Get (create) a status bar writer
/// // Attach to this class, display in the Network pane
/// IStatusWriter sw = Core.UIManager.GetStatusWriter( this, StatusPane.Network );
///
/// // Submit a message to the status bar
/// sw.ShowStatus( "Downloading…", false ); // Do not repaint
///
/// Trace.WriteLine( sw.LastMessage ); // Should print "Downloading…"
///
/// // Do some lengthy operation (possibly by running async jobs)
/// …
/// …
///
/// // Resign use of status bar
/// // Unless you do it, your message will be kept in status bar infinitely
/// sw.ClearStatus();
///
/// Trace.WriteLine( sw.LastMessage == null ); // Should be True
///
///
void ShowStatus( string message, bool repaint );
///
/// Cancels the status bar message submitted through this status bar writer and allows other tasks to display their messages in this status bar pane.
///
///
/// It's important to understand the Omea status bar usage model which significantly differs from one of the orthodox "Application.StatusBar" property. In the case of that property you would just throw it a new value to be displayed immediately, and forget about it. The value would be shown until some other caller supplied an alternative.
/// The Omea Status Writer was specially designed for simultaneous use by many consumers. It struggles for the status bar display time for you. Once given a string, it then tries to show it again and again when the status bar is not occupied by another task. Other status bar consumers may override your value, but as soon as they need the status bar no more, your setting will return to view. Due to this, you must explicitly resign your use of status bar (by calling ) when you don't need to display the text any more, so that others could display their information. Also, failure to do this will result in infinite persistence of your message in the status bar because it will not be overwritten by other statusbar consumers.
///
///
///
/// // Get (create) a status bar writer
/// // Attach to this class, display in the Network pane
/// IStatusWriter sw = Core.UIManager.GetStatusWriter( this, StatusPane.Network );
///
/// // Submit a message to the status bar
/// sw.ShowStatus( "Downloading…" );
///
/// Trace.WriteLine( sw.LastMessage ); // Should print "Downloading…"
///
/// // Do some lengthy operation (possibly by running async jobs)
/// …
/// …
///
/// // Resign use of status bar
/// // Unless you do it, your message will be kept in status bar infinitely
/// sw.ClearStatus();
///
/// Trace.WriteLine( sw.LastMessage == null ); // Should be True
///
///
void ClearStatus();
///
/// The last message supplied to this status writer thru that is currently being displayed in the appropriate status pane, or Null, if the status writer has been cleared with or as a result of a call to with an empty string ("") or Null parameter.
///
///
/// Setting status text to an empty string ("") through the method causes this property to return the Null value.
/// It's important to understand the Omea status bar usage model which significantly differs from one of the orthodox "Application.StatusBar" property. In the case of that property you would just throw it a new value to be displayed immediately, and forget about it. The value would be shown until some other caller supplied an alternative.
/// The Omea Status Writer was specially designed for simultaneous use by many consumers. It struggles for the status bar display time for you. Once given a string, it then tries to show it again and again when the status bar is not occupied by another task. Other status bar consumers may override your value, but as soon as they need the status bar no more, your setting will return to view. Due to this, you must explicitly resign your use of status bar (by calling ) when you don't need to display the text any more, so that others could display their information. Also, failure to do this will result in infinite persistence of your message in the status bar because it will not be overwritten by other statusbar consumers.
///
///
///
/// // Get (create) a status bar writer
/// // Attach to this class, display in the Network pane
/// IStatusWriter sw = Core.UIManager.GetStatusWriter( this, StatusPane.Network );
///
/// // Submit a message to the status bar
/// sw.ShowStatus( "Downloading…" );
///
/// Trace.WriteLine( sw.LastMessage ); // Should print "Downloading…"
///
/// // Do some lengthy operation (possibly by running async jobs)
/// …
/// …
///
/// // Resign use of status bar
/// // Unless you do it, your message will be kept in status bar infinitely
/// sw.ClearStatus();
///
/// Trace.WriteLine( sw.LastMessage == null ); // Should be True
///
///
string LastMessage{ get; }
///
/// Shows a status bar message in the appropriate status bar pane and automatically removes it after a given time span.
///
/// Message to be displayed in the status bar. May be Null.
/// Expiration period, in seconds, after which the message will be automatically revoked from the status bar. 0 means no expiration.
/// Use of this function makes it unnecessary to call the function to reveal the status bar of your message.
/// You should not mix calls to the timed and untimed versions of because the timed version will erase the status message even if gets overwritten by a non-timed call by that moment. In the contrary, multiple calls to the timed function will prolongate the time-to-live of the status message accordingly, regardless of whether their time spans overlap or not.
///
///
///
/// // Get (create) a status bar writer
/// // Attach to this class, display in the Network pane
/// IStatusWriter sw = Core.UIManager.GetStatusWriter( this, StatusPane.Network );
///
/// // Submit a message to the status bar
/// // It will be automatically revoked ten seconds later
/// sw.ShowStatus( "Download completed.", 10 );
///
///
/// 2.1
void ShowStatus(string message, int nSecondsToKeep);
}
///
/// Allows to hide certain nodes from an and other tree views.
///
/// If the filter conditions change, the tre can be refiltered with a call to
/// .
public interface IResourceNodeFilter
{
///
/// Checks if the node for the specified resource should be displayed in the tree.
///
/// The resource to display.
/// The depth of the resource in the tree (0 if the resource is
/// a top-level node, 1 if it's a child of a top-level node, and so on).
/// true if the resource should be displayed, false if it should be hidden.
bool AcceptNode( IResource res, int level );
}
///
/// Allows to control sidebar panes which display trees of resources.
///
/// Instances of this class are obtained through
/// and related methods.
public interface IResourceTreePane
{
///
/// Registers a toolbar button for the local toolbar in the tree pane. The button
/// icon is specified as an Icon instance.
///
/// The action which is registered.
/// The icon shown on the button.
/// The text shown on the button, or null if the button contains only an icon.
/// The tooltip shown for the button.
///
/// The filters which provide additional control over the state of the action. Can be equal to
/// null or an empty array if no additional filters are needed.
/// If the filters have marked the presentation as hidden, the Update() method of the
/// action itself is not called.
///
void RegisterToolbarAction( IAction action, Icon icon, string text, string tooltip,
IActionStateFilter[] filters );
///
/// Registers a toolbar button for the local toolbar in the tree pane. The button
/// icon is specified as an Icon instance.
///
/// The action which is registered.
/// The icon shown on the button.
/// The text shown on the button, or null if the button contains only an icon.
/// The tooltip shown for the button.
///
/// The filters which provide additional control over the state of the action. Can be equal to
/// null or an empty array if no additional filters are needed.
/// If the filters have marked the presentation as hidden, the Update() method of the
/// action itself is not called.
///
void RegisterToolbarAction( IAction action, Image icon, string text, string tooltip,
IActionStateFilter[] filters );
///
/// Adds a node filter that will show or hide certain nodes in the tree.
///
/// The node filter instance.
void AddNodeFilter( IResourceNodeFilter nodeFilter );
///
/// Clears and recreates the tree when the conditions of a node filter have changed.
///
/// If true, the selection is restored to the same node
/// after the rebuild. If false, all branches are collapsed after the rebuild, and the
/// default selection is used.
void UpdateNodeFilter( bool keepSelection );
///
/// Sets the selection to the specified resource in the tree and, if necessary,
/// expands its parent branches.
///
/// The resource to select.
void SelectResource( IResource res );
///
/// Initiates in-place editing for the specified resource node.
///
/// The resource for which the display name should be edited.
void EditResourceLabel( IResource res );
///
/// Expands the parent nodes of the specified resource node.
///
/// The resource for which the parents should be expanded.
void ExpandParents( IResource res );
///
/// Allows dropping resources on an empty space in the pane and sets the specified handler
/// to process such drops.
///
/// The handler which is invoked when resources are
/// dropped over the empty space.
[Obsolete]
void EnableDropOnEmpty( IResourceUIHandler emptyDropHandler );
///
/// Allows dropping resources on an empty space in the pane and sets the specified drag
/// and drop handler to process such drops.
///
/// The handler which is invoked when resources are
/// dropped over the empty space.
/// 2.0
void EnableDropOnEmpty( IResourceDragDropHandler emptyDropHandler );
///
/// If true, new nodes which are added to the tree are automatically selected.
///
bool SelectAddedItems { get; set; }
///
/// Gets and sets the ID of the directed link property which links a resource node
/// to its parent.
///
int ParentProperty { get; set; }
///
/// Gets and sets the resource types which are used to filter the pane content when
/// a workspace is active.
///
/// When a workspace is active, the top-level resources displayed in the pane
/// are resources of the specified types directly linked to the workspace resource.
string[] WorkspaceFilterTypes { get; set; }
///
/// Gets the resource currently selected in the tree pane.
///
IResource SelectedNode { get; }
///
/// Gets or sets the callback used to return text of tooltips for items shown in the tree pane.
///
/// 2.0
ResourceToolTipCallback ToolTipCallback { get; set; }
}
///
/// The callback used to get the tooltips to show for IResourceTreePane items.
///
/// 2.0
public delegate string ResourceToolTipCallback( IResource res );
///
/// Allows to control the sidebar at the right part of the screen.
///
public interface ISidebar
{
///
/// Registers a pane to be displayed in the right sidebar.
///
/// The pane instance.
/// The ID of the pane.
/// The caption of the pane.
/// The icon displayed for the pane in the small toolbar at the
/// bottom of the sidebar. For the icon, an image in PNG 24x24 format is required. If image has
/// different format, it will be adjusted to fit 24x24.
void RegisterPane( AbstractViewPane viewPane, string paneId, string caption, Image icon );
///
/// Changes the caption of the pane with the specified ID.
///
/// The ID of the pane.
/// The new caption of the pane.
/// 2.0
void SetPaneCaption( string paneId, string caption );
///
/// Checks if the specified pane in the right sidebar is currently expanded.
///
/// The ID of the pane to check.
/// true if the pane is expanded, false otherwise.
bool IsPaneExpanded( string paneId );
///
/// Expands or collapses the specified pane in the right sidebar.
///
/// The ID of the pane to expand or collapse.
/// true if the pane should be expanded, false if it should be collapsed.
void SetPaneExpanded( string paneId, bool expanded );
///
/// Gets the number of panes registered in the right sidebar.
///
int PanesCount { get; }
///
/// Returns the instance of the pane with the name.
///
/// The name of the pane to retrieve.
/// The pane instance, or null if there is no such pane in the current tab.
/// 2.1
AbstractViewPane GetPane( string name );
}
///
/// Allows to control the left sidebar switcher (which supports showing different sidebars
/// depending on the active tab).
///
public interface ISidebarSwitcher
{
///
/// Registers a custom view pane in the left sidebar.
///
/// ID of the pane which is registered.
/// ID of the tab in which the pane is shown.
/// User-visible caption of the pane.
/// Icon to show on the button which expands/collapses the pane.
/// The pane instance.
void RegisterViewPane( string paneId, string tabId, string caption, Image icon, AbstractViewPane viewPane );
///
/// Registers a standard view pane displaying a tree of resources in the left sidebar.
///
/// ID of the pane which is registered.
/// ID of the tab in which the pane is shown.
/// User-visible caption of the pane.
/// Icon to show on the button which expands/collapses the pane.
/// The root of the resource tree displayed in the pane.
/// The instance of the tree view pane.
IResourceTreePane RegisterTreeViewPane( string paneId, string tabId, string caption, Image icon,
IResource rootResource );
///
/// Registers a custom view pane in the left sidebar which serves as the resource
/// structure pane.
///
/// ID of the pane which is registered.
/// ID of the tab in which the pane is shown.
/// User-visible caption of the pane.
/// Icon to show on the button which expands/collapses the pane.
/// The pane instance.
/// The resource structure pane is the pane in which Omea tries to find the resource
/// registered as the resource location through .
///
void RegisterResourceStructurePane( string paneId, string tabId, string caption, Image icon,
AbstractViewPane viewPane );
///
/// Registers a standard pane displaying a tree of resources, which also serves as the resource
/// structure pane, in the left sidebar.
///
/// ID of the pane which is registered.
/// ID of the tab in which the pane is shown.
/// User-visible caption of the pane.
/// Icon to show on the button which expands/collapses the pane.
/// The root of the resource tree displayed in the pane.
/// The instance of the tree view pane.
/// The resource structure pane is the pane in which Omea tries to find the resource
/// registered as the resource location through .
IResourceTreePane RegisterResourceStructureTreePane( string paneId, string tabId, string caption,
Image icon, IResource rootResource );
///
/// Registers a standard pane displaying a tree of resources, which also serves as the resource
/// structure pane, in the left sidebar. The pane is automatically filtered by workspace resource
/// type when a workspace is active.
///
/// ID of the pane which is registered.
/// ID of the tab in which the pane is shown.
/// User-visible caption of the pane.
/// Icon to show on the button which expands/collapses the pane.
/// The resource type the root of which is used as the root
/// resource of the pane.
/// The instance of the tree view pane.
/// The resource structure pane is the pane in which Omea tries to find the resource
/// registered as the resource location through .
/// The root resource for a resource type is obtained through
/// .
/// When a workspace is active, the pane displays on the top level the resources
/// of rootResType type linked to the workspace. If resources of additional types
/// should be displayed, should be used.
///
IResourceTreePane RegisterResourceStructureTreePane( string paneId, string tabId, string caption,
Image icon, string rootResType );
///
/// Registers a keyboard shortcut for activating the pane with the specified ID.
///
/// The pane ID for which the shortcut is registeed.
/// The keyboard shortcut.
void RegisterViewPaneShortcut( string paneId, Keys shortcut );
///
/// Returns the instance of the "Views and Categories" pane for the active tab.
///
IResourceTreePane DefaultViewPane { get; }
///
/// Activates a pane with the specified ID.
///
/// ID of the pane to activate.
/// If the pane was hidden, it is shown. Then the focus is transferred to it.
void ActivateViewPane( string paneId );
///
/// If the active tab has the specified ID, activates the pane with the specified ID (if present)
/// and returns the pane instance. If the active tab is different, returns null.
///
/// The tab which should be active.
/// The pane ID to activate.
/// The pane instance or null if the activation failed.
AbstractViewPane ActivateViewPane( string tabId, string paneId );
///
/// Returns the ID of the pane which is currently active in the current tab.
///
/// The active pane is the pane which is currently focused, or which was last
/// focused if the focus is not currently in the sidebar.
string ActivePaneId { get; }
///
/// Returns the instance of the pane with the specified ID in the current tab.
///
/// The ID of the pane to retrieve.
/// The pane instance, or null if there is no such pane in the current tab.
AbstractViewPane GetPane( string paneId );
///
/// Returns the instance of the pane with the specified ID in the specified tab.
///
/// The ID of the tab for which the pane is retrieved.
/// The ID of the pane to retrieve.
/// The pane instance, or null if there is no such pane in the specified tab.
AbstractViewPane GetPane( string tabId, string paneId );
///
/// Returns the ID of the pane which has been registered as the resource structure pane
/// for the specified tab.
///
/// The ID of the tab for which the resource structure pane is retrieved.
/// The ID of the pane, or null if no resource structure pane was registered.
string GetResourceStructurePaneId( string tabId );
}
///
/// Allows to query the information about a registered resource type tab.
///
public interface IResourceTypeTab
{
///
/// The ID of the tab.
///
string Id { get; }
///
/// The name of the tab (the text displayed in the tab caption).
///
string Name { get; }
///
/// Returns the resource types which are displayed in the tab.
///
string[] GetResourceTypes();
///
/// The link property for which the resources are displayed in the tab.
///
int LinkPropId { get; }
///
/// Returns the list of all resources displayed in the tab.
///
/// true if a live list is requested, false otherwise.
/// The list of resources displayed in the tab, or null if the filter
/// list is requested for the "All Resources" tab.
IResourceList GetFilterList( bool live );
}
///
/// The collection of registered resource type tabs.
///
public interface IResourceTypeTabCollection
{
///
/// The count of registered resource type tabs.
///
int Count { get; }
///
/// Returns the resource type tab at the given index.
///
/// The tab at index 0 is 'All Resources'; the first tab registered by a plugin
/// is at index 1.
IResourceTypeTab this [int index] { get; }
///
/// Returns the resource type tab with the specified ID.
///
IResourceTypeTab this [string tabId] { get; }
}
///
/// Allows to register resource type tabs and to get information about the
/// registered resource type tabs.
///
public interface ITabManager
{
///
/// Gets the collection of registered resource type tabs.
///
IResourceTypeTabCollection Tabs { get; }
///
/// Registers a resource type tab which displays resources of a single type.
///
/// ID of the tab (non-localized).
/// User-visible name of the tab (localized).
/// The resource type displayed in the tab.
/// Order of the tab relative to other tabs.
void RegisterResourceTypeTab( string tabId, string tabName, string resType, int order );
///
/// Registers a resource type tab which displays resources of multiple types.
///
/// ID of the tab (non-localized).
/// User-visible name of the tab (localized).
/// The resource types displayed in the tab.
/// Order of the tab relative to other tabs.
void RegisterResourceTypeTab( string tabId, string tabName, string[] resTypes, int order );
///
/// Registers a resource type tab which displays resources of multiple types and
/// the resources which have the specified link property.
///
/// ID of the tab (non-localized).
/// User-visible name of the tab (localized).
/// The resource types displayed in the tab.
/// ID of the link property for the resources displayed in the tab.
/// Order of the tab relative to other tabs.
/// This is used, for example, for the "Web" tab. The actual bookmarks
/// displayed in the tab may have different types (HTML file, plain-text file, picture etc.),
/// but they all have a link of type "Source", which distinguishes them from local files, Outlook
/// attachments and other file-based resources.
/// The resources displayed in the tab either have one of the specified resource
/// types or a link of the specified type.
///
void RegisterResourceTypeTab( string tabId, string tabName, string[] resTypes, int linkPropId,
int order );
///
/// Sets the resource which is selected in the sidebar when the specified tab is first
/// activated.
///
/// ID of the tab for which the resource is set.
/// The default selected resource.
/// First, an attempt to select the resource in the resource structure pane
/// for the tab is made. If there is no resource structure pane, or if that pane does not
/// contain the resource, an attempt is made to select the resource in the "Views and
/// Categories" tab.
void SetDefaultSelectedResource( string tabId, IResource res );
///
/// Selects the tab where resources of the specified type are displayed.
///
/// The resource type of the tab to switch to.
/// If there is no tab registered for the specified resource type, the
/// method switches to the "All Resources" tab.
void SelectResourceTypeTab( string resType );
///
/// Selects the tab where resources with the specified link property are displayed.
///
/// The property of the resources in the tab to switch to.
/// If there is no tab registered for the specified link property, the
/// method switches to the "All Resources" tab.
void SelectLinkPropTab( int linkPropId );
///
/// Returns the ID of the tab where the resources of the specified type are displayed.
///
/// The resource type of the tab to find.
/// The ID of the tab, or null if there is no tab registered for the
/// specified resource type.
string FindResourceTypeTab( string resType );
///
/// Returns the ID of the tab where the resources with the specified link property are displayed.
///
/// The ID of the link property for the tab to find.
/// The ID of the tab, or null if there is no tab registered for the
/// specified link property type.
string FindLinkPropTab( int linkPropId );
///
/// Gets the ID of the currently selected tab, and allows to switch to a different tab.
///
string CurrentTabId { get; set; }
///
/// Returns the information about the currently selected tab.
///
IResourceTypeTab CurrentTab { get; }
///
/// Switches to the specified tab and verifies that the tab switch was completed correctly.
///
/// The tab to activate.
/// true if the tab was activated, false if the user switched to a different
/// tab while the tab switch was being processed.
/// 1.0.2
bool ActivateTab( string tabId );
///
/// Returns the ID of the tab in which the specified resource is visible.
///
/// The resource to check.
/// The ID of the tab in which the resource is visible, or null if
/// the resource is only visible in the "All Resources" tab.
string GetResourceTab( IResource res );
///
/// Fired after the user has switched to a different resource type tab.
///
event EventHandler TabChanged;
}
///
/// Contains IDs of the standard sidebar panes which are registered by the Omea core.
///
public class StandardViewPanes
{
///
/// ID of the "Views and Categories" pane.
///
public const string ViewsCategories = "ViewsCategories";
///
/// ID of the "Correspondents" pane.
///
public const string Correspondents = "Correspondents";
}
///
/// Allows any component to return an action context for its current state.
///
public interface IContextProvider
{
///
/// Returns the action context for the current state of the control.
///
/// The kind of action which is invoked (keyboard, menu and so on).
/// The action context for the specified kind and the current state.
IActionContext GetContext( ActionContextKind kind );
}
///
/// Defines flags which specify additional properties of a column in multiline view.
///
/// 2.0
[Flags]
public enum MultiLineColumnFlags
{
///
/// The left edge of the column is anchored to the left side of the view area.
///
AnchorLeft = 1,
///
/// The right edge of the column is anchored to the right side of the view area.
///
AnchorRight = 2,
///
/// The column is hidden and other columns are stretched if the resource does not have
/// the property displayed in the column.
///
HideIfNoProp = 4
}
///
/// Allows to define grouping for resources displayed in the resource browser.
///
/// 2.0
public interface IResourceGroupProvider
{
///
/// Returns the name of the group in which the specified resource is found.
///
/// The resource shown in resource browser.
/// The name of the group.
string GetGroupName( IResource res );
}
///
/// Manages the default resource list columns used when displaying resource lists
/// and the columns which are available in the "Configure Columns" dialog.
///
public interface IDisplayColumnManager
{
///
/// Registers a column which will be included in the list when the resources of the specified
/// type are displayed.
///
/// The type for which the column is registered, or null if
/// the column is registered for resources of all types.
/// The position of the column relative to other columns registered
/// for the same resource type.
/// The descriptor specifying the properties displayed in the column,
/// its width and flags.
/// If the displayed list contains resources of several types and columns with
/// the same index have been registered for those types, the relative position of those
/// columns is undefined.
void RegisterDisplayColumn( string resourceType, int index, ColumnDescriptor column );
///
/// Makes the specified column available for selection for a specific resource type
/// or all resource types, even if the properties shown in the column are not present
/// on any of the resources in the current resource list.
///
/// The resource type for which the column is registered,
/// or null if the column is registered for all resource types.
/// The descriptor specifying the properties displayed in the column,
/// its width and flags.
void RegisterAvailableColumn( string resourceType, ColumnDescriptor column );
///
/// Removes the column with the specified property names from the list of columns
/// registered with .
///
/// The resource type for which the column was registered,
/// or null if it was registered for all resource types.
/// The property name of the column to be removed.
void RemoveAvailableColumn( string resourceType, string propName );
///
/// Registers a custom handler for drawing the values of a specified property and
/// handling events in the column displaying the property.
///
/// The ID of the property for which the custom column is
/// registered.
/// The custom column implementation.
void RegisterCustomColumn( int propId, ICustomColumn customColumn );
///
/// Registers a column visible in the multi-line view for the specified resource.
///
/// The type of the resource.
/// The ID of property displayed in the column.
/// The row in which the column rectangle starts.
/// The row in which the column rectangle ends.
/// The X position where the column data starts.
/// The width of the column in pixels.
/// The flags specifying additional options for the column.
/// The color of text displayed in the column.
/// The alignment of text within the column rectangle.
/// 2.0
void RegisterMultiLineColumn( string resourceType, int propId, int startRow, int endRow,
int startX, int width, MultiLineColumnFlags flags, Color textColor, HorizontalAlignment textAlign );
///
/// Registers a column visible in the multi-line view for the specified resource.
///
/// The type of the resource.
/// The IDs of properties displayed in the column.
/// The row in which the column rectangle starts.
/// The row in which the column rectangle ends.
/// The X position where the column data starts.
/// The width of the column in pixels.
/// The flags specifying additional options for the column.
/// Color of the text rendered into this column.
/// Horizontal alignment of the text rendered into this column.
/// 2.0
void RegisterMultiLineColumn( string resourceType, int[] propIds, int startRow, int endRow,
int startX, int width, MultiLineColumnFlags flags, Color textColor, HorizontalAlignment textAlign );
///
/// Sets the value indicating whether top-level items in threads of the specified resource type
/// are always aligned even if the items have no children.
///
/// The resource type for which the setting is performed.
/// If true, the threads are always aligned. If false, top level items
/// with no children are displayed with zero indent and not with a single indent step.
/// 2.0
void SetAlignTopLevelItems( string resourceType, bool align );
///
/// Registers a custom callback which will be used to convert the values of the specified
/// property to text displayed in the resource list view.
///
/// The ID of the property for which the callback is registered.
/// The callback which returns a text string given a resource
/// and a property ID.
void RegisterPropertyToTextCallback( int propId, PropertyToTextCallback propToText );
///
/// Registers a custom callback which will be used to convert the values of the specified
/// property to text displayed in the resource list view, depending on the space available
/// for displaying the property value in the list.
/// ///
/// The ID of the property for which the callback is registered.
/// The callback which returns a text string given a resource,
/// a property ID and a width value.
/// 2.0
void RegisterPropertyToTextCallback( int propId, PropertyToTextCallback2 propToText );
///
/// Returns the list of default columns used for displaying the specified resource list.
///
/// The resource list for which the columns are retrieved.
/// The array of column descriptors describing the list columns.
/// The returned array includes columns registered for every resource type
/// in the list and columns registered for any resource type.
ColumnDescriptor[] GetDefaultColumns( IResourceList resList );
///
/// Adds the columns registered for any resource type to the specified list of
/// column descriptors.
///
/// An array of column descriptors.
/// An array containing all the column descriptors in the original
/// array and descriptors for all columns registered for any resource type.
ColumnDescriptor[] AddAnyTypeColumns( ColumnDescriptor[] columnDescriptors );
}
///
/// The main setting store that stores settings for Omea application and all the plugins.
///
///
/// Use to get access to the setting store.
/// For your plugins, you should use instead of developing cutsom settings-management facilities.
///
public interface ISettingStore
{
///
/// Writes a string option to the setting store.
///
/// Section (group, category) of the option.
/// Option unique name.
/// Option value.
void WriteString( string section, string key, string value );
///
/// Writes an integer option to the setting store.
///
/// Section (group, category) of the option.
/// Option unique name.
/// Option value.
void WriteInt( string section, string key, int value );
///
/// Writes a boolean option to the setting store.
///
/// Section (group, category) of the option.
/// Option unique name.
/// Option value.
void WriteBool( string section, string key, bool value );
///
/// Writes a date/time option to the setting store.
///
/// Section (group, category) of the option.
/// Option unique name.
/// Option value.
void WriteDate( string section, string key, DateTime value );
///
/// Reads a string value from the settings store.
/// If there is no such option in the setting store, an empty string is returned.
///
/// Section (group, category) of the option.
/// Option unique name.
/// Option value.
string ReadString( string section, string key );
///
/// Reads a string value from the settings store.
/// If there is no such option in the setting store, the default value is returned.
///
/// Section (group, category) of the option.
/// Option unique name.
/// The default value to be used if the option is not defined.
/// Option value.
string ReadString( string section, string key, string defaultValue );
///
/// Reads an integer value from the settings store.
/// If there is no such option in the setting store, the default value is returned.
///
/// Section (group, category) of the option.
/// Option unique name.
/// The default value to be used if the option is not defined.
/// Option value.
int ReadInt( string section, string key, int defaultValue );
///
/// Reads a boolean value from the settings store.
/// If there is no such option in the setting store, the default value is returned.
///
/// Section (group, category) of the option.
/// Option unique name.
/// The default value to be used if the option is not defined.
/// Option value.
bool ReadBool( string section, string key, bool defaultValue );
///
/// Reads a date/time value from the settings store.
/// If there is no such option in the setting store, the default value is returned.
///
/// Section (group, category) of the option.
/// Option unique name.
/// The default value to be used if the option is not defined.
/// Option value.
DateTime ReadDate( string section, string key, DateTime defaultValue );
}
///
/// Manages the registration of interfaces for handling resources of specific types
/// provided by plugins.
///
public interface IPluginLoader
{
///
/// Registers the user interface action handler
/// for the specific resource type.
///
/// The resource type for which the handler is registered.
/// The handler implementation.
///
/// The user interface handler is responsible for handling operations like
/// drag and drop, in-place rename and selection in the sidebar panes.
/// If the handler was already registered, the new handler replaces the
/// previously registered handler.
///
void RegisterResourceUIHandler( string resType, IResourceUIHandler handler );
///
/// Returns the user interface handler registered for the specified resource type.
///
/// The resource type for which the handler is requested.
/// The handler implementation, or null if there was no handler registered.
/// 2.0
IResourceUIHandler GetResourceUIHandler( string resType );
///
/// Returns the user interface handler registered for the specified resource.
///
/// The resource for which the handler is requested.
/// The handler implementation, or null if there was no handler registered.
/// If there is no handler registered for the type of the resource but the
/// resource has a source link, the handler
/// for the source resource is returned.
IResourceUIHandler GetResourceUIHandler( IResource res );
///
/// Registers the drag and drop handler
/// for the specific resource type.
///
/// The resource type for which the handler is registered.
/// The handler implementation.
///
/// The implementation allows registering more than one handler for each of the resource types.
/// Upon execution (drag-over or drop), all the handlers for this resource type are queried in order of registration,
/// until one is found that agrees to handle the operation. The remaining handlers do not get queried.
/// When the drop operation is performed, the handler is queried for a drag-over and the result
/// should be positive for the drop to execute, ie the effect must not be .
///
/// 2.0
void RegisterResourceDragDropHandler( string resType, IResourceDragDropHandler handler );
///
/// Returns the drag and drop handler registered for the specified resource.
///
/// The resource for which the handler is requested.
/// The handler implementation, or null if there was no handler registered.
/// If there is no handler registered for the type of the resource but the
/// resource has a source link, the handler
/// for the source resource is returned.
/// 2.0
IResourceDragDropHandler GetResourceDragDropHandler( IResource res );
///
/// Returns the drag and drop handler registered for the specified resource type.
///
/// The resource type for which the handler is requested.
/// The handler implementation, or null if there was no handler registered.
/// 2.0
IResourceDragDropHandler GetResourceDragDropHandler( string resType );
///
/// Registers the rename handler
/// for the specific resource type.
///
/// The resource type for which the handler is registered.
/// The handler implementation.
///
/// If the handler was already registered, the new handler replaces the
/// previously registered handler.
///
void RegisterResourceRenameHandler( string resType, IResourceRenameHandler handler );
///
/// Returns the rename handler registered for the specified resource.
///
/// The resource for which the handler is requested.
/// The handler implementation, or null if there was no handler registered.
/// If there is no handler registered for the type of the resource but the
/// resource has a source link, the handler
/// for the source resource is returned.
/// 2.0
IResourceRenameHandler GetResourceRenameHandler( IResource res );
///
/// Registers a custom threading handler for the specified resource type.
///
/// The resource type for which the handler is registered.
/// The handler implementation.
/// 2.0
void RegisterResourceThreadingHandler( string resType, IResourceThreadingHandler handler );
///
/// Registers a custom threading handler for resources with the specified property.
///
/// The ID of the property which must be present on the resources for which
/// the handler is used.
/// The handler implementation.
/// 2.0
void RegisterResourceThreadingHandler( int propId, IResourceThreadingHandler handler );
///
/// Registers a default threading handler with the specified reply link type for the
/// specified resource type.
///
/// The resource type for which the handler is registered.
/// The ID of the reply link property.
/// 2.0
void RegisterDefaultThreadingHandler( string resType, int replyProp );
///
/// Returns the threading handler registered for the specified resource type.
///
/// The resource type for which the handler is requested.
/// The handler implementation, or null if no handler is registered.
IResourceThreadingHandler GetResourceThreadingHandler( string resType );
///
/// Gets the composite threading handler which can perform threading of resources of all
/// types based on the registered threading handlers.
///
/// 2.0
IResourceThreadingHandler CompositeThreadingHandler { get; }
///
/// Registers a text provider for the specified
/// resource type or for any resource type.
///
/// The resource type for which the provider is registered,
/// or null if the provider is registered for all resource types.
/// The provider implementation.
/// When a resource is indexed, first all the providers which have been
/// registered for the type of the resource are invoked, and then all the providers
/// registered for all resource types.
void RegisterResourceTextProvider( string resType, IResourceTextProvider provider );
///
/// Checks whether any text provider for
/// the specified resource type is registered.
///
/// The resource type for which the provider is queried. Can not be null.
/// True if any text provider was registered for the specified resource type.
bool HasTypedTextProvider( string resType );
///
/// Invokes all registered resource text providers for the specified resource.
///
/// The resource for which the text is requested.
/// The consumer to which the text fragments are passed.
void InvokeResourceTextProviders( IResource res, IResourceTextConsumer consumer );
///
/// Registers a resource displayer for the specified
/// resource type.
///
/// The resource type for which the resource displayer is registered.
/// The resource displayer implementation.
/// If the resource displayer was already registered, the new implementation
/// replaces the previously registered implementation.
void RegisterResourceDisplayer( string resType, IResourceDisplayer displayer );
///
/// Returns the resource displayer registered for the specified resource type.
///
/// The resource type for which the displayer is requested.
/// The resource displayer implementation, or null if none was registered.
IResourceDisplayer GetResourceDisplayer( string resType );
///
/// Registers a newspaper provider for the specified
/// resource type.
///
/// The resource type for which the provider is registered.
/// The provider implementation.
/// 2.0
void RegisterNewspaperProvider( string resType, INewspaperProvider provider );
///
/// Returns the newspaper provider registered for the specified resource type.
///
/// The resource type for which the provider is requested.
/// The newspaper provider implementation, or null if none was registered.
/// 2.0
INewspaperProvider GetNewspaperProvider( string resType );
///
/// Returns the stream provider registered for the specified
/// resource type.
///
/// The resource type for which the provider is registered.
/// The provider implementation.
/// If the provider for the resource type was already registered, the new
/// provider replaces the previously registered provider.
void RegisterStreamProvider( string resType, IStreamProvider provider );
///
/// Returns the stream provider registered for the specified resource type.
///
/// The resource type for which the provider is requested.
/// The provider implementation, or null if none was registered.
IStreamProvider GetStreamProvider( string resType );
///
/// Registers a plugin service.
///
/// The plugin service implementation.
/// Plugin services are interfaces which can be used by plugins to provide APIs
/// to other plugins. For example, the Outlook plugin registers an
/// email service which allows other plugins to send e-mail.
/// If several services are registered which implement the same interface, the last
/// registered one is used.
void RegisterPluginService( object pluginService );
///
/// Returns an implementation of the specified plugin service interface.
///
/// The type of the interface to return.
/// The implementation of the interface, or null if none was registered.
object GetPluginService( Type serviceType );
///
/// Registers a resource serializer for the
/// specified resource type.
///
/// The resource type for which the serializer is registered.
/// The serializer implementation.
/// If the serializer for the resource type was already registered, the new
/// serializer replaces the previously registered serializer.
void RegisterResourceSerializer( string resType, IResourceSerializer serializer );
///
/// Returns the resource serializer registered for the specified resource type.
///
/// The resource type for which the serializer is requested.
/// The serializer implementation, or null if none was registered.
IResourceSerializer GetResourceSerializer( string resType );
///
/// Register a view constructor implementation.
///
/// The view constructor implementation.
void RegisterViewsConstructor( IViewsConstructor constructor );
///
/// Returns the list of all registered view constructors.
///
/// ArrayList containing all registered
/// implementations.
ArrayList GetViewsConstructors();
///
/// Registers a resource deleter for the specified
/// resource type.
///
/// The resource type for which the deleter is registered.
/// The resource deleter implementation.
void RegisterResourceDeleter( string resType, IResourceDeleter deleter );
///
/// Returns the resource deleter registered for the specified resource type.
///
/// The resource type for which the deleter is requested.
/// The deleter implementation, or null if none was registered for the
/// specified resource type.
IResourceDeleter GetResourceDeleter( string resType );
}
///
/// Manages registration and retrieval of icons for resources.
///
/// All small (16x16) resource icons are put in one global image list,
/// which can be accessed through the property.
public interface IResourceIconManager
{
///
/// Registers a provider of icons for the specified resource type.
///
/// The resource type for which the provider is registered.
/// The provider implementation.
void RegisterResourceIconProvider( string resType, IResourceIconProvider provider );
///
/// Registers a provider of icons for the specified resource types.
///
/// The resource types for which the provider is registered.
/// The provider implementation.
void RegisterResourceIconProvider( string[] resTypes, IResourceIconProvider provider );
///
/// Registers a provider of overlay icons for the specified resource type.
///
/// The resource type for which the provider is registered, or null
/// if the provider is registered for all resource types.
/// The provider implementation.
/// 2.0
void RegisterOverlayIconProvider( string resType, IOverlayIconProvider provider );
///
/// Returns the provider of icons for the specified resource type.
///
/// The resource type for which the provider is returned.
/// The provider implementation, or null if no provider has been registered.
IResourceIconProvider GetResourceIconProvider( string resType );
///
/// Returns the index in the global image list of the icon for the specified resource.
///
/// The resource for which the icon is returned.
/// The icon index, or the index of the default icon if no icon provider
/// has been registered.
int GetIconIndex( IResource res );
///
/// Returns the index in the global image list of the default icon for the specified
/// resource type.
///
/// The resource type for which the icon is returned.
/// The icon index, or the index of the default icon if no icon provider
/// has been registered.
int GetDefaultIconIndex( string resType );
///
/// Returns the indexes in the global image list of the overlay icons for the specified
/// resource.
///
/// The resource for which the icons are returned.
/// The array of icon indexes, or an empty array if the specified resource
/// has no overlay icons.
/// 2.0
int[] GetOverlayIconIndices( IResource res );
///
/// Registers an icon for the specified property type.
///
/// The ID of the property type for which the icon is registered.
/// The icon which is registered.
void RegisterPropTypeIcon( int propId, Icon icon );
///
/// Returns the index of the icon for the specified property type.
///
/// The ID of the property type.
/// The index of the icon, or the default property or link icon if no custom
/// icon has been registered.
int GetPropTypeIconIndex( int propId );
///
/// Registers a large (32x32) icon for the specified resource type.
///
/// The resource type for which the icon is registered.
/// The icon which is registered.
/// The large icon is used as the icon of the resource edit window where
/// the resource is edited.
void RegisterResourceLargeIcon( string resType, Icon icon );
///
/// Returns the large (32x32) icon for the specified resource type.
///
/// The resource type for which the icon is returned.
/// The icon, or null if no icon has been registered.
Icon GetResourceLargeIcon( string resType );
///
/// Returns the image list containing all 16x16 resource icons.
///
ImageList ImageList { get; }
///
/// Returns the color depth of the icon image list.
///
/// The image list is 8-bit when running under Windows 2000 and 32-bit
/// when running under Windows XP.
ColorDepth IconColorDepth { get; }
Hashtable CollectAssemblyIcons();
}
///
/// Describes the behavior of a resource type when added to a workspace.
///
public enum WorkspaceResourceType
{
///
/// Drag and drop adds resource recursively. If added recursively, pulls resources by link type
/// specified at registration. Linked resources are not shown in Other view.
/// Examples: Newsgroup, Outlook folder.
///
Container,
///
/// Drag and drop adds resource non-recursively. Linked resources are shown in Other view.
/// Examples: Category, Contact.
///
Filter,
///
/// Drag and drop adds resource recursively. If added recursively, pulls resources by
/// Parent link. Linked resources are not shown in Other view.
/// Examples: RSS feed group, News folder.
///
Folder,
///
/// Drag and drop adds resource non-recursively. Pulls linked resources by link types
/// specified at registration.
/// Examples: Email.
///
None
}
///
/// Allows to register the relationships of resources to workspaces and to perform
/// different operations on workspaces.
///
public interface IWorkspaceManager
{
///
/// Registers a resource type which can interact with workspaces.
///
/// The resource type which is registered.
/// The IDs of the link properties which are followed to make
/// other resources visible in the workspace when the resource is added to the workspace.
/// The behavior of the resource type when added to the workspace.
void RegisterWorkspaceType( string resType, int[] linkPropIDs, WorkspaceResourceType workspaceResourceType );
///
/// Registers a resource type which can interact with workspaces as a .
///
/// The resource type which is registered.
/// The IDs of the link properties which are followed to make
/// other resources visible in the workspace when the resource is added to the workspace.
/// The ID of the link property which is followed to recurse
/// the container hierarchy when a resource is added to the
void RegisterWorkspaceContainerType( string resType, int[] linkPropIds, int recurseLinkPropId );
///
/// Registers a resource type which can interact with workspaces as a .
///
/// The resource type which is registered.
/// Obsolete; ignored.
/// The IDs of the link properties which are followed to make
/// other resources visible in the workspace when the resource is added to the workspace.
void RegisterWorkspaceFolderType( string resType, string contentType, int[] linkPropIDs );
///
/// Registers the filter which is used to restrict the resources shown in the tree-based
/// selector of the workspace configuration dialog. The same filter is used for both
/// "Available" and "In Workspace" trees.
///
/// The resource type (registered with )
/// for which the filter is used.
/// The filter instance.
void RegisterWorkspaceSelectorFilter( string resType, IResourceNodeFilter filter );
///
/// Registers the filters which are used to restrict the resources shown in the tree-based
/// selector of the workspace configuration dialog. The filters used for "Available" and
/// "In Workspace" trees are configured separately.
///
/// The resource type (registered with )
/// for which the filter is used.
/// The filter instance used for the "Available" tree.
/// The filter instance used for the "In Workspace" tree.
/// 1.0.2
void RegisterWorkspaceSelectorFilter( string resType, IResourceNodeFilter availTreeFilter,
IResourceNodeFilter workspaceTreeFilter );
///
/// Creates a workspace with the specified name.
///
/// The name of the workspace to create.
/// The workspace resource.
IResource CreateWorkspace( string name );
///
/// Deletes the specified workspace.
///
/// A resource of type Workspace.
void DeleteWorkspace( IResource workspace );
///
/// Adds the specified resource to a workspace.
///
/// The workspace to which the resource is added.
/// The resource to add.
void AddResourceToWorkspace( IResource workspace, IResource res );
///
/// Adds the specified resource and its child resources to a workspace.
///
/// The workspace to which the resource is added.
/// The resource to add.
void AddResourceToWorkspaceRecursive( IResource workspace, IResource res );
///
/// Adds all resources in the specified list to the workspace.
///
/// The workspace to which the resources are added.
/// The resources to add.
void AddResourcesToWorkspace( IResource workspace, IResourceList resList );
///
/// If a workspace is active, adds the specified resource to the active workspace.
///
/// The resource to add.
void AddToActiveWorkspace( IResource res );
///
/// If a workspace is active, adds the specified resource and its children to the
/// active workspace.
///
/// The resource to add.
void AddToActiveWorkspaceRecursive( IResource res );
///
/// Removes the specified resource from a workspace.
///
/// The workspace from which the resource is removed.
/// The resource to be removed.
void RemoveResourceFromWorkspace( IResource workspace, IResource res );
///
/// Removes all resources in the specified list from a workspace.
///
/// The workspace from which the resources are removed.
/// The resources to be removed.
void RemoveResourcesFromWorkspace( IResource workspace, IResourceList resList );
///
/// Returns the list of resources visible in the specified workspace.
///
/// The workspace for which the list is returned.
/// The list of resources visible in the workspace.
IResourceList GetFilterList( IResource workspace );
///
/// Returns the non-live list of resources added to the workspace which have the specified type.
///
/// The workspace for which resources are returned.
/// The resource type, or null if all resources should be returned.
/// The list of resources added to the workspace.
/// The returned list does not include resources which are visible in a workspace
/// because their container or another linked resource was added to the workspace. For example,
/// if an email folder was added to the workspace, the returned list includes only the folder,
/// but not the emails in the folder.
IResourceList GetWorkspaceResources( IResource workspace, string resType );
///
/// Returns the live list of resources added to the workspace which have the specified type.
///
/// The workspace for which resources are returned.
/// The resource type, or null if all resources should be returned.
/// The list of resources added to the workspace.
/// The returned list does not include resources which are visible in a workspace
/// because their container or another linked resource was added to the workspace. For example,
/// if an email folder was added to the workspace, the returned list includes only the folder,
/// but not the emails in the folder.
IResourceList GetWorkspaceResourcesLive( IResource workspace, string resType );
///
/// Returns the behavior of a resource type when added to the workspace.
///
/// The resource type name.
/// The behavior value, or if the resource
/// type was not registered for workspace usage.
WorkspaceResourceType GetWorkspaceResourceType( string resType );
///
/// Returns the link type which is used for recursively traversing the workspace
/// container resources with the specified content type, or the ID of the "Parent"
/// link if no specific link has been registered.
///
/// The resource type registered for using in workspaces.
/// The ID of the link property type.
int GetRecurseLinkPropId( string resType );
///
/// Checks if the specified resource or one of its parents is recursively added to the specified
/// workspace.
///
/// The workspace to check.
/// The resource to check.
/// true if the resource or one of its parents is recursively added to the specified
/// workspace, false otherwise.
/// 2.0
bool IsInWorkspaceRecursive( IResource workspace, IResource res );
///
/// Returns the list of workspaces to which the specified resource belongs.
///
/// The resource which is checked.
/// The array of workspaces, or an empty array if the resource does
/// not belong to any workspace or no workspaces are defined.
IResourceList GetResourceWorkspaces( IResource resource );
///
/// Returns a live resource list of active workspaces.
///
///
IResourceList GetAllWorkspaces();
///
/// Sets the name of the tab in Workspaces dialog in which the selector for the specified
/// resource type is displayed.
///
/// If multiple resource types have the same tab name, they are displayed in the same tab.
///
/// The workspace resource type.
/// The name of the tab in which it is displayed.
/// 2.0
void SetWorkspaceTabName( string resourceType, string tabName );
///
/// If the parent of the specified resource is recursively added to a workspace,
/// deletes the direct links from this resource to the workspace.
///
/// The resource for which the links should be cleaned.
void CleanWorkspaceLinks( IResource res );
///
/// Gets or sets the active workspace.
///
/// The active workspace resource, or null if no workspace is active.
IResource ActiveWorkspace { get; set; }
///
/// Occurs when the active workspace changes.
///
event EventHandler WorkspaceChanged;
}
///
/// Allows to perform operations with resource categories.
///
public interface ICategoryManager
{
///
/// Returns the list of categories to which the specified resource belongs.
///
/// The resource for which the categories are retrieved.
/// The list of resources of type "Category".
IResourceList GetResourceCategories( IResource resource );
///
/// Adds the specified resource to the specified category.
///
/// The resource to add.
/// The resource of type Category specifying the category
/// to which the resource is added.
void AddResourceCategory( IResource res, IResource category );
///
/// Set the specified category to the specified resource.
///
/// The resource to add.
/// The resource of type Category specifying the category
/// to which the resource is added.
void SetResourceCategory( IResource res, IResource category );
///
/// Removes the specified resource from the specified category.
///
/// The resource to remove.
/// The resource of type Category specifying the category
/// from which the resource is removed.
void RemoveResourceCategory( IResource res, IResource category );
///
/// Finds a category which has the specified parent category and name.
///
/// The parent for the category to find,
/// or null if top-level categories for all resource types should be searched.
/// The name of the category to find.
/// The category, or null if there is no category with the specified
/// name at the specified level.
IResource FindCategory( IResource parentCategory, string name );
///
/// Finds a category with the specified name under the specified category,
/// and creates a new category if no category with that name exists.
///
/// The parent category.
/// The name of the category to find or create.
/// A resource of type Category.
IResource FindOrCreateCategory( IResource parentCategory, string name );
///
/// Returns the resource which is used as a root of the categories for the
/// specified resource type.
///
/// The resource is created automatically if necessary.
/// The resource type.
/// A resource of type ResourceTreeRoot.
IResource GetRootForTypedCategory( string resType );
///
/// Finds and returns the resource which is used as a root of the categories for the
/// specified resource type.
///
/// If the resource is not found, returns null.
/// The resource type.
/// A resource of type ResourceTreeRoot, or null if the specified root
/// has not been created.
/// 2.0
IResource FindRootForTypedCategory( string resType );
///
/// Gets the resource which is the root of the untyped category tree.
///
/// 2.0
IResource RootCategory
{
get;
}
///
/// Internal method, should not be used by plugins.
///
bool CheckRenameCategory( IWin32Window parentWindow, IResource category, string newName );
}
///
/// Allows to receive notifications about changes in a specified set of resources.
///
/// Implementations of this interface can be used with
/// and
/// .
/// 2.0
public interface IResourceListListener
{
///
/// Called when a resource is added to the set.
///
/// The added resource.
void ResourceAdded( IResource res );
///
/// Called before a resource is removed from the set.
///
/// The resource being removed.
void ResourceDeleting( IResource res );
///
/// Called when a resource belonging to the set is changed.
///
/// The changed resource.
/// The details of the changes to the resource.
void ResourceChanged( IResource res, IPropertyChangeSet cs );
}
///
/// Manages the hierarchies of resources in Omea.
///
public interface IResourceTreeManager
{
///
/// Gets the resource which is the root of the tree displayed in the Views and Categories pane.
///
IResource ResourceTreeRoot { get; }
///
/// Gets the resource which is the root of the hierarchy of resources of the specified type.
///
/// The resource is created if necessary. A plugin can create a hierarchy for any
/// resource type, if necessary.
/// The resource type for which the root is returned.
/// The resource of type ResourceTreeRoot.
IResource GetRootForType( string resType );
///
/// Links the specified resource to the root of the Views and Categories resource tree
/// at the specified position.
///
/// The resource to be linked to the root.
///
/// The relative position of the resource in the list. Resources
/// are sorted by index in ascending order.
/// The special values and insert to the beginning and the end of the list, respectively.
///
void LinkToResourceRoot( IResource res, int index );
///
/// Specifies that the children of the specified node are sorted by values of the specified
/// property.
///
/// The sorting mode is applied hierarchically down the tree unless a different
/// sorting mode is specified for a child node.
/// The node for which the sorting mode is specified.
/// The string containing a list of property names,
/// in the format used by .
void SetResourceNodeSort( IResource node, string sortProps );
///
/// Returns the list of properties by which the children of the specified node are
/// sorted in the tree.
///
/// The node for which the sorting mode is retrieved.
/// The list of property names, or null if no sorting mode has been specified
/// for the specified node or any of its parents.
string GetResourceNodeSort( IResource node );
///
/// Specifies that the specified resource type has a separate hierarchy of views
/// which does not contain the standard views defined for all resources.
///
/// The resource type which has a separate hierarchy.
void SetViewsExclusive( string resType );
///
/// Checks if the specified resource type has a separate hierarchy of views.
///
/// The resource type to check.
/// true if the resource type has a separate hierarchy of views, false otherwise.
bool AreViewsExclusive( string resType );
///
///
/// Registers a listener for receiving notifications about changes in the children
/// of the specified resource.
///
/// Using this method is more efficient than creating a separate resource list
/// for monitoring changes to each node in the tree.
/// The parent resource.
/// The ID of the link property between the parent and the children.
/// The listener which is being registered.
/// 2.0
void RegisterTreeListener( IResource parent, int parentProp, IResourceListListener listener );
///
///
/// Unregisters a listener for receiving notifications about changes in the children
/// of the specified resource.
///
/// The parent resource.
/// The ID of the link property between the parent and the children.
/// The listener which is being unregistered.
/// 2.0
void UnregisterTreeListener( IResource parent, int parentProp, IResourceListListener listener );
}
///
/// Manages the rules that are used for notifying the user about arriving resources.
///
public interface INotificationManager
{
///
/// Registers a resource type for which the "Notify Me" feature can be used.
///
/// Type of the resources for which "Notify Me" is invoked.
///
/// Type of the resources processed by "Notify Me" rules for the resource type.
///
void RegisterNotifyMeResourceType( string resType, string ruleResType );
///
/// Registers the condition template that is offered to the user in the "Notify Me"
/// dialog when it is invoked for a resource of the specific type. Multiple conditions
/// can be registered for the same resource type - in this case, the conditions are shown
/// with checkboxes.
///
/// The resource type for which the notify condition is registered.
/// The template which will be used in the notification rule.
/// ID of the link type which links the target resource to the
/// resource which should be used as the condition parameter. (Specify 0 if the target resource
/// itself should be used as the parameter.) For example, if you want to offer "From 'sender'"
/// as the condition, specify the ID of the "From" property in the parameter.
/// The notification registration is not stored in the resource store and needs to be
/// performed on every run of the plugin.
void RegisterNotifyMeCondition( string resType, IResource conditionTemplate, int linkPropId );
///
/// Returns the list of "Notify Me" condition templates for the specified resource type.
///
///
/// Array of resources of type ConditionTemplate
IResource[] GetNotifyMeConditions( string resType );
///
/// Returns the link type which links the target resource to the resource which should be used
/// as the condition parameter, for the specified resource type and condition template.
///
///
///
/// Link type ID, or 0 if the resource itself should be used as the condition parameter.
int GetConditionLinkType( string resType, IResource conditionTemplate );
///
/// Returns the resource type for which the rules are created, given the resource type
/// for which the dialog is invoked.
///
/// The resource type for which the dialog is invoked.
/// The resource type for which the rules are created.
string GetRuleResourceType( string resType );
}
///
/// Represents a method which is called when the resource edited through
/// is saved.
///
public delegate void EditedResourceSavedDelegate( IResource res, object tag );
///
/// Represents a method which is called to validate a string entered in
/// the dialog shown by .
///
public delegate void ValidateStringDelegate( string value, ref string validateErrorMessage );
///
/// Interface for managing calls, which could be invoked from outside of Omea
/// process via RPC calls.
///
/// 2.0
public interface IRemoteControlManager
{
///
/// Add new call, whcih could be invoked via RPC mechanism.
///
/// Name of proceudre, exported to clients.
/// Method to call.
/// true if call was registered, false if method with this name already exists.
///
/// Procedure can have any number of parameters of types string, int and
/// bool. It must return string with XML as result or throw exception with
/// meaningful message in case of error.
///
/// Will be throwed if passed delegate
/// have arguments of unknown type or return type is not string.
bool AddRemoteCall(string rcName, Delegate method);
}
}