document.hpp

ncbi源码

/*
 * ===========================================================================
 * PRODUCTION $Log: document.hpp,v $
 * PRODUCTION Revision 1000.5  2004/06/01 19:46:46  gouriano
 * PRODUCTION PRODUCTION: UPGRADED [GCC34_MSVC7] Dev-tree R1.39
 * PRODUCTION
 * ===========================================================================
 */

#ifndef GUI_CORE___DOCUMENT__HPP
#define GUI_CORE___DOCUMENT__HPP

/*  $Id: document.hpp,v 1000.5 2004/06/01 19:46:46 gouriano Exp $
 * ===========================================================================
 *
 *                            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:  Mike DiCuccio
 *
 * File Description:
 *    CDocument -- the basic data unit for GBENCH
 */


#include <corelib/ncbimtx.hpp>
#include <gui/core/idocument.hpp>
#include <gui/core/iview.hpp>
#include <gui/utils/msg_pool.hpp>

#include <gui/utils/view_event.hpp>
#include <util/ievent_receiver.hpp>
#include <util/ievent_transmitter.hpp>


#include <map>

BEGIN_NCBI_SCOPE


class CObjectOStream;
class CDocWorkspace;
class IView;

class NCBI_GUICORE_EXPORT CDocument : public IDocument,
                                      public IEventTransmitter,
                                      public IEventReceiver
{
    friend class CDocManager;

public:

    CDocument();
    virtual ~CDocument(void);

    // Get a description of our contents.
    // This is suitable for display in a GUI component such as a list view.
    const string& GetTitle     (void) const;
    const string& GetShortTitle(void) const;

    // Retrieve the unique ID associated with this document
    size_t GetDocID(void) const;

    // Attach a view to the current document
    virtual void AttachView(IView* view, const string& pool_name = "");

    // Detach a view to the current document
    virtual void DetachView(IView* view);

    // Retrieve the existing views for this class
    const TViews& GetViews(void) const;
    TViews&       SetViews(void);

    // Clear this document.  This is called at application shut-down
    // to make sure all data is properly destroyed.
    virtual void Clear(void);

    // Hide/Show the workspace associated with this document
    void ShowWorkspace(void);
    void HideWorkspace(void);

    // Add an annotation to this document.  This will throw an exception if the
    // action is unsupported.
    void AttachAnnot(objects::CSeq_annot& annot);

    // serialization: write our contents to a stream
    // this is pure virtual to allow derived document types to determine what
    // serialization means for their data
    virtual void Write(CObjectOStream& os) const = 0;

    // access the scope associated with this document
    objects::CScope& GetScope(void) const;
    void             SetScope(objects::CScope& scope);

    // Force all views to update themselves relative to this document.
    // This is equivalent to calling PostDocumentChanged()
    void UpdateAllViews(void);

    // message event triggers.  These functions start the messaging cascade.
    void PostDocumentChanged(const string& msg_pool = kEmptyStr);
    void PostVisibleRangeChanged(const objects::CSeq_loc& loc,
                                 const string& msg_pool = kEmptyStr);
    void PostSelectionChanged(const CSelectionBuffer& buf,
                              const string& msg_pool = kEmptyStr);
    void PostViewCreated(IView& view);
    void PostViewReleased(IView& view);

    // Send event to a views group message pool
    void PostGroupMessage(IView* view, TUpdateFlags flags, 
                          const void* user_data);

     // Transmitter/reciever QI for registering events with document
    virtual IEventTransmitter * QueryInterfaceTransmitter(void);
    virtual IEventReceiver    * QueryInterfaceReceiver(void);

protected:
    // the master scope for this record
    mutable CRef<objects::CScope> m_Scope;

    // the workspace (= container for all views)
    //auto_ptr<CDocWorkspace> m_Workspace;

    // Views attached to this document
    TViews m_Views;

    // positioning information for views
    int m_LastX;
    int m_LastY;

    // titles for this document, one brief the other longer
    string m_Title;
    string m_ShortTitle;

    // mutex for guarding access to internals
    CMutex m_Mutex;

private:

    // document ID - private; derived classes cannot alter
    size_t m_DocId;

    // Message Pool 
    typedef CMsgPool<IView>     TViewMsgPool;
    typedef CMsgPoolMgr<IView>  TViewMsgPoolMgr;

    // the pool manager for this document
    auto_ptr<TViewMsgPoolMgr> m_MsgPoolMgr;

    // the name of the pool containing all possible views
    string m_AllViewsName;

    // the actual pool containing all views
    CRef<TViewMsgPool> m_AllViewsPool;

    // flag: are we currently processing a message in the pool?
    bool m_MsgPosted;

    // map view to its group message pool
    typedef map<IView*, CRef<TViewMsgPool> > TViewGroupPools;
    TViewGroupPools m_ViewGroupPools;

    // internal function to retrieve a single message pool.  This may
    // return NULL if no such view is found.
    TViewMsgPool* x_GetMessagePool(const string& name,
                                   bool create_if_not_found = false);

    // internal function to wrap creation of the all views pool
    TViewMsgPool& x_GetAllViewsPool();

    // internal message posting function
    void x_PostMessage(TViewMsgPool* pool, TUpdateFlags event,
                       const void* data);

    // Prohibit copying!
    CDocument(const CDocument&);
    CDocument& operator= (const CDocument&);

    // IEventTransmitter
    virtual void SetHost(IEventTransmitter * host);
    virtual void FireEvent(const CEvent * evt);

    // IEventReceiver
    virtual void OnEvent(const CEvent * evt);
};


inline
size_t CDocument::GetDocID(void) const
{
    return m_DocId;
}

// Get a description of our contents.
// This is suitable for display in a GUI component such as a list view.
inline
const string& CDocument::GetTitle(void) const
{
    return m_Title;
}


inline
const string& CDocument::GetShortTitle(void) const
{
    return m_ShortTitle;
}


inline
objects::CScope& CDocument::GetScope(void) const
{
    return *m_Scope;
}


// Retrieve the existing views for this class
inline
const IDocument::TViews& CDocument::GetViews(void) const
{
    return m_Views;
}


inline
IDocument::TViews& CDocument::SetViews(void)
{
    return m_Views;
}


END_NCBI_SCOPE



/*
 * ===========================================================================
 * $Log: document.hpp,v $
 * Revision 1000.5  2004/06/01 19:46:46  gouriano
 * PRODUCTION: UPGRADED [GCC34_MSVC7] Dev-tree R1.39
 *
 * Revision 1.39  2004/05/17 13:18:50  dicuccio
 * Removed old document workspace.  Inherit views from IWMClient to support new
 * workspace integration.  Removed references to CChild.
 *
 * Revision 1.38  2004/03/30 17:09:56  tereshko
 * Added support for events broadcasting
 *
 * Revision 1.37  2003/12/31 20:31:02  dicuccio
 * Added internal functions to wrap handling of message pools
 *
 * Revision 1.36  2003/12/22 19:12:10  dicuccio
 * Modified mechanism for view-view messaging: provide more explicit function
 * signatures; added helper functions to make posting messages easier.
 *
 * Revision 1.35  2003/11/19 20:41:06  friedman
 * Added grouping views into group message pools
 *
 * Revision 1.33  2003/11/06 19:51:40  dicuccio
 * Changed API for ATtachView() to take an optional message pool name
 *
 * Revision 1.32  2003/11/04 17:10:22  dicuccio
 * Added variables to hold positions of most recent views
 *
 * Revision 1.31  2003/11/04 13:08:15  dicuccio
 * Changed storage of message pool to CRef<> instead of C++ reference
 *
 * Revision 1.30  2003/11/04 12:29:50  friedman
 * Added all view message pool to be invoked fom UpdateAllViews. Replaces
 * iterating through the all the views and calling Update.
 *
 * Revision 1.29  2003/10/10 17:10:30  dicuccio
 * Added interface functions to detach a view from a document
 *
 * Revision 1.28  2003/09/04 14:00:26  dicuccio
 * Introduce IDocument and IView as abstract base classes.  Use IDocument instead
 * of CDocument.
 *
 * Revision 1.27  2003/08/22 15:54:48  dicuccio
 * General clean-up:  Removed unneeded export specifiers from templates; removed
 * 'USING_SCOPE(objects)'
 *
 * Revision 1.26  2003/07/31 16:40:58  dicuccio
 * Added document ID
 *
 * Revision 1.25  2003/06/25 16:59:41  dicuccio
 * Changed CPluginHandle into a pointer-to-implementation (the previous
 * implementation is now the pointer held).  Lots of #include file clean-ups.
 *
 * Revision 1.24  2003/06/17 19:40:16  dicuccio
 * Added AttachAnnot()
 *
 * Revision 1.23  2003/06/02 16:01:29  dicuccio
 * Rearranged include/objects/ subtree.  This includes the following shifts:
 *     - include/objects/alnmgr --> include/objtools/alnmgr
 *     - include/objects/cddalignview --> include/objtools/cddalignview
 *     - include/objects/flat --> include/objtools/flat
 *     - include/objects/objmgr/ --> include/objmgr/
 *     - include/objects/util/ --> include/objmgr/util/
 *     - include/objects/validator --> include/objtools/validator
 *
 * Revision 1.22  2003/05/08 16:17:39  dicuccio
 * Changed CFastMutex -> CMutex (locks must be recursive-safe)
 *
 * Revision 1.21  2003/05/05 12:38:51  dicuccio
 * Added mutex for guarding access to CDocument's data members
 *
 * Revision 1.20  2003/04/29 14:28:44  dicuccio
 * Removed last vestiges of old typing system
 *
 * Revision 1.19  2003/04/24 16:11:49  dicuccio
 * Large revision.  Removed old notions of document == bioseq-handle; instituted
 * new abstract base class in which a document holds a scope
 *
 * Revision 1.18  2003/04/10 19:49:06  dicuccio
 * Made text description a member variable
 *
 * Revision 1.17  2003/03/31 13:50:03  dicuccio
 * Added general mechanism for determination of feature subtypes - permits
 * exploration of different modes of feature resolution
 *
 * Revision 1.16  2003/03/17 14:56:54  dicuccio
 * Removed dependency on view.hpp.  Added member variable for workspace, one per
 * document.  Added Show()/Hide() functions for workspace.
 *
 * Revision 1.15  2003/03/03 15:35:10  dicuccio
 * Added view slaved flag
 *
 * Revision 1.14  2003/02/20 19:44:06  dicuccio
 * Created new plugin architecture, mediated via an ASN.1 spec.  Moved GBENCH
 * framework over to use new plugin architecture.
 *
 * Revision 1.13  2003/02/05 19:35:38  dicuccio
 * Added member variable for the scope of a bioseq handle.  Removed user-level
 * annotations (unused and unnecessary).
 *
 * Revision 1.12  2003/01/13 13:11:41  dicuccio
 * Namespace clean-up.  Retired namespace gui -> converted to namespace ncbi.
 * Moved all FLUID-generated code into namespace ncbi.
 *
 * Revision 1.11  2003/01/08 15:34:16  dicuccio
 * Added missing #includes
 *
 * Revision 1.10  2003/01/08 14:41:06  dicuccio
 * Revamped type resolution - each record is now bound to a list of its types so
 * that records can be typed based on sub-components.
 *
 * Revision 1.9  2002/12/20 19:09:03  dicuccio
 * Changed SetViews() -> GetViews()
 *
 * Revision 1.8  2002/12/19 18:13:02  dicuccio
 * Added export specifiers for Win32.
 *
 * Revision 1.7  2002/12/09 20:38:29  dicuccio
 * Added user-level annotations.  These annotations are not strictly part of the
 * record, but may be added to the record as desired.
 *
 * Revision 1.6  2002/11/29 15:55:17  dicuccio
 * Added somewhat obtuse work-around for MSVC's handling of namespaces (the
 * nested namespace ncbi::objects presents a lot of difficulty for MSVC's
 * compiler)
 *
 * Revision 1.5  2002/11/25 19:25:34  dicuccio
 * Added function to explicitly set the bioseq-handle - used by data loader
 * plugins.  Added default flags to UpdateAllViews(): update all events by
 * default.
 *
 * Revision 1.4  2002/11/09 22:56:39  dicuccio
 * Provide public access to non-const view list and view attachment.
 *
 * Revision 1.3  2002/11/07 18:20:13  dicuccio
 * Moved #ifdef to top of file.
 *
 * Revision 1.2  2002/11/05 19:45:47  dicuccio
 * Promote CViewUtils to be a friend of CDocument
 *
 * Revision 1.1  2002/11/04 21:09:06  dicuccio
 * Initial revision
 *
 * ===========================================================================
 */

#endif  // GUI_CORE___DOCUMENT__HPP