1 /*  $Id: messenger.hpp 104942 2007-05-31 20:08:39Z thiessen $
2 * ===========================================================================
3 *
4 *                            PUBLIC DOMAIN NOTICE
5 *               National Center for Biotechnology Information
6 *
7 *  This software/database is a "United States Government Work" under the
8 *  terms of the United States Copyright Act.  It was written as part of
9 *  the author's official duties as a United States Government employee and
10 *  thus cannot be copyrighted.  This software/database is freely available
11 *  to the public for use. The National Library of Medicine and the U.S.
12 *  Government have not placed any restriction on its use or reproduction.
13 *
14 *  Although all reasonable efforts have been taken to ensure the accuracy
15 *  and reliability of the software and data, the NLM and the U.S.
16 *  Government do not and cannot warrant the performance or results that
17 *  may be obtained by using this software or data. The NLM and the U.S.
18 *  Government disclaim all warranties, express or implied, including
19 *  warranties of performance, merchantability or fitness for any particular
20 *  purpose.
21 *
22 *  Please cite the author in any work or product based on this material.
23 *
24 * ===========================================================================
25 *
26 * Authors:  Paul Thiessen
27 *
28 * File Description:
29 *      Classes to handle messaging and communication between sequence
30 *      and structure windows
31 *
32 * ===========================================================================
33 */
34 
35 #ifndef CN3D_MESSENGER__HPP
36 #define CN3D_MESSENGER__HPP
37 
38 #include <corelib/ncbistl.hpp>
39 #include <objects/mmdb1/Biostruc_annot_set.hpp>
40 
41 #include <string>
42 #include <list>
43 #include <map>
44 #include <vector>
45 
46 
47 BEGIN_SCOPE(Cn3D)
48 
49 // for now, there is only a single global messenger, which for convenience
50 // can be accessed anywhere via this function
51 class Messenger;
52 Messenger * GlobalMessenger(void);
53 
54 
55 class ViewerBase;
56 class BlockMultipleAlignment;
57 class Sequence;
58 class StructureWindow;
59 class StructureObject;
60 class Molecule;
61 class MoleculeIdentifier;
62 class StructureSet;
63 
64 class Messenger
65 {
66 public:
67     // redraw messages - "Post..." means redraw is *not* immediate, but
68     // is cached and actually occurs during system idle time. Thus, during
69     // processing of an event, any number of PostRedraws can be called, and
70     // only one redraw as appropriate will be done at idle time.
71     void PostRedrawSequenceViewer(ViewerBase *viewer);
72     void PostRedrawAllSequenceViewers(void);
73 
74     void PostRedrawMolecule(const Molecule *molecule);
75     void PostRedrawAllStructures(void);
76 
77     // un-Post a redraw message - use (carefully!) to avoid redundant redraws
78     // (flicker) if some other action is known to cause immediate redraw.
79     void UnPostRedrawAllSequenceViewers(void);
80     void UnPostRedrawSequenceViewer(ViewerBase *viewer);
81 
82     // un-Post structure redraws - again, use carefully to avoid redundant redraws
83     // when some non-Messenger method causes structure redraws to occur
84     void UnPostStructureRedraws(void);
85 
86     // should be called only by Cn3DApp at idle time; processes any redraws
87     // that have been posted by prior event(s)
88     void ProcessRedraws(void);
89 
90     // called if the application is about to exit - tell sequence window(s) to save
91     void SequenceWindowsSave(bool prompt);
92 
93     // called to notify all sequence viewers that their font should be changed
94     void NewSequenceViewerFont(void);
95 
96     // these next few are related to highlighting:
97 
98     // typedef for highlight storage
99     typedef std::map < const MoleculeIdentifier *, std::vector < bool > > MoleculeHighlightMap;
100 
101     // check for highlight
102     bool IsHighlighted(const Molecule *molecule, int residueID) const;
103     bool IsHighlighted(const Sequence *sequence, unsigned int seqIndex) const;
104     bool IsHighlightedAnywhere(const MoleculeIdentifier *identifier) const;
105     bool IsHighlightedAnywhere(const Molecule *molecule) const;
106 
107     // clear all highlight stores - and optionally post redraws. Returns 'true'
108     // if there were actually any highlights to remove
109     bool RemoveAllHighlights(bool postRedraws);
110 
111     // add/remove highlights based on sequence
112     void AddHighlights(const Sequence *sequence, unsigned int seqIndexFrom, unsigned int seqIndexTo);
113     void RemoveHighlights(const Sequence *sequence, unsigned int seqIndexFrom, unsigned int seqIndexTo);
114     // toggle highlights on each individual residue in given region
115     void ToggleHighlights(const Sequence *sequence, unsigned int seqIndexFrom, unsigned int seqIndexTo);
116 
117     // highlight any 'ole residue, regardless of molecule type
118     void AddHighlights(const Molecule *molecule, int residueIDFrom, int residueIDTo, bool scrollViewersTo = false);
119     void ToggleHighlight(const Molecule *molecule, int residueID, bool scrollViewersTo = false);
120 
121     // get/set a bunch of highlights all at once - copies highlight list from given set
122     void GetHighlights(MoleculeHighlightMap *copyHighlights);
123     void SetHighlights(const MoleculeHighlightMap& newHighlights);
124 
125     // highlights a sequence and moves viewer to that row
126     void HighlightAndShowSequence(const Sequence *sequence);
127 
128     // remove all highlights except those on the given sequence
129     void KeepHighlightsOnlyOnSequence(const Sequence *sequence);
130 
131     // temporarily turns off highlighting (suspend==true) - but doesn't erase highlight stores,
132     // so when called with suspend==false, highlights will come back on
133     void SuspendHighlighting(bool suspend);
134 
135     // store/restore highlights in/from a cache
136     void CacheHighlights(void);
137     void RestoreCachedHighlights(void);
138 
139 private:
140 
141     // lists of registered viewers
142     typedef std::list < ViewerBase * > SequenceViewerList;
143     SequenceViewerList sequenceViewers;
144     // currently can only have one structure viewer
145     StructureWindow * structureWindow;
146 
147     // to keep track of messages posted
148     typedef std::map < const Molecule *, bool > RedrawMoleculeList; // use map to preclude redundant redraws
149     RedrawMoleculeList redrawMolecules;
150     typedef std::map < ViewerBase *, bool > RedrawSequenceViewerList;
151     RedrawSequenceViewerList redrawSequenceViewers;
152     bool redrawAllStructures;
153     bool redrawAllSequenceViewers;
154     bool highlightingSuspended;
155 
156     // To store lists of highlighted entities
157     MoleculeHighlightMap highlights, highlightCache;
158 
159     bool IsHighlighted(const MoleculeIdentifier *identifier, int index) const;
160     void ToggleHighlights(const MoleculeIdentifier *identifier, unsigned int indexFrom, unsigned int indexTo,
161         const StructureSet *set);
162 
163     void RedrawMoleculesWithIdentifier(const MoleculeIdentifier *identifier, const StructureSet *set);
164 
165 public:
Messenger(void)166     Messenger(void) : redrawAllStructures(false), redrawAllSequenceViewers(false), highlightingSuspended(false) { }
167 
IsAnythingHighlighted(void) const168     bool IsAnythingHighlighted(void) const { return (highlights.size() > 0); }
169 
170     // to get lists of highlighted molecules with structure only (for user annotations)
171     bool GetHighlightedResiduesWithStructure(MoleculeHighlightMap *residues) const;
172 
173     // to get lists of highlighted residues that come from a single structure object
174     // (for cdd annotations) - returns NULL if highlights aren't from one structure
175     ncbi::objects::CBiostruc_annot_set * CreateBiostrucAnnotSetForHighlightsOnSingleObject(void) const;
176 
177     // formats list of highlighted residues for selection messaging; returns true if
178     // there are any highlights
179     bool GetHighlightsForSelectionMessage(std::string *data) const;
180 
181     // to register sequence and structure viewers for redraw postings
AddSequenceViewer(ViewerBase * sequenceViewer)182     void AddSequenceViewer(ViewerBase *sequenceViewer)
183         { sequenceViewers.push_back(sequenceViewer); }
184 
AddStructureWindow(StructureWindow * window)185     void AddStructureWindow(StructureWindow *window)
186         { structureWindow = window; }
187 
188     // to unregister viewers
189     void RemoveStructureWindow(const StructureWindow *structureWindow);
190     void RemoveSequenceViewer(const ViewerBase *sequenceViewer);
191 
192     // set window titles
193     void SetAllWindowTitles(void) const;
194 
195     // for sending messages through file messenger
196     bool IsFileMessengerActive(void) const;
197     void FileMessengerSend(const std::string& toApp, const std::string& command, const std::string& data);
198 };
199 
200 END_SCOPE(Cn3D)
201 
202 #endif // CN3D_MESSENGER__HPP
203