[occt.git] / src / TDocStd / TDocStd_Application.cdl

-- Created on: 1999-06-30
-- Created by: Denis PASCAL
-- Copyright (c) 1999 Matra Datavision
-- Copyright (c) 1999-2012 OPEN CASCADE SAS
--
-- The content of this file is subject to the Open CASCADE Technology Public
-- License Version 6.5 (the "License"). You may not use the content of this file
-- except in compliance with the License. Please obtain a copy of the License
-- at http://www.opencascade.org and read it completely before using this file.
--
-- The Initial Developer of the Original Code is Open CASCADE S.A.S., having its
-- main offices at: 1, place des Freres Montgolfier, 78280 Guyancourt, France.
--
-- The Original Code and all software distributed under the License is
-- distributed on an "AS IS" basis, without warranty of any kind, and the
-- Initial Developer hereby disclaims all such warranties, including without
-- limitation, any warranties of merchantability, fitness for a particular
-- purpose or non-infringement. Please see the License for the specific terms
-- and conditions governing the rights and limitations under the License.


deferred class Application from TDocStd inherits Application from CDF

	---Purpose:  
    	-- The abstract root class for all application classes.
    	-- They are in charge of:
    	-- -   Creating documents
    	-- -   Storing documents and retrieving them
    	-- -   Initializing document views.
    	-- To create a useful OCAF-based application, you
    	-- derive a class from Application and implement
    	-- the methods below. You will have to redefine the
    	-- deferred (virtual) methods Formats,
    	-- InitDocument, and Resources, and override others.
    	-- The application is a container for a document,
    	-- which in its turn is the container of the data
    	-- framework made up of labels and attributes.
    	-- Besides furnishing a container for documents,
    	-- TDocStd_Application provides the following
    	-- services for them:
    	-- -   Creation of new documents
    	-- -   Activation of documents in sessions of an application
    	-- -   Storage and retrieval of documents
    	-- -   Initialization of document views.
    	-- Note:
    	-- If a client needs detailed information concerning
    	-- the events during the Open/Store operation, MessageDriver
    	-- inherited from CDM_MessageDriver of the
    	-- corresponding application has to be implemented. 
    	-- If the MessageDriver is not defined all messages
    	-- will be (by default) directed to
    	-- CDM_NullMessageDriver and will be lost.

uses Manager                  from Resource,
     Document                 from TDocStd,
     CString                  from Standard,
     ExtendedString           from TCollection,
     SequenceOfExtendedString from TColStd,
     ReaderStatus             from PCDM,
     StoreStatus              from PCDM

raises NoSuchObject from Standard

is

    Initialize;

    IsDriverLoaded (me)
    	---Purpose: Check if meta data driver was successfully loaded
    	--          by the application constructor
    returns Boolean from Standard;

 
    Resources (me: mutable)
    	---Purpose: create  (if  not done)  a Manager  using ResourcesName
    	--          method.
    returns Manager from Resource
    is redefined virtual;

    ResourcesName (me: mutable)
    	---Purpose:  Returns the name of the file containing the
    	-- resources of this application.
    	-- In a resource file, the application associates the schema name 
    	-- of the document with the storage and
    	-- retrieval plug-ins that are to be loaded for each
    	-- document. On retrieval, the application reads the
    	-- schema name in the heading of the CSF file and
    	-- loads the plug-in indicated in the resource file.
    	-- This plug-in instantiates the actual driver for
    	-- transient-persistent conversion.
    	-- Your application can bring this process into play
    	-- by defining a class which inherits
    	-- CDF_Application and redefines the function
    	-- which returns the appropriate resources file. At
    	-- this point, the function Retrieve and the class
    	-- CDF_Store can be called. This allows you to
    	-- deal with storage and retrieval of - as well as
    	-- copying and pasting - documents.
    	-- To implement a class like this, several virtual
    	-- functions should be redefined. In particular, you
    	-- must redefine the abstract function Resources
    	-- inherited from the superclass CDM_Application.
    returns CString from Standard
    is deferred;

    NbDocuments (me)
    	---Purpose: returns the number of documents handled by the current applicative session.
    returns Integer from Standard;

    GetDocument (me; index : Integer from Standard; aDoc : in out Document from TDocStd);
    	---Purpose: Constructs the new document aDoc.
    	-- aDoc is identified by the index index which is
    	-- any integer between 1 and n where n is the
    	-- number of documents returned by NbDocument.
    	-- Example
    	-- Handle(TDocStd_Application)
    	-- anApp;
    	-- if (!CafTest::Find(A)) return 1;
    	--  Handle(TDocStd) aDoc;
    	-- Standard_Integer nbdoc = anApp->NbDocuments();
    	-- for (Standard_Integer i = 1; i <= nbdoc; i++) {
    	-- aApp->GetDocument(i,aDoc);
    
    Formats(me: mutable; Formats: out SequenceOfExtendedString from TColStd)
    	---Purpose: 
    	-- Returns the format name Formats
    	-- representing the format supported for
    	-- application documents.
    	-- This virtual function is to be redefined for each
    	-- specific application.
    is redefined deferred;

    NewDocument (me : mutable; format : ExtendedString from TCollection; aDoc : out Document from TDocStd)
    	---Purpose: Constructs the empty new document aDoc.
    	-- This document will have the format format.
    	-- If InitDocument is redefined for a specific
    	-- application, the new document is handled by the
    	-- applicative session.
    is virtual;

    InitDocument (me; aDoc : Document from TDocStd)
    	---Purpose: Initialize the document aDoc for the applicative session.
    	-- This virtual function is called by NewDocument
    	-- and is to be redefined for each specific application.
        
    is virtual;


    ---Purpose: Modified flag (different of disk version)
    --          =============

    --Modify(me: mutable); (see CDM_Document)


    --IsModified(me) returns Boolean from Standard; (see CDM_Document)


    ---Purpose: to open/save a document
    --          =======================

    Close  (me : mutable; aDoc : Document from TDocStd);
    ---Purpose: Close the given document. the document is not any more
    --          handled by the applicative session.


    IsInSession (me; path : ExtendedString from TCollection)
    	---Purpose:  Returns an index for the document found in the
    	-- path path in this applicative session.
    	-- If the returned value is 0, the document is not
    	-- present in the applicative session.
   	-- This method can be used for the interactive part
    	-- of an application. For instance, on a call to
    	-- Open, the document to be opened may already
    	-- be in memory. IsInSession checks to see if this
    	-- is the case. Open can be made to depend on
    	-- the value of the index returned: if IsInSession
    	--  returns 0, the document is opened; if it returns
    	-- another value, a message is displayed asking the
    	--  user if he wants to override the version of the
    	--  document in memory.
    	-- Example:
    	-- Standard_Integer insession = A->IsInSession(aDoc);
    	-- if (insession > 0) {
    	-- cout << "document " << insession << " is already in session" << endl;
    	-- return 0;
    	-- }
  
    returns Integer from Standard;

    Open (me : mutable; path :     ExtendedString from TCollection;
                        aDoc : out Document from TDocStd)
    	---Purpose: Retrieves the document aDoc stored under the
    	-- name aName in the directory directory.
    	-- In order not to override a version of aDoc which
    	-- is already in memory, this method can be made
    	-- to depend on the value returned by IsInSession.
    returns ReaderStatus from PCDM;

    SaveAs (me : mutable; aDoc : Document from TDocStd;
                          path : ExtendedString from TCollection)
    	---Purpose:  Save the  active document  in the file  <name> in the
    	--           path <path> ; o verwrites  the file  if  it already exists.
    returns StoreStatus from PCDM;
    
    
    Save (me : mutable; aDoc : Document from TDocStd)
    	---Purpose: Save aDoc active document.  
        -- Exceptions:
    	--  Standard_NotImplemented if the document
    	-- was not retrieved in the applicative session by using Open. 
    returns StoreStatus from PCDM;
    
    SaveAs (me : mutable; aDoc : Document from TDocStd;
                          path : ExtendedString from TCollection;
    	    	    	  theStatusMessage:  out  ExtendedString from TCollection)
    	---Purpose:  Save the  active document  in the file  <name> in the
    	--           path <path>  .  overwrite  the file  if  it
    	--          already exist. 
    returns StoreStatus from PCDM;    
    
    Save (me : mutable; aDoc : Document from TDocStd; 
    	    	    	theStatusMessage:  out  ExtendedString from TCollection)
    	---Purpose: Save the document overwriting the previous file 
    returns StoreStatus from PCDM;
    
    --Exit (me)
    --  to quit the application. the applicative documents must be closed before.
    OnOpenTransaction   (me:mutable; theDoc: Document from TDocStd)
    is virtual protected;
    ---Purpose: Notification that is fired at each OpenTransaction event.

    OnCommitTransaction (me:mutable; theDoc: Document from TDocStd)
    is virtual protected;
    ---Purpose: Notification that is fired at each CommitTransaction event.

    OnAbortTransaction  (me:mutable; theDoc: Document from TDocStd)
    is virtual protected;
    ---Purpose: Notification that is fired at each AbortTransaction event.


fields

    myResources      : Manager from Resource;
    myIsDriverLoaded : Boolean from Standard;

friends
    class Document from TDocStd

end Application;
Commit	Line	Data
b311480e	1	-- Created on: 1999-06-30
	2	-- Created by: Denis PASCAL
	3	-- Copyright (c) 1999 Matra Datavision
	4	-- Copyright (c) 1999-2012 OPEN CASCADE SAS
	5	--
	6	-- The content of this file is subject to the Open CASCADE Technology Public
	7	-- License Version 6.5 (the "License"). You may not use the content of this file
	8	-- except in compliance with the License. Please obtain a copy of the License
	9	-- at http://www.opencascade.org and read it completely before using this file.
	10	--
	11	-- The Initial Developer of the Original Code is Open CASCADE S.A.S., having its
	12	-- main offices at: 1, place des Freres Montgolfier, 78280 Guyancourt, France.
	13	--
	14	-- The Original Code and all software distributed under the License is
	15	-- distributed on an "AS IS" basis, without warranty of any kind, and the
	16	-- Initial Developer hereby disclaims all such warranties, including without
	17	-- limitation, any warranties of merchantability, fitness for a particular
	18	-- purpose or non-infringement. Please see the License for the specific terms
	19	-- and conditions governing the rights and limitations under the License.
	20
7fd59977	21
	22
	23
	24	deferred class Application from TDocStd inherits Application from CDF
	25
	26	---Purpose:
	27	-- The abstract root class for all application classes.
	28	-- They are in charge of:
	29	-- - Creating documents
	30	-- - Storing documents and retrieving them
	31	-- - Initializing document views.
	32	-- To create a useful OCAF-based application, you
	33	-- derive a class from Application and implement
	34	-- the methods below. You will have to redefine the
	35	-- deferred (virtual) methods Formats,
	36	-- InitDocument, and Resources, and override others.
	37	-- The application is a container for a document,
	38	-- which in its turn is the container of the data
	39	-- framework made up of labels and attributes.
	40	-- Besides furnishing a container for documents,
	41	-- TDocStd_Application provides the following
	42	-- services for them:
	43	-- - Creation of new documents
	44	-- - Activation of documents in sessions of an application
	45	-- - Storage and retrieval of documents
	46	-- - Initialization of document views.
	47	-- Note:
	48	-- If a client needs detailed information concerning
	49	-- the events during the Open/Store operation, MessageDriver
	50	-- inherited from CDM_MessageDriver of the
	51	-- corresponding application has to be implemented.
	52	-- If the MessageDriver is not defined all messages
	53	-- will be (by default) directed to
	54	-- CDM_NullMessageDriver and will be lost.
	55
	56	uses Manager from Resource,
	57	Document from TDocStd,
	58	CString from Standard,
	59	ExtendedString from TCollection,
	60	SequenceOfExtendedString from TColStd,
15e8b082 M	61	ReaderStatus from PCDM,
15e8b082 M	62	StoreStatus from PCDM
7fd59977	63
	64	raises NoSuchObject from Standard
	65
	66	is
	67
	68	Initialize;
	69
	70	IsDriverLoaded (me)
	71	---Purpose: Check if meta data driver was successfully loaded
	72	-- by the application constructor
	73	returns Boolean from Standard;
	74
	75
	76
	77	Resources (me: mutable)
	78	---Purpose: create (if not done) a Manager using ResourcesName
	79	-- method.
	80	returns Manager from Resource
	81	is redefined virtual;
	82
	83	ResourcesName (me: mutable)
	84	---Purpose: Returns the name of the file containing the
	85	-- resources of this application.
	86	-- In a resource file, the application associates the schema name
	87	-- of the document with the storage and
	88	-- retrieval plug-ins that are to be loaded for each
	89	-- document. On retrieval, the application reads the
	90	-- schema name in the heading of the CSF file and
	91	-- loads the plug-in indicated in the resource file.
	92	-- This plug-in instantiates the actual driver for
	93	-- transient-persistent conversion.
	94	-- Your application can bring this process into play
	95	-- by defining a class which inherits
	96	-- CDF_Application and redefines the function
	97	-- which returns the appropriate resources file. At
	98	-- this point, the function Retrieve and the class
	99	-- CDF_Store can be called. This allows you to
	100	-- deal with storage and retrieval of - as well as
	101	-- copying and pasting - documents.
	102	-- To implement a class like this, several virtual
	103	-- functions should be redefined. In particular, you
	104	-- must redefine the abstract function Resources
	105	-- inherited from the superclass CDM_Application.
	106	returns CString from Standard
	107	is deferred;
	108
	109	NbDocuments (me)
	110	---Purpose: returns the number of documents handled by the current applicative session.
	111	returns Integer from Standard;
	112
	113	GetDocument (me; index : Integer from Standard; aDoc : in out Document from TDocStd);
	114	---Purpose: Constructs the new document aDoc.
	115	-- aDoc is identified by the index index which is
	116	-- any integer between 1 and n where n is the
	117	-- number of documents returned by NbDocument.
	118	-- Example
	119	-- Handle(TDocStd_Application)
	120	-- anApp;
	121	-- if (!CafTest::Find(A)) return 1;
	122	-- Handle(TDocStd) aDoc;
	123	-- Standard_Integer nbdoc = anApp->NbDocuments();
	124	-- for (Standard_Integer i = 1; i <= nbdoc; i++) {
	125	-- aApp->GetDocument(i,aDoc);
	126
127	Formats(me: mutable; Formats: out SequenceOfExtendedString from TColStd)
128	---Purpose:
129	-- Returns the format name Formats
130	-- representing the format supported for
131	-- application documents.
132	-- This virtual function is to be redefined for each
133	-- specific application.
134	is redefined deferred;
135
136	NewDocument (me : mutable; format : ExtendedString from TCollection; aDoc : out Document from TDocStd)
137	---Purpose: Constructs the empty new document aDoc.
138	-- This document will have the format format.
139	-- If InitDocument is redefined for a specific
140	-- application, the new document is handled by the
141	-- applicative session.
142	is virtual;
143
144	InitDocument (me; aDoc : Document from TDocStd)
145	---Purpose: Initialize the document aDoc for the applicative session.
146	-- This virtual function is called by NewDocument
147	-- and is to be redefined for each specific application.
148
149	is virtual;
150
151
152	---Purpose: Modified flag (different of disk version)
153	-- =============
154
155	--Modify(me: mutable); (see CDM_Document)
156
157
158	--IsModified(me) returns Boolean from Standard; (see CDM_Document)
159
160
161	---Purpose: to open/save a document
162	-- =======================
163
164	Close (me : mutable; aDoc : Document from TDocStd);
165	---Purpose: Close the given document. the document is not any more
166	-- handled by the applicative session.
167
168
169	IsInSession (me; path : ExtendedString from TCollection)
170	---Purpose: Returns an index for the document found in the
171	-- path path in this applicative session.
172	-- If the returned value is 0, the document is not
173	-- present in the applicative session.
174	-- This method can be used for the interactive part
175	-- of an application. For instance, on a call to
176	-- Open, the document to be opened may already
177	-- be in memory. IsInSession checks to see if this
178	-- is the case. Open can be made to depend on
179	-- the value of the index returned: if IsInSession
180	-- returns 0, the document is opened; if it returns
181	-- another value, a message is displayed asking the
182	-- user if he wants to override the version of the
183	-- document in memory.
184	-- Example:
185	-- Standard_Integer insession = A->IsInSession(aDoc);
186	-- if (insession > 0) {
187	-- cout << "document " << insession << " is already in session" << endl;
188	-- return 0;
189	-- }
190
191	returns Integer from Standard;
192
193	Open (me : mutable; path : ExtendedString from TCollection;
194	aDoc : out Document from TDocStd)
195	---Purpose: Retrieves the document aDoc stored under the
196	-- name aName in the directory directory.
197	-- In order not to override a version of aDoc which
198	-- is already in memory, this method can be made
199	-- to depend on the value returned by IsInSession.
15e8b082	200	returns ReaderStatus from PCDM;
7fd59977	201
	202	SaveAs (me : mutable; aDoc : Document from TDocStd;
	203	path : ExtendedString from TCollection)
	204	---Purpose: Save the active document in the file <name> in the
	205	-- path <path> ; o verwrites the file if it already exists.
15e8b082	206	returns StoreStatus from PCDM;
7fd59977	207
	208
	209	Save (me : mutable; aDoc : Document from TDocStd)
	210	---Purpose: Save aDoc active document.
	211	-- Exceptions:
	212	-- Standard_NotImplemented if the document
	213	-- was not retrieved in the applicative session by using Open.
15e8b082	214	returns StoreStatus from PCDM;
7fd59977	215
	216	SaveAs (me : mutable; aDoc : Document from TDocStd;
	217	path : ExtendedString from TCollection;
	218	theStatusMessage: out ExtendedString from TCollection)
	219	---Purpose: Save the active document in the file <name> in the
	220	-- path <path> . overwrite the file if it
	221	-- already exist.
15e8b082	222	returns StoreStatus from PCDM;
7fd59977	223
	224	Save (me : mutable; aDoc : Document from TDocStd;
	225	theStatusMessage: out ExtendedString from TCollection)
	226	---Purpose: Save the document overwriting the previous file
15e8b082	227	returns StoreStatus from PCDM;
7fd59977	228
	229	--Exit (me)
	230	-- to quit the application. the applicative documents must be closed before.
	231	OnOpenTransaction (me:mutable; theDoc: Document from TDocStd)
	232	is virtual protected;
	233	---Purpose: Notification that is fired at each OpenTransaction event.
	234
	235	OnCommitTransaction (me:mutable; theDoc: Document from TDocStd)
	236	is virtual protected;
	237	---Purpose: Notification that is fired at each CommitTransaction event.
	238
	239	OnAbortTransaction (me:mutable; theDoc: Document from TDocStd)
	240	is virtual protected;
	241	---Purpose: Notification that is fired at each AbortTransaction event.
	242
	243
	244	fields
	245
	246	myResources : Manager from Resource;
	247	myIsDriverLoaded : Boolean from Standard;
	248
	249	friends
	250	class Document from TDocStd
	251
	252	end Application;