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

Go to the SVN repository for this file.

1 #ifndef GUI_WIDGETS_SEQ_GRAPHIC___LAYOUT_TRACK__HPP
2 #define GUI_WIDGETS_SEQ_GRAPHIC___LAYOUT_TRACK__HPP
3 
4 /* $Id: layout_track.hpp 46676 2021-08-27 22:14:42Z evgeniev $
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  * Author: Liangshou Wu, Victor Joukov
30  *
31  */
32 
33  /**
34  * File Description:
35  */
36 
37 #include <gui/gui_export.h>
38 #include <util/range.hpp>
39 #include <gui/objutils/objects.hpp>
43 
44 class wxMenu;
45 class wxEvtHandler;
46 
48 
49 ///////////////////////////////////////////////////////////////////////////////
50 /// FeaturePanel uses the following extension point to obtain
51 /// registered seqgraphic track factories (instances of CLayoutTrack)
52 
53 #define EXT_POINT__SEQGRAPHIC_LAYOUT_TRACK_FACTORY "seqgraphic_layout_track_factory"
54 
55 class CRenderingContext;
57 class CLayoutTrack;
58 class CTempTrackProxy;
59 
60 ///////////////////////////////////////////////////////////////////////////////
61 /// CTrackTypeInfo - holds description of a layout track type.
63 {
64 public:
65  CTrackTypeInfo(const string& id, const string& description)
66  : m_Id(id)
67  , m_Descr(description)
68  {}
69 
70  virtual ~CTrackTypeInfo() {};
71 
72  const string& GetId() const { return m_Id; }
73  const string& GetDescr() const { return m_Descr; }
74 
75 protected:
76  string m_Id;
77  string m_Descr;
78 };
79 
80 
81 ///////////////////////////////////////////////////////////////////////////////
82 /// ILayoutTrackFactory
84 {
85 public:
86  /// the tracks holding a list of annotation name and track pair.
87  /// for those tracks that don't have annotation concept or no need
88  /// to separate annotations, the key can be just the same as
89  /// the track's name.
91 
92  /// List of annotations with the corresponding titles
94 
96 
97  /// extra parameter for initializing a track.
98  /// the tracks with no concept of level and annotation
99  /// can completely ignore the extra parameters.
101  {
102  typedef vector<string> TAnnots;
103  typedef vector<string> TSubTracks;
104 
105  /// layout level that limits feature retrieving used by annotation
106  /// selector. By default, m_Level is set to -1, resovle all.
107  /// For m_Level >=0, features/data will be fetched up to or on that
108  /// level exactly depending on the setting of m_Adative.
109  int m_Level;
110 
111  /// Adaptive/Exact selector
113 
114  /// particular annotations the track will be looking at.
116 
117  /// potential track-specific filter.
118  /// Any number of fitlers is supported using various logic operators.
119  /// The operators include AND, OR, NOT, LIKE, =, !=, (), >, <, <=, and >= .
120  /// For example:
121  /// f1=f1_val1 and (f1=f1_val2 or f2>f2_val1) and not f3
122  string m_Filter;
123 
124  /// potential track-specific sort_by.
125  /// Rules for specifying sort_by:
126  /// 1. Only one sorting critero is supported at one time
127  /// 2. Sort_by name and values should be in this format:
128  /// sort_by=sort_name[|sort_value1|sort_value2...]
129  /// Sort_name should come at the beginning of the string.
130  /// Sort_values are options, but if there is any, '|' is
131  /// used to separate them from sort_name and from each other.
132  string m_SortBy;
133 
134 
135  /// A subkey for creating feature-specific layout track for a
136  /// generic layout track type. The example of usage is the layout
137  /// track for a subtype of seq-feat.
138  string m_Subkey;
139 
140  /// The requested range we want to look at.
141  /// This is optional since the visible range can also be got from
142  /// the rendering context for most cases. The range need to be
143  /// specified for projecting features from another feature, such
144  /// as alginments.
146 
147  /// Flag indicating if track verification is required.
148  /// By default, a data track will be verified to make sure
149  /// it indeed exists during track configuration.
151 
152  /// when set to true, indicates that that the factory is used by seqconfig
153  /// this means that some operations taking a long time and not needed by seqconfig may be skipped
154  /// while creating the track
155  /// do not use this anywhere but in seqconfig!
156  /// a track created with this flag is not usable for loading the track data!
158 
159  /// Flag indicating if checking coverage graph is necessary.
160  /// By defult, it is true.
162 
163  /// Flag indicating if track data should be checked against declared
164  /// track type.
165  /// By default, it's true.
167 
168  /// List of subTracks
170 
171  /// map of known correspondencies between annots and full titles
173 
174  /// Already used feature track subkeys
175  /// To be used by CAllOtherFeaturesTrack container
177 
178  /// Track setting profile for additionial parameters
180 
181  /// Track remote path
182  string m_RemotePath;
183 
185  : m_Level(-1)
186  , m_Adaptive(true)
187  , m_SkipGenuineCheck(false)
188  , m_FastConfig(false)
189  , m_CoverageGraphCheck(true)
190  , m_DataTypeCheck(true)
191  {}
192 
193  SExtraParams(int level, bool adaptive, const TAnnots* annots = NULL,
194  const string& sub_key = NcbiEmptyString,
195  const string& filter = NcbiEmptyString,
196  const string& sort_by = NcbiEmptyString,
197  const string& remote_path = NcbiEmptyString)
198  : m_Level(level)
199  , m_Adaptive(adaptive)
200  , m_Filter(filter)
201  , m_SortBy(sort_by)
202  , m_Subkey(sub_key)
203  , m_SkipGenuineCheck(false)
204  , m_FastConfig(false)
205  , m_CoverageGraphCheck(true)
206  , m_DataTypeCheck(true)
207  , m_RemotePath(remote_path)
208  {
209  if (annots) m_Annots = *annots;
210  }
211  };
212 
213  /// Help function to find matched annotations.
214  /// @param src_annots is a list of known existing annotations served
215  /// as source annotations. Annotation type and track type may
216  /// or may not be set. It works together with target_annots.
217  /// @param target_annots is the original wanted annotation. The final
218  /// output annotation will be found within the intersection
219  /// set between src_annots and target_annots
220  /// @param annot_type targeted annotation type. If empty, it is ignored.
221  /// @param track_type targeted track type. If empty, it is ignored.
222  /// @param out_annots output annotation list.
223  /// The current implementation only consider named annotations. It
224  /// may be extended to include any other annotations.
225  static void GetMatchedAnnots(const TAnnotMetaDataList& src_annots,
226  const vector<string>& target_annots,
227  const string& annot_type, const string& track_type,
228  TAnnotNameTitleMap& out_annots);
229 
230  /// create a new name based on annotation name and fitler string.
231  static string MergeAnnotAndFilter(const string& annot,
232  const string& filter);
233 
234  /// extract anntation name from a source string.
235  static string ExtractAnnotName(const string& source);
236 
237  /// extract filter name from a source string.
238  static string ExtractFilterName(const string& source);
239 
240  /// create layout tracks based on input object and extra parameters.
241  /// For extra parameters, please refer SExtraParams for details,
242  /// especially, about the assumption for level parameter.
244  SConstScopedObject& object,
245  ISGDataSourceContext* ds_context,
246  CRenderingContext* r_cntx,
247  const SExtraParams& params = SExtraParams(),
248  const TAnnotMetaDataList& src_annots = TAnnotMetaDataList()) const = 0;
249 
250  virtual void GetMatchedAnnots(
251  const TAnnotMetaDataList& /*src_annots*/,
252  const ILayoutTrackFactory::SExtraParams& /*params*/,
253  TAnnotNameTitleMap& /*out_annots*/) const {}
254 
255  /// duplicate any track setting from a given track instance to a proxy.
256  /// by default, it does nothing.
257  virtual void CloneTrack(const CLayoutTrack* /*track*/,
258  CTempTrackProxy* /*track_proxy*/) const {};
259 
260  virtual ~ILayoutTrackFactory() {};
261 
262  /// Have any concept of level.
263  /// Feature retrieving level (adaptive or exact level) for
264  /// annotation selector.
265  virtual bool UnderstandLevel() const = 0;
266 
267  // does this track support export to ASN1?
268  // track factories returning true must be able to accept a NULL as
269  // CRenderingContext in a call to CreateTracks()
270  // the track constructor must be able to accept a NULL as well
271  // and the track should implement IAsn1Generator interface
272  virtual bool SupportsExportToAsn1() const { return false; }
273 
274  /// Background track initialization.
275  /// Since some of track initializations will be time consumming,
276  /// but others are not, we need to know if there is a need to do
277  /// background track initialization.
278  virtual bool NeedBackgroundInit() const = 0;
279 
280  virtual const CTrackTypeInfo& GetThisTypeInfo() const = 0;
281 };
282 
283 
284 ///////////////////////////////////////////////////////////////////////////////
285 /// ITrackConfigurable interface for tracks that are configurable.
286 /// This is currently for sviewer (cgi) purpose.
287 /// If a track is configurable, it should provide a list of settings
288 /// (either dropdown list or check box) exposed to users to modify.
290 {
291 public:
293 
294  virtual ~ITrackConfigurable() {}
296  GetSettings(const string& profile,
297  const TKeyValuePairs& settings,
298  const CTempTrackProxy* track_proxy) const = 0;
299 };
300 
301 
302 ///////////////////////////////////////////////////////////////////////////////
303 /// ILegendProvider interface for tracks that are have legend
304 /// This is currently for sviewer (cgi) purpose.
306 {
307 public:
308  virtual ~ILegendProvider() {}
309  virtual void GetLegend(const CTempTrackProxy* track_proxy, objects::CTrackConfig::TLegend& legend) const = 0;
310 };
311 
312 
313 
314 ///////////////////////////////////////////////////////////////////////////////
315 /// IIconProvider interface for tracks providing track icons.
316 /// For those tracks with special track icons (icon image), the track factory
317 /// need to implement this interface.
319 {
320 public:
321  virtual ~IIconProvider() {}
322  virtual void RegisterIconImages() const = 0;
323 };
324 
325 ///////////////////////////////////////////////////////////////////////////////
326 /// IAsn1Generator interface for tracks capable of generating an ASN1 seq_entry for their data.
328 {
329 public:
330  enum EDataType {
333  eDataType_Vcf
334  };
335 
336  virtual ~IAsn1Generator() {}
337 
338  // write track contents into this seq-entry
339  virtual void GenerateAsn1(objects::CSeq_entry& seq_entry, TSeqRange range) = 0;
340 
341  // if true, this track should be handled by stage 2
342  virtual bool BypassStage1() = 0;
343 
344  // estimate number of features in the specified range
345  // returns true if range is acceptable for downloads
346  // if false, sMsg will contain a message that can be shown to the user
347  // if range was actually checked, nFeats will contain number of features in range
348  virtual bool CheckRange(TSeqRange range, string& sMsg, size_t& nFeats) = 0;
349 
350  // returns the type of the track's data
351  virtual EDataType GetDataType() const { return eDataType_Asn1; }
352 
353  static string DataTypeToString(EDataType data_type);
354 };
355 
356 ///////////////////////////////////////////////////////////////////////////////
357 /// ILayoutTrackHost
358 /// An interface used for handling GUI-related events, such as layout change
359 /// event that requires refresh the screen, zoom event that requires zooming
360 /// to a certain range, and menu event that pops up a context-sensitive menu.
362 {
363 public:
364  virtual ~ILayoutTrackHost() {}
365 
366  /// provides mouse coords in OpenGL viewport coord system
367  //virtual TVPPoint LTH_GetVPPosByWindowPos(const wxPoint& pos) = 0;
368 
369  /// notifies the host about changes of the track.
370  virtual void LTH_OnLayoutChanged() = 0;
371 
372  /// notifies the host we need to zoom on to a range.
373  virtual void LTH_ZoomOnRange(const TSeqRange& range) = 0;
374 
375  /// show track-specific context menu.
376  virtual void LTH_PopupMenu(wxMenu* menu) = 0;
377 
378  virtual void LTH_PushEventHandler(wxEvtHandler* handler) = 0;
379 
380  virtual void LTH_PopEventHandler() = 0;
381 
382  virtual void LTH_ConfigureTracksDlg(const string& category) {}
383 
384  virtual void ResetSearch() {}
385 };
386 
387 
388 ///////////////////////////////////////////////////////////////////////////////
389 /// ITrackContainer
390 /// The interface for layout track that is also a container of tracks.
391 ///
393 {
394 public:
395  virtual ~ITrackContainer() {}
396 
397  /// Replace the track by the given track order.
398  virtual void SetTrack(CLayoutTrack* track, int order, bool shown = true) = 0;
399 
400  /// Duplicate an existing child track.
401  /// @param id the source track order
402  /// @param track_title the track title for the dupliated track
403  virtual void CloneTrack(int order, const string& track_tile) = 0;
404 
405  /// Rename a child track.
406  /// @param id the source track order
407  /// @param new_name the track
408  virtual void RenameChildTrack(int order, const string& new_name) = 0;
409 
410  /// completely remove a track from the hierachical tree.
411  /// @param id is the track order.
412  /// @param immediately if true the track/proxy will be removed
413  /// from its parent immediately. Otherwise, it will be
414  /// marked as 'empty' so that the track removal will
415  /// be done from gui registryand.
416  virtual void RemoveTrack(int order, bool immediately = true) = 0;
417 
418  /// Close a track.
419  /// Hide the given track, but track is not removed.
420  virtual void CloseTrack(int order) = 0;
421 
422  /// move a track up by 1.
423  virtual void MoveUp(int order) = 0;
424 
425  /// move a track down by 1.
426  virtual void MoveDown(int order) = 0;
427 
428  /// move a track up by 1.
429  virtual void MoveTrackToTop(int order) = 0;
430 
431  /// move a track down by 1.
432  virtual void MoveTrackToBottom(int order) = 0;
433 
434  /// Has any real subtracks.
435  /// This differs from Empty() method. Empty() method only considers
436  /// the visible tracks, but HasSubtracks() will consider the ones
437  /// that are off.
438  virtual bool HasSubtracks() const = 0;
439 
440  /// Will have no subtrack for ever.
441  /// There will be no any potential subtracks?
442  virtual bool NoSubtrackEver() const = 0;
443 };
444 
445 
447 
448 #endif // GUI_WIDGETS_SEQ_GRAPHIC___LAYOUT_TRACK__HPP
File Description:
CRef –.
Definition: ncbiobj.hpp:618
CRenderingContext offers the basic context and utility methods for rendering layout objects in featur...
File Description:
CTrackTypeInfo - holds description of a layout track type.
virtual ~CTrackTypeInfo()
CTrackTypeInfo(const string &id, const string &description)
const string & GetDescr() const
const string & GetId() const
IAsn1Generator interface for tracks capable of generating an ASN1 seq_entry for their data.
virtual ~IAsn1Generator()
virtual void GenerateAsn1(objects::CSeq_entry &seq_entry, TSeqRange range)=0
virtual bool CheckRange(TSeqRange range, string &sMsg, size_t &nFeats)=0
virtual EDataType GetDataType() const
virtual bool BypassStage1()=0
IIconProvider interface for tracks providing track icons.
virtual void RegisterIconImages() const =0
virtual ~IIconProvider()
ILayoutTrackFactory.
map< string, CRef< CAnnotMetaData > > TAnnotMetaDataList
virtual ~ILayoutTrackFactory()
virtual bool SupportsExportToAsn1() const
virtual void GetMatchedAnnots(const TAnnotMetaDataList &, const ILayoutTrackFactory::SExtraParams &, TAnnotNameTitleMap &) const
virtual bool UnderstandLevel() const =0
Have any concept of level.
virtual void CloneTrack(const CLayoutTrack *, CTempTrackProxy *) const
duplicate any track setting from a given track instance to a proxy.
virtual const CTrackTypeInfo & GetThisTypeInfo() const =0
map< string, CRef< CLayoutTrack > > TTrackMap
the tracks holding a list of annotation name and track pair.
map< string, string > TAnnotNameTitleMap
List of annotations with the corresponding titles.
virtual TTrackMap CreateTracks(SConstScopedObject &object, ISGDataSourceContext *ds_context, CRenderingContext *r_cntx, const SExtraParams &params=SExtraParams(), const TAnnotMetaDataList &src_annots=TAnnotMetaDataList()) const =0
create layout tracks based on input object and extra parameters.
virtual bool NeedBackgroundInit() const =0
Background track initialization.
ILayoutTrackHost An interface used for handling GUI-related events, such as layout change event that ...
virtual void LTH_ConfigureTracksDlg(const string &category)
virtual ~ILayoutTrackHost()
virtual void LTH_PopupMenu(wxMenu *menu)=0
show track-specific context menu.
virtual void LTH_PushEventHandler(wxEvtHandler *handler)=0
virtual void LTH_OnLayoutChanged()=0
provides mouse coords in OpenGL viewport coord system
virtual void ResetSearch()
virtual void LTH_PopEventHandler()=0
virtual void LTH_ZoomOnRange(const TSeqRange &range)=0
notifies the host we need to zoom on to a range.
ILegendProvider interface for tracks that are have legend This is currently for sviewer (cgi) purpose...
virtual void GetLegend(const CTempTrackProxy *track_proxy, objects::CTrackConfig::TLegend &legend) const =0
virtual ~ILegendProvider()
ISGDSManager is seqgraphic data source manage that serves as an data source context.
ITrackConfigurable interface for tracks that are configurable.
map< string, string > TKeyValuePairs
virtual ~ITrackConfigurable()
virtual CRef< objects::CTrackConfigSet > GetSettings(const string &profile, const TKeyValuePairs &settings, const CTempTrackProxy *track_proxy) const =0
ITrackContainer The interface for layout track that is also a container of tracks.
virtual void CloseTrack(int order)=0
Close a track.
virtual void MoveUp(int order)=0
move a track up by 1.
virtual void MoveTrackToTop(int order)=0
move a track up by 1.
virtual void RemoveTrack(int order, bool immediately=true)=0
completely remove a track from the hierachical tree.
virtual void MoveDown(int order)=0
move a track down by 1.
virtual void CloneTrack(int order, const string &track_tile)=0
Duplicate an existing child track.
virtual void MoveTrackToBottom(int order)=0
move a track down by 1.
virtual bool HasSubtracks() const =0
Has any real subtracks.
virtual bool NoSubtrackEver() const =0
Will have no subtrack for ever.
virtual void SetTrack(CLayoutTrack *track, int order, bool shown=true)=0
Replace the track by the given track order.
virtual ~ITrackContainer()
virtual void RenameChildTrack(int order, const string &new_name)=0
Rename a child track.
Definition: map.hpp:338
void(*)(CSeq_entry_Handle seh, IWorkbench *wb, const CSerialObject &obj) handler
#define true
Definition: bool.h:35
#define false
Definition: bool.h:36
#define NULL
Definition: ncbistd.hpp:225
#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 NcbiEmptyString
Definition: ncbistr.hpp:122
#define NCBI_GUIWIDGETS_SEQGRAPHIC_EXPORT
Definition: gui_export.h:536
Defines to provide correct exporting from DLLs in Windows.
range(_Ty, _Ty) -> range< _Ty >
const CharType(& source)[N]
Definition: pointer.h:1149
extra parameter for initializing a track.
string m_RemotePath
Track remote path.
bool m_Adaptive
Adaptive/Exact selector.
TAnnots m_Annots
particular annotations the track will be looking at.
set< string > m_UsedFeatureSubkeys
Already used feature track subkeys To be used by CAllOtherFeaturesTrack container.
SExtraParams(int level, bool adaptive, const TAnnots *annots=NULL, const string &sub_key=NcbiEmptyString, const string &filter=NcbiEmptyString, const string &sort_by=NcbiEmptyString, const string &remote_path=NcbiEmptyString)
string m_Filter
potential track-specific filter.
string m_SortBy
potential track-specific sort_by.
int m_Level
layout level that limits feature retrieving used by annotation selector.
TSeqRange m_Range
The requested range we want to look at.
string m_TrackProfile
Track setting profile for additionial parameters.
bool m_DataTypeCheck
Flag indicating if track data should be checked against declared track type.
bool m_FastConfig
when set to true, indicates that that the factory is used by seqconfig this means that some operation...
string m_Subkey
A subkey for creating feature-specific layout track for a generic layout track type.
bool m_SkipGenuineCheck
Flag indicating if track verification is required.
bool m_CoverageGraphCheck
Flag indicating if checking coverage graph is necessary.
TAnnotNameTitleMap m_AnnotNameTitleMap
map of known correspondencies between annots and full titles
TSubTracks m_SubTracks
List of subTracks.
Modified on Wed Apr 17 13:08:55 2024 by modify_doxy.py rev. 669887