#ifndef GUI_PLUGIN_PLUGIN_HPP #define GUI_PLUGIN_PLUGIN_HPP /* $Id: plugin.hpp 14666 2007-07-09 13:40:22Z dicuccio $ * =========================================================================== * * PUBLIC DOMAIN NOTICE * National Center for Biotechnology Information * * This software/database is a "United States Government Work" under the * terms of the United States Copyright Act. It was written as part of * the author's official duties as a United States Government employee and * thus cannot be copyrighted. This software/database is freely available * to the public for use. The National Library of Medicine and the U.S. * Government have not placed any restriction on its use or reproduction. * * Although all reasonable efforts have been taken to ensure the accuracy * and reliability of the software and data, the NLM and the U.S. * Government do not and cannot warrant the performance or results that * may be obtained by using this software or data. The NLM and the U.S. * Government disclaim all warranties, express or implied, including * warranties of performance, merchantability or fitness for any particular * purpose. * * Please cite the author in any work or product based on this material. * * =========================================================================== * * Authors: Mati Shomrat * * File Description: * CPlugin - defines a base interface for all plugins */ #include <corelib/ncbistd.hpp> #include <gui/gui_export.h> #include <gui/objects/PluginMessage.hpp> #include <gui/core/resolver.hpp> #include <gui/utils/reporter.hpp> BEGIN_NCBI_SCOPE BEGIN_SCOPE(objects) class CPluginInfoSet; class CPluginArg; class CPluginArgSet; END_SCOPE(objects) typedef void (*FPluginArgCallback)( objects::CPluginArg& arg, objects::CPluginArgSet& set ); class NCBI_GUIOBJECTS_EXPORT CPluginBase : public CObject { public: /// destructor virtual ~CPluginBase(void); /// @name Message-passing interface /// @{ /// pass a message to the plugin /// This function will perform validation on the message and delegate /// actual handling to user-overridable methods. void Execute(objects::CPluginMessage& msg); /// Initialize the plugin. This maps to the plugin command /// CPluginCommand::eCommand_init, and takes no arguments. No specific /// registration is needed to obtain this command; however, if you want /// to register 'init' as an auto-initializable command (i.e., a command /// launched at application start-up), then you will need to register the /// command. This command is implicitly supported by all plugins. The /// provided plugin message is largely for future extension. virtual void Init(objects::CPluginMessage& msg); virtual void CreateInterface(objects::CPluginMessage& msg); /// Execute the 'load' command. This maps to CPluginCommand::eCommand_load. /// Use of this command requires registration in the plugin's information /// settings, and explicit override from the user. Calling this command /// on a plugin that does not support it will result in an exception. virtual void Load(objects::CPluginMessage& msg); /// Execute the 'save' command. This maps to CPluginCommand::eCommand_save. /// Use of this command requires registration in the plugin's information /// settings, and explicit override from the user. Calling this command /// on a plugin that does not support it will result in an exception. virtual void Save(objects::CPluginMessage& msg); /// Execute the 'import' command. This maps to CPluginCommand::eCommand_import. /// Use of this command requires registration in the plugin's information /// settings, and explicit override from the user. Calling this command /// on a plugin that does not support it will result in an exception. virtual void Import(objects::CPluginMessage& msg); /// Execute the 'load-project' command. This maps to /// CPluginCommand::eCommand_load_project. Use of this command requires /// registration in the plugin's information settings, and explicit override /// from the user. Calling this command on a plugin that does not support it /// will result in an exception. This command is implicitly supported by all /// data plugins so that the framework can generically call LoadProject on /// any data plugin. virtual void LoadProject(objects::CPluginMessage& msg); /// Execute the 'save-project' command. This maps to /// CPluginCommand::eCommand_save_project. Use of this command requires /// registration in the plugin's information settings, and explicit override /// from the user. Calling this command on a plugin that does not support it /// will result in an exception. This command is implicitly supported by all /// data plugins so that the framework can generically call LoadProject on any /// data plugin. virtual void SaveProject(objects::CPluginMessage& msg); /// Execute the 'search' command. This maps to CPluginCommand::eCommand_search. /// Use of this command requires registration in the plugin's information /// settings, and explicit override from the user. Calling this command on a /// plugin that does not support it will result in an exception. virtual void Search(objects::CPluginMessage& msg); /// Execute the 'manage' command. This maps to CPluginCommand::eCommand_manage. /// Use of this command requires registration in the plugin's information /// settings, and explicit override from the user. Calling this command on a /// plugin that does not support it will result in an exception. virtual void Manage(objects::CPluginMessage& msg); /// Execute the 'run' command. This maps to CPluginCommand::eCommand_run. /// Use of this command requires registration in the plugin's information /// settings, and explicit override from the user. Calling this command on a /// plugin that does not support it will result in an exception. virtual void Run(objects::CPluginMessage& msg); /// Wait until the plugin has completed its execution. Plugins that override /// this API should block until execution of their plugin has completed. This /// maps to the plugin command CPluginCommand::eCommand_finish. This command /// is implicitly supported by all plugins. The provided plugin message is /// largely for future extension. virtual void Finish(objects::CPluginMessage& msg); /// Attempt to stop a plugin's operation immediately. This maps to the plugin /// command CPluginCommand::eCommand_abort. If a plugin manages a thread of /// its own, it must respond to this command and block until the thread has /// been stopped. This command is implicitly supported by all plugins. The /// provided plugin message is largely for future extension. virtual void Abort(objects::CPluginMessage& msg); /// Pause execution of a plugin. This maps to the plugin command /// CPluginCommand::eCommand_suspend. This command is implicitly supported by /// all plugins. If a plugin manages a thread, it should overload this function /// and provide a blocking thread suspension. The provided plugin message is /// largely for future extension. virtual void Suspend(objects::CPluginMessage& msg); /// Resume execution of a paused plugin. This maps to the plugin command /// CPluginCommand::eCommand_resume. This command is implicitly supported by /// all plugins. If a plugin manages a thread, it should overload this function /// and provide a blocking thread resumption. The provided plugin message is /// largely for future extension. virtual void Resume(objects::CPluginMessage& msg); /// Create a new view. This maps to the plugin command /// CPluginCommand::eCommand_new_view. Use of this command requires /// registration in the plugin's information settings, and explicit override /// from the user. Calling this command on a plugin that does not support it /// will result in an exception. virtual void NewView(objects::CPluginMessage& msg); /// Create a new composite view. This maps to the plugin command /// CPluginCommand::eCommand_new_composite_view. A composite view differs from /// a regular view in that a composite view serves as a container for other /// views. Composite views are derived from IViewComposite or CViewComposite. /// Use of this command requires registration in the plugin's information /// settings, and explicit override from the user. Calling this command on a /// plugin that does not support it will result in an exception. virtual void NewCompositeView(objects::CPluginMessage& msg); /// Retrieve some status information about the current execution. GetStatus() /// is passed a message with two arguments - 'pct_completed' and 'message' - /// so that a plugin can fill in some basic status information virtual void GetStatus(objects::CPluginMessage& msg); /// @} /// @name Message-free interface /// @{ /// Status inquiry: Are we still running? The default implementation returns /// true, and assumes that all tasks are running in a non-threaded, blocking /// fashion. If an algorithm is managing a thread or interactive dialog, /// this function should be overridden to prevent the instance from being /// deleted until interaction or computation is completed. virtual bool IsCompleted(void) const; /// Retrieve information about a plugin's arguments, class names, and so forth. virtual void GetPluginInfo(objects::CPluginInfoSet& info) const = 0; /// Finalize the arguments (gets called just before argument dialog). /// Version defined here does nothing; subclasses should override /// if they want to do something. virtual void FinalizeArgs(objects::CPluginMessage& msg); /// Validate all the arguments (gets called just after argument dialog). /// If arguments are not valid, it thows an exception. Primarily it is /// to be catched in PluginArgDialog, so it is of CDDV_DDX_Exception type. /// Version defined here does nothing; subclasses should override /// if they want to do something. virtual objects::CPluginArg* ValidateArgs(objects::CPluginArgSet& set); /// This is the way to provide customized resolving dialog for particular /// plugin. By default, it returns NULL, thus standard global resolver will /// be used. virtual FResolvePluginArgs GetArgsResolver(); /// This is the way to provide a dynamic behaviour of automatically generated /// PluginArgForm. virtual FPluginArgCallback GetPluginArgCallback(); /// @} }; template<typename PluginType> class CPlugin : public CPluginBase { public: /// overloaded GetInfo() - we call a static function in our derived plugin /// type. This static function is a requirement of all plugin /// implementations. virtual void GetPluginInfo(objects::CPluginInfoSet& info) const { PluginType::GetInfo(info); } }; END_NCBI_SCOPE #endif /// GUI_PLUGIN_PLUGIN_HPP
0001 0002 0003 0004 0005 0006 0007 0008 0009 0010 0011 0012 0013 0014 0015 0016 0017 0018 0019 0020 0021 0022 0023 0024 0025 0026 0027 0028 0029 0030 0031 0032 0033 0034 0035 0036 0037 0038 0039 0040 0041 0042 0043 0044 0045 0046 0047 0048 0049 0050 0051 0052 0053 0054 0055 0056 0057 0058 0059 0060 0061 0062 0063 0064 0065 0066 0067 0068 0069 0070 0071 0072 0073 0074 0075 0076 0077 0078 0079 0080 0081 0082 0083 0084 0085 0086 0087 0088 0089 0090 0091 0092 0093 0094 0095 0096 0097 0098 0099 0100 0101 0102 0103 0104 0105 0106 0107 0108 0109 0110 0111 0112 0113 0114 0115 0116 0117 0118 0119 0120 0121 0122 0123 0124 0125 0126 0127 0128 0129 0130 0131 0132 0133 0134 0135 0136 0137 0138 0139 0140 0141 0142 0143 0144 0145 0146 0147 0148 0149 0150 0151 0152 0153 0154 0155 0156 0157 0158 0159 0160 0161 0162 0163 0164 0165 0166 0167 0168 0169 0170 0171 0172 0173 0174 0175 0176 0177 0178 0179 0180 0181 0182 0183 0184 0185 0186 0187 0188 0189 0190 0191 0192 0193 0194 0195 0196 0197 0198 0199 0200 0201 0202 0203 0204 0205 0206 0207 0208 0209 0210 0211 0212 0213 0214 0215 0216 0217 0218 0219 0220 0221 0222 0223 0224 0225 0226 0227 0228 0229 0230 0231 0232 0233 0234