source/AyaNova.PlugIn/IAyaNovaCommand.cs

@@ -0,0 +1,263 @@
+using System;
+using System.Collections.Generic;
+using System.Linq;
+using System.Text;
+using GZTW.AyaNova.BLL;
+using System.Drawing;
+
+namespace AyaNova.PlugIn
+{   
+    public interface IAyaNovaPlugin
+    {
+        /// <summary>
+        /// Displayed in menus to group this plugin's menu item options beneath
+        /// </summary>
+        string PluginName { get; }
+
+        /// <summary>
+        /// May be displayed in UI 
+        /// or log files
+        /// </summary>
+        string PluginVersion { get; }
+
+        /// <summary>
+        /// About info for plugin
+        /// 
+        /// </summary>
+        string About { get; }
+
+        /// <summary>
+        /// Unique identifier for plugin, used in AyaNova to route commands
+        /// and should also be used as the application ID if using the Integration 
+        /// object to persist plugin specific data.
+        /// 
+        /// This ID should never change.
+        /// 
+        /// Any plugin that fails to return a unique ID will not be loaded
+        /// </summary>
+        Guid PluginID { get; }
+
+        /// <summary>
+        /// Icon used to display beside plugin name in plugin menu option
+        /// or null if no icon provided
+        /// Should always be 16px square
+        /// </summary>
+        Image PluginSmallIcon { get; }
+
+        /// <summary>
+        /// Icon used to display beside plugin name in plugin menu option
+        /// or null if no icon provided
+        /// Should always be 32px square
+        /// </summary>
+        Image PluginLargeIcon { get; }
+
+        /// <summary>
+        /// This is set by AyaNova after sucessful call to Initialize
+        /// This gives the plugin access to the images and icons used in AyaNova
+        /// </summary>
+        System.Resources.ResourceManager AyaNovaResourceManager { set; }
+       
+        /// <summary>
+        /// Called when a user logs in to AyaNova sucessfully
+        /// 
+        /// Check the version number to ensure you are working with the same version of AyaNova as
+        /// your plugin requires.
+        /// 
+        /// There is no particular requirement for the plugin to do anything with this method
+        /// however this is a good point to cache any information required from the AyaNova biz object 
+        /// library if you need to cache it since access rights may have changed at this point.
+        /// 
+        /// Also any long held resources required should be loaded at this point (be sure to release them in Close)
+        /// 
+        /// Typically this is called after a user has launched AyaNova and sucessfully logged in but it may also
+        /// be called when a user has used the logout menu option in AyaNova and just logged back in again.
+        /// </summary>
+        /// <param name="AyaNovaVersion">The version of AyaNova calling this plugin</param>
+        /// <param name="localizedText">The current logged in AyaNova user's localized text object</param>
+        /// <returns>False if initialization failed or plugin does not wish to participate or is unsupported in which case 
+        /// it will not be called upon again by AyaNova.  true if plugin is supported / initialized ok</returns>
+        bool Initialize(Version AyaNovaVersion, LocalizedTextTable localizedText);
+
+        
+
+        /// <summary>
+        /// Called when a user is logging out but just before they have logged out.
+        /// Release any resources at this point.  
+        /// 
+        /// Typically this is called when AyaNova is about to close but may also be called when the user has selected
+        /// logout from the interface
+        /// </summary>
+        void Close();
+
+        /// <summary>
+        /// If your plugin supports the object type in question
+        /// then this should return true.
+        /// 
+        /// This is called by AyaNova when it needs to know if the plugins menu should be displayed or not
+        /// for a particular single object edit form.
+        /// 
+        /// Returning true will cause AyaNova to display in the plugin menu a popup item with the PluginName.
+        /// 
+        /// Later on, if the user selects that popup item then a call will be made to SingleObjectMenuOptions
+        /// to get the specific options.
+        /// 
+        /// </summary>
+        /// <param name="objectType"></param>
+        /// <returns>true to display plugin name in plugin menu, false to not participate for the object type</returns>
+        bool SingleObjectMenuShow(RootObjectTypes objectType);
+
+        /// <summary>
+        /// If your plugin supports a list of the object type in question
+        /// then this should return true.
+        /// 
+        /// This is called by AyaNova when it needs to know if the plugins menu should be displayed or not
+        /// for a list display of an object type.
+        /// 
+        /// Returning true will cause AyaNova to display in the plugin menu a popup item with the PluginName.
+        /// 
+        /// Later on, if the user selects that popup item then a call will be made to MultipleObjectsMenuOptions
+        /// to get the specific options.
+        /// 
+        /// </summary>
+        /// <param name="objectType"></param>
+        /// <returns>true to display plugin name in plugin menu, false to not participate for the object type</returns>
+        bool MultipleObjectsMenuShow(RootObjectTypes objectType);
+
+
+        /// <summary>
+        /// If your Plugin supports editing the object type (or the specific object) provided
+        /// then this should return a generic List of AyaNovaPluginMenuItem structs
+        /// which will be displayed in the menu for a single AyaNova object being edited.
+        /// 
+        /// If your plugin does not support the object type in question then return null instead.
+        /// 
+        /// NOTE: if your plugin is general purpose and not tied to specific object types or you want to offer a general 
+        /// setup / configuration option for your plugin: AyaNova will invoke this method with objectType=RootObjectTypes.Nothing
+        /// and display the menu items in the main AyaNova window.
+        ///         
+        /// </summary>
+        /// <param name="objectType">The type of object currently open in the AyaNova UI</param> 
+        /// <param name="ayaNovaObject">The live object being edited or selected</param>
+        /// <returns>A generic list of AyaNovaPluginMenuItem structs for all available options or null if not supported</returns>
+        List<AyaNovaPluginMenuItem> SingleObjectMenuOptions(RootObjectTypes objectType, object ayaNovaObject);
+
+        /// <summary>
+        /// If your Plugin supports editing multiples of the object type in question
+        /// then this should return a generic List of AyaNovaPluginMenuItem structs
+        /// which will be displayed in the menu for a list of the AyaNova object type being edited.
+        /// 
+        /// If your plugin does not support the object type in question or in multiples
+        /// then return null instead.
+        ///      
+        /// </summary>
+        /// <param name="objectType">The type of object list currently open in the AyaNova UI</param> 
+        /// <returns>A generic list of AyaNovaPluginMenuItem structs for all available options or null if not supported</returns>
+        List<AyaNovaPluginMenuItem> MultipleObjectsMenuOptions(RootObjectTypes objectType);
+
+        /// <summary>
+        /// Called by AyaNova UI when a plugin's menu option is selected on a list of AyaNova objects
+        /// 
+        /// Note that the list of id's will always be for objects that are saved in the AyaNova database and were displayed in the UI as a read only list
+        /// from which the user selected one or more of these object record rows in a grid or other UI method.
+        /// </summary>
+        /// <param name="commandKey">The plugin's key value specified for the command in the AyaNovaPluginMenuItem </param>
+        /// <param name="objectType">The type of AyaNova object selected</param>
+        /// <param name="objectIDList">A list of ID's of the objects selected</param>
+        /// <param name="listObject">Full list object of all items displayed in AyaNova UI (note, user could have filtered this list)</param>
+        /// <returns>true if the AyaNova UI should refresh it's display of the list or false if not</returns>
+        bool CommandSelectedForList(string commandKey, RootObjectTypes objectType, List<Guid> objectIDList, object listObject);
+
+        /// <summary>
+        /// Called by the AyaNova UI when a plugin's menu option is selected in an edit form for a single object
+        /// Note: the object may or may not have been saved to database, it could be completely new, retrieved and partially edited or 
+        /// identical to the copy in the database.  
+        /// 
+        /// To check if it was ever saved to database use the IsNew property.
+        /// To check if it's in a partially edited but unsaved state check the IsDirty property.
+        /// 
+        /// Do NOT under any circumstances attempt to save or delete the object in your plugin, AyaNova has a *lot* of code to ensure 
+        /// saving and deleting goes smoothly and there is no need to save or delete the object.  If you save the object in your plugin it will result in 
+        /// an unstable state in the AyaNova user interface which could lead to data loss or crashes.
+        /// 
+        /// 
+        /// Changes made to the object in the plugin will be immediately reflected in the AyaNova user interface since the UI is bound to the object.
+        /// 
+        /// For simplicity the object is passed as type object.  Simply cast it back to it's type to work with it's methods and properties, i.e.:
+        /// If your plugin operates on Client objects and the type passed is a Client then:
+        /// if(objectType is Client)
+        /// Client c=(Client)ayanovaObject;
+        /// you can then access the properties and methods through c.
+        /// 
+        /// NOTE: if your plugin is general purpose and not tied to specific object types or you want to offer a setup option
+        /// AyaNova will display a plugin option on the main windows for plugins that return single menu object options for
+        /// object type RootObjectTypes.Nothing.
+        /// 
+        /// If a user selects a plugin command from the main AyaNova menu it will appear here as objectType=RootObjectTypes.Nothing
+        /// and ayaNovaObject will be NULL.
+        /// </summary>
+        /// <param name="commandKey">The plugin's key value specified for the command in the AyaNovaPluginMenuItem</param>
+        /// <param name="objectType">The type of AyaNova object selected</param>
+        /// <param name="ayaNovaObject">The live object being edited or selected</param>
+        /// <returns></returns>
+        void CommandSelectedForSingleObject(string commandKey, RootObjectTypes objectType, object ayaNovaObject);
+
+       
+
+    }
+
+   
+
+    #region Menu item structure
+
+    /// <summary>
+    /// Menu item structure used to communicate available menu options
+    /// to AyaNova
+    /// 
+    /// Note that the CommandKey value is the hidden internal key that will be passed back to the 
+    /// plugin if a user selects that menu item.
+    /// 
+    /// The Display string is the text displayed to the user in the menu, if it is left empty then an image *must* be provided 
+    /// and only the image will be displayed, no text.
+    ///  
+    /// Images should be 16px square for the small menu image and 32px square for the large menu image.
+    /// Users can choose in AyaNova large or small menu item images, if only one is provided then the other will be scaled
+    /// if required which will display less sharp.
+    /// 
+    /// If both images are null and Display is empty then the menu option will be ignored and not offered to the user.
+    /// If the CommandKey value is empty then the menu option will be ignored and not offered to the user.
+    /// 
+    /// Note: localized text keys can be used within the Display string displayed to the end user
+    /// by surrounding them in parenthesis and starting them with the tag LT:
+    /// 
+    /// For example an option that is presented in a single client editing form could be 
+    /// formatted like this "Transmogrify [LT:O.Client] now" and the [LT:O.Client] would
+    /// be replaced with the localized version automatically based on the current users locale.
+    /// 
+    /// Or an option in a list of clients could be "Transmogrify [LT:Client.Label.List] now" which in default English
+    /// locale would display "Transmogrify clients now";
+    /// </summary>
+    [Serializable]
+    public struct AyaNovaPluginMenuItem
+    {
+        public AyaNovaPluginMenuItem(string ItemKey, string ItemDisplay, Image LargeMenuImage, Image SmallMenuImage)
+        {
+            mCommandKey=ItemKey;
+            mDisplay=ItemDisplay;
+            mMenuItemLargeImage=LargeMenuImage;
+            mMenuItemSmallImage = SmallMenuImage;
+        }
+
+        internal string mCommandKey;
+        internal string mDisplay;
+        internal Image mMenuItemLargeImage;
+        internal Image mMenuItemSmallImage;
+
+        public string CommandKey { get { return mCommandKey; } }
+        public string Display { get { return mDisplay; } }
+        public Image MenuItemLargeImage { get { return mMenuItemLargeImage; } }
+        public Image MenuItemSmallImage { get { return mMenuItemSmallImage; } }
+
+
+    }
+    #endregion
+}