NCBI C++ ToolKit
extension.hpp
Go to the documentation of this file.

Go to the SVN repository for this file.

1 #ifndef GUI_GUI___EXTENSION__HPP
2 #define GUI_GUI___EXTENSION__HPP
3 
4 /* $Id: extension.hpp 18397 2008-11-28 19:45:17Z dicuccio $
5  * ===========================================================================
6  *
7  * PUBLIC DOMAIN NOTICE
8  * National Center for Biotechnology Information
9  *
10  * This software/database is a "United States Government Work" under the
11  * terms of the United States Copyright Act. It was written as part of
12  * the author's official duties as a United States Government employee and
13  * thus cannot be copyrighted. This software/database is freely available
14  * to the public for use. The National Library of Medicine and the U.S.
15  * Government have not placed any restriction on its use or reproduction.
16  *
17  * Although all reasonable efforts have been taken to ensure the accuracy
18  * and reliability of the software and data, the NLM and the U.S.
19  * Government do not and cannot warrant the performance or results that
20  * may be obtained by using this software or data. The NLM and the U.S.
21  * Government disclaim all warranties, express or implied, including
22  * warranties of performance, merchantability or fitness for any particular
23  * purpose.
24  *
25  * Please cite the author in any work or product based on this material.
26  *
27  * ===========================================================================
28  *
29  * Authors: Andrey Yazhuk
30  *
31  * File Description:
32  * Application Extension API
33  */
34 
35 
36 /** @addtogroup GUI_UTILS
37  *
38  * @{
39  */
40 
41 #include <gui/gui_export.h>
42 
43 #include <corelib/ncbiobj.hpp>
44 
45 
47 
48 ///////////////////////////////////////////////////////////////////////////////
49 /// IExtension
50 /// IExtension interface represents an abstract pluggable component. Software
51 /// components can contribute Extensions to various Extension Points in order
52 /// to add new functionality to the application.
53 /// IExtension is managed by CIRef and so classes implementing IExtension
54 /// interface need to be CRef-compatible (for instance, derived from CObject)
55 
57 {
58 public:
59  /// returns the unique human-readable identifier for the extension
60  /// the id should use lowercase letters separated by underscores - "like_this"
61  virtual string GetExtensionIdentifier() const = 0;
62 
63  /// returns a displayable label for this extension
64  /// ( please capitalize the key words - "My Extension" )
65  virtual string GetExtensionLabel() const = 0;
66 
67  virtual ~IExtension() {};
68 };
69 
70 
71 ///////////////////////////////////////////////////////////////////////////////
72 /// IExtensionPoint
73 ///
74 /// IExtensionPoint interface represents an aspect of an application
75 /// functionality that can be extended by pluggable components.
76 /// Each Extension Point has a unique ID and represents an aspect of the
77 /// application that can be abstracted. For instance an Extension Point can
78 /// represent a place in a popup menu where arbitrary commands can be inserted.
79 /// Any software component in an application can declare its own Extension Points
80 /// to allow other components to add new functionality. Usually an Extension Point
81 /// is associated with a specific interface and all Extensions contributed to
82 /// this point must implement this interface.
83 
85 {
86 public:
88  typedef vector<TExtRef> TExtVec;
89 
90 public:
91  // returns the unique identifier of this extension
92  virtual string GetIdentifier() const = 0;
93 
94  // returns a displayable label for this extension
95  virtual string GetLabel() const = 0;
96 
97  // return true if extension is succesfully added
98  virtual bool AddExtension(IExtension& extension) = 0;
99 
100  // retuns an extension with the given id (or empty reference)
101  virtual TExtRef GetExtension(const string& ext_id) = 0;
102 
103  // fills the container with references to extensions
104  virtual void GetExtensions(TExtVec& extensions) = 0;
105 
106  // removes the given extension, if extension is not found returns false
107  virtual bool RemoveExtension(IExtension& extension) = 0;
108 
109  // removes the extension with the given id, if extension is not found returns false
110  virtual bool RemoveExtension(const string& ext_id) = 0;
111 
112  virtual ~IExtensionPoint() {};
113 };
114 
115 
116 ///////////////////////////////////////////////////////////////////////////////
117 /// IExtensionRegistry
118 /// IExtensionRegistry is an interface representing a Registry where Extension
119 /// Points and Extensions are registered. IExtensionRegistry provides a more
120 /// convenient higher-level API for working with Points and Extensions.
122 {
123 public:
125  typedef vector<TExtRef> TExtVec;
127  typedef vector<TExtPointRef> TExtPointVec;
128 
129 public:
130  /// adds a new Extension Point, returns true if successful
131  virtual bool AddExtensionPoint(IExtensionPoint& ext_point) = 0;
132 
133  /// adds a new Extension Point, returns true if successful
134  virtual bool AddExtensionPoint(const string& ext_point_id,
135  const string& ext_point_label) = 0;
136 
137  /// adds a new Extension to an Extension Point, if the Point does not exists
138  /// creates a new one, returns true if successful
139  virtual bool AddExtension(const string& ext_point_id,
140  IExtension& extension) = 0;
141 
142  /// finds and returns a reference to an Extension with the specified Id,
143  /// search is performed across all Points in the Registry
144  /// returns null if there the Id is not found
145  virtual TExtRef GetExtension(const string& extension_id) = 0;
146 
147  /// finds and returns a reference to an Extension with the specified Id,
148  /// search is performed only in the Extension Point with the given Id,
149  /// returns null if there the Id is not found
150  virtual TExtRef GetExtension(const string& ext_point_id,
151  const string& extension_id) = 0;
152 
153  /// returns a reference to an Extension Point with the given identifier,
154  /// returns null if there the Id is not found
155  virtual TExtPointRef GetExtensionPoint(const string& ext_point_id) = 0;
156 
157  /// finds an Extension Point with the given Id and fills the given container
158  /// with references to all Extensions registered in the Point.
159  /// returns false if a Point with the given id is not registered
160  virtual bool GetExtensions(const string& ext_point_id,
161  TExtVec& extensions) = 0;
162 
163  /// fills the given container with all Extension Points registered
164  virtual void GetExtensionPoints(TExtPointVec& ext_points) = 0;
165 
166  /// removes the given Extension from all Extension Points in the Registry
167  /// returns false if the Extension is not registered
168  virtual bool RemoveExtension(IExtension& extension) = 0;
169 
170  /// removes the Extension with the given Id from all Extension Point in the
171  /// Registry, returns false if the Extension Id is not found
172  virtual bool RemoveExtension(const string& ext_id) = 0;
173 
174  /// removes the given Extension from the Extension Point with the given id
175  /// returns false if the Point or Extension is not found
176  virtual bool RemoveExtension(const string& ext_point_id,
177  IExtension& extension) = 0;
178 
179  /// removes the Extension with the given Id from the Extension Point with
180  /// the specified Id.
181  /// returns false if the Point or Extension is not found
182  virtual bool RemoveExtension(const string& ext_point_id,
183  const string& ext_id) = 0;
184 
185  /// removes the specified Extension Point from the Registry.
186  virtual bool RemoveExtensionPoint(IExtensionPoint& ext_point) = 0;
187 
188  virtual ~IExtensionRegistry() {}
189 };
190 
191 
193 
194 /* @} */
195 
196 #endif // GUI_GUI___EXTENSION__HPP
IExtensionPoint.
Definition: extension.hpp:85
IExtensionRegistry IExtensionRegistry is an interface representing a Registry where Extension Points ...
Definition: extension.hpp:122
IExtension IExtension interface represents an abstract pluggable component.
Definition: extension.hpp:57
virtual string GetIdentifier() const =0
virtual ~IExtension()
Definition: extension.hpp:67
virtual TExtRef GetExtension(const string &extension_id)=0
finds and returns a reference to an Extension with the specified Id, search is performed across all P...
virtual string GetExtensionLabel() const =0
returns a displayable label for this extension ( please capitalize the key words - "My Extension" )
virtual bool AddExtension(IExtension &extension)=0
virtual ~IExtensionRegistry()
Definition: extension.hpp:188
virtual bool AddExtension(const string &ext_point_id, IExtension &extension)=0
adds a new Extension to an Extension Point, if the Point does not exists creates a new one,...
virtual bool AddExtensionPoint(IExtensionPoint &ext_point)=0
adds a new Extension Point, returns true if successful
virtual string GetExtensionIdentifier() const =0
returns the unique human-readable identifier for the extension the id should use lowercase letters se...
virtual string GetLabel() const =0
virtual TExtRef GetExtension(const string &ext_point_id, const string &extension_id)=0
finds and returns a reference to an Extension with the specified Id, search is performed only in the ...
virtual void GetExtensionPoints(TExtPointVec &ext_points)=0
fills the given container with all Extension Points registered
virtual bool RemoveExtension(const string &ext_id)=0
removes the Extension with the given Id from all Extension Point in the Registry, returns false if th...
virtual TExtRef GetExtension(const string &ext_id)=0
virtual TExtPointRef GetExtensionPoint(const string &ext_point_id)=0
returns a reference to an Extension Point with the given identifier, returns null if there the Id is ...
virtual ~IExtensionPoint()
Definition: extension.hpp:112
virtual void GetExtensions(TExtVec &extensions)=0
vector< TExtRef > TExtVec
Definition: extension.hpp:88
CIRef< IExtensionPoint > TExtPointRef
Definition: extension.hpp:126
CIRef< IExtension > TExtRef
Definition: extension.hpp:87
virtual bool RemoveExtension(const string &ext_point_id, const string &ext_id)=0
removes the Extension with the given Id from the Extension Point with the specified Id.
vector< TExtPointRef > TExtPointVec
Definition: extension.hpp:127
virtual bool RemoveExtensionPoint(IExtensionPoint &ext_point)=0
removes the specified Extension Point from the Registry.
virtual bool RemoveExtension(const string &ext_point_id, IExtension &extension)=0
removes the given Extension from the Extension Point with the given id returns false if the Point or ...
virtual bool RemoveExtension(const string &ext_id)=0
virtual bool GetExtensions(const string &ext_point_id, TExtVec &extensions)=0
finds an Extension Point with the given Id and fills the given container with references to all Exten...
vector< TExtRef > TExtVec
Definition: extension.hpp:125
virtual bool AddExtensionPoint(const string &ext_point_id, const string &ext_point_label)=0
adds a new Extension Point, returns true if successful
virtual bool RemoveExtension(IExtension &extension)=0
CIRef< IExtension > TExtRef
Definition: extension.hpp:124
virtual bool RemoveExtension(IExtension &extension)=0
removes the given Extension from all Extension Points in the Registry returns false if the Extension ...
#define END_NCBI_SCOPE
End previously defined NCBI scope.
Definition: ncbistl.hpp:103
#define BEGIN_NCBI_SCOPE
Define ncbi namespace.
Definition: ncbistl.hpp:100
#define NCBI_GUIUTILS_EXPORT
Definition: gui_export.h:518
Defines to provide correct exporting from DLLs in Windows.
Portable reference counted smart and weak pointers using CWeakRef, CRef, CObject and CObjectEx.
Modified on Fri Sep 20 14:57:10 2024 by modify_doxy.py rev. 669887