Classe CDocTemplate

Classe di base astratta che definisce le funzionalità di base per i modelli di documenti.

Sintassi

class CDocTemplate : public CCmdTarget

Membri

Costruttori protetti

Nome Descrizione
CDocTemplate::CDocTemplate Costruisce un oggetto CDocTemplate.

Metodi pubblici

Nome Descrizione
CDocTemplate::AddDocument Aggiunge un documento a un modello.
CDocTemplate::CloseAllDocuments Chiude tutti i documenti associati a questo modello.
CDocTemplate::CreateNewDocument Crea un nuovo documento.
CDocTemplate::CreateNewFrame Crea una nuova finestra cornice contenente un documento e una visualizzazione.
CDocTemplate::CreateOleFrame Crea una finestra cornice abilitata per OLE.
CDocTemplate::CreatePreviewFrame Crea un frame figlio utilizzato per Rich Preview.
CDocTemplate::GetDocString Recupera una stringa associata al tipo di documento.
CDocTemplate::GetFirstDocPosition Recupera la posizione del primo documento associato a questo modello.
CDocTemplate::GetNextDoc Recupera un documento e la posizione della successiva.
CDocTemplate::InitialUpdateFrame Inizializza la finestra cornice e, facoltativamente, la rende visibile.
CDocTemplate::LoadTemplate Carica le risorse per una determinata CDocTemplate classe derivata o .
CDocTemplate::MatchDocType Determina il grado di confidenza nella corrispondenza tra un tipo di documento e questo modello.
CDocTemplate::OpenDocumentFile Apre un file specificato da un percorso.
CDocTemplate::RemoveDocument Rimuove un documento da un modello.
CDocTemplate::SaveAllModified Salva tutti i documenti associati a questo modello, che sono stati modificati.
CDocTemplate::SetContainerInfo Determina le risorse per i contenitori OLE durante la modifica di un elemento OLE sul posto.
CDocTemplate::SetDefaultTitle Visualizza il titolo predefinito nella barra del titolo della finestra del documento.
CDocTemplate::SetPreviewInfo Configura il gestore dell'anteprima del processo.
CDocTemplate::SetServerInfo Determina le risorse e le classi quando il documento del server è incorporato o modificato sul posto.

Osservazioni:

In genere si creano uno o più modelli di documento nell'implementazione della funzione dell'applicazione InitInstance . Un modello di documento definisce le relazioni tra tre tipi di classi:

  • Classe di documento, derivata da CDocument.

  • Classe di visualizzazione, che visualizza i dati della classe documento elencata in precedenza. È possibile derivare questa classe da CView, CScrollView, CFormViewo CEditView. È anche possibile usare CEditView direttamente.

  • Classe della finestra cornice che contiene la visualizzazione. Per una singola applicazione SDI (Document Interface), si deriva questa classe da CFrameWnd. Per un'applicazione MDI (Multiple Document Interface), derivare questa classe da CMDIChildWnd. Se non è necessario personalizzare il comportamento della finestra cornice, è possibile usare CFrameWnd o CMDIChildWnd direttamente senza derivare la propria classe.

L'applicazione ha un modello di documento per ogni tipo di documento supportato. Ad esempio, se l'applicazione supporta sia fogli di calcolo che documenti di testo, l'applicazione dispone di due oggetti modello di documento. Ogni modello di documento è responsabile della creazione e della gestione di tutti i documenti del tipo.

Il modello di documento archivia i puntatori agli oggetti per le CRuntimeClass classi di finestre di documento, visualizzazione e cornice. Questi CRuntimeClass oggetti vengono specificati durante la costruzione di un modello di documento.

Il modello di documento contiene l'ID delle risorse usate con il tipo di documento , ad esempio menu, icona o risorse della tabella di scelta rapida. Il modello di documento contiene anche stringhe contenenti informazioni aggiuntive sul tipo di documento. Questi includono il nome del tipo di documento (ad esempio, "Foglio di lavoro") e l'estensione di file (ad esempio, ".xls"). Facoltativamente, può contenere altre stringhe usate dall'interfaccia utente dell'applicazione, gestione file di Windows e supporto per il collegamento e l'incorporamento di oggetti (OLE).

Se l'applicazione è un contenitore OLE e/o un server, il modello di documento definisce anche l'ID del menu usato durante l'attivazione sul posto. Se l'applicazione è un server OLE, il modello di documento definisce l'ID della barra degli strumenti e il menu usati durante l'attivazione sul posto. È possibile specificare queste risorse OLE aggiuntive chiamando SetContainerInfo e SetServerInfo.

Poiché CDocTemplate è una classe astratta, non è possibile usare direttamente la classe . Un'applicazione tipica usa una delle due CDocTemplateclassi derivate da Microsoft Foundation Class Library: CSingleDocTemplate, che implementa SDI e CMultiDocTemplate, che implementa MDI. Per altre informazioni sull'uso dei modelli di documento, vedere queste classi.

Se l'applicazione richiede un paradigma dell'interfaccia utente fondamentalmente diverso da SDI o MDI, è possibile derivare la propria classe da CDocTemplate.

Per altre informazioni su CDocTemplate, vedere Modelli di documento e processo di creazione di documenti/visualizzazioni.

Gerarchia di ereditarietà

CObject

CCmdTarget

CDocTemplate

Requisiti

Intestazione:afxwin.h

CDocTemplate::AddDocument

Usare questa funzione per aggiungere un documento a un modello.

virtual void AddDocument(CDocument* pDoc);

Parametri

pDoc
Puntatore al documento da aggiungere.

Osservazioni:

Classi derivate CMultiDocTemplate ed CSingleDocTemplate eseguire l'override di questa funzione. Se si deriva la classe document-template personalizzata da CDocTemplate, la classe derivata deve eseguire l'override di questa funzione.

CDocTemplate::CDocTemplate

Costruisce un oggetto CDocTemplate.

CDocTemplate (
    UINT nIDResource,
    CRuntimeClass* pDocClass,
    CRuntimeClass* pFrameClass,
    CRuntimeClass* pViewClass);

Parametri

nIDResource
Specifica l'ID delle risorse utilizzate con il tipo di documento. Ciò può includere risorse di menu, icona, tabella dell'acceleratore e stringa.

La risorsa stringa è costituita da un massimo di sette sottostringhe separate dal \n carattere (il \n carattere è necessario come segnaposto se non è inclusa una sottostringa; tuttavia, i caratteri finali \n non sono necessari); queste sottostringhe descrivono il tipo di documento. Per informazioni sulle sottostringhe, vedere GetDocString. Questa risorsa stringa si trova nel file di risorse dell'applicazione. Ad esempio:

// MYCALC.RC
STRINGTABLE PRELOAD DISCARDABLE
BEGIN
  IDR_SHEETTYPE "\nSheet\nWorksheet\nWorksheets (*.myc)\n.myc\n MyCalcSheet\nMyCalc Worksheet"
END

Si noti che la stringa inizia con un \n carattere, perché la prima sottostringa non viene usata per le applicazioni MDI e quindi non è inclusa. È possibile modificare questa stringa usando l'editor di stringhe; L'intera stringa viene visualizzata come una singola voce nell'editor di stringhe, non come sette voci separate.

pDocClass
Punta all'oggetto CRuntimeClass della classe document. Questa classe è una CDocumentclasse derivata da che si definisce per rappresentare i documenti.

pFrameClass
Punta all'oggetto CRuntimeClass della classe finestra cornice. Questa classe può essere una CFrameWndclasse derivata da o può essere CFrameWnd stessa se si desidera un comportamento predefinito per la finestra cornice principale.

pViewClass
Punta all'oggetto CRuntimeClass della classe di visualizzazione. Questa classe è una CViewclasse derivata da che si definisce per visualizzare i documenti.

Osservazioni:

Utilizzare questa funzione membro per costruire un CDocTemplate oggetto . Allocare dinamicamente un CDocTemplate oggetto e passarlo dalla CWinApp::AddDocTemplateInitInstance funzione membro della classe dell'applicazione.

CDocTemplate::CloseAllDocuments

Chiamare questa funzione membro per chiudere tutti i documenti aperti.

virtual void CloseAllDocuments(BOOL bEndSession);

Parametri

bEndSession
Non utilizzato.

Osservazioni:

Questa funzione membro viene in genere usata come parte del comando File Exit. L'implementazione predefinita di questa funzione chiama la CDocument::DeleteContents funzione membro per eliminare i dati del documento e quindi chiude le finestre cornice per tutte le visualizzazioni associate al documento.

Eseguire l'override di questa funzione se si desidera richiedere all'utente di eseguire un'elaborazione di pulizia speciale prima della chiusura del documento. Ad esempio, se il documento rappresenta un record in un database, è possibile eseguire l'override di questa funzione per chiudere il database.

CDocTemplate::CreateNewDocument

Chiamare questa funzione membro per creare un nuovo documento del tipo associato a questo modello di documento.

virtual CDocument* CreateNewDocument();

Valore restituito

Puntatore al documento appena creato o NULL se si verifica un errore.

CDocTemplate::CreateNewFrame

Crea una nuova finestra cornice contenente un documento e una visualizzazione.

virtual CFrameWnd* CreateNewFrame(
    CDocument* pDoc,
    CFrameWnd* pOther);

Parametri

pDoc
Documento a cui fare riferimento la nuova finestra cornice. Può essere NULL.

pOther
Finestra cornice in cui deve essere basata la nuova finestra cornice. Può essere NULL.

Valore restituito

Puntatore alla finestra cornice appena creata o NULL se si verifica un errore.

Osservazioni:

CreateNewFrame utilizza gli CRuntimeClass oggetti passati al costruttore per creare una nuova finestra cornice con una visualizzazione e un documento allegato. Se il pDoc parametro è NULL, il framework restituisce un TRACE messaggio.

Il pOther parametro viene usato per implementare il comando Window New. Fornisce una finestra cornice in cui modellare la nuova finestra cornice. La nuova finestra cornice viene in genere creata invisibile. Chiamare questa funzione per creare finestre cornice al di fuori dell'implementazione del framework standard di File Nuovo e Apri file.

CDocTemplate::CreateOleFrame

Crea una finestra cornice OLE.

CFrameWnd* CreateOleFrame(
    CWnd* pParentWnd,
    CDocument* pDoc,
    BOOL bCreateView);

Parametri

pParentWnd
Puntatore alla finestra padre della cornice.

pDoc
Puntatore al documento a cui deve fare riferimento la nuova finestra cornice OLE.

bCreateView
Determina se una visualizzazione viene creata insieme al frame.

Valore restituito

Puntatore a una finestra cornice in caso di esito positivo; in caso contrario NULL, .

Osservazioni:

Se bCreateView è zero, viene creato un frame vuoto.

CDocTemplate::GetDocString

Recupera una stringa associata al tipo di documento.

virtual BOOL GetDocString(
    CString& rString,
    enum DocStringIndex index) const;

Parametri

rString
Riferimento a un CString oggetto che conterrà la stringa quando la funzione restituisce.

index
Indice della sottostringa recuperata dalla stringa che descrive il tipo di documento. Per il parametro è possibile specificare uno dei valori riportati di seguito:

  • CDocTemplate::windowTitle Nome visualizzato nella barra del titolo della finestra dell'applicazione, ad esempio "Microsoft Excel". Presente solo nel modello di documento per le applicazioni SDI.

  • CDocTemplate::docName Radice per il nome del documento predefinito (ad esempio, "Foglio"). Questa radice, più un numero, viene usata per il nome predefinito di un nuovo documento di questo tipo ogni volta che l'utente sceglie il comando Nuovo dal menu File (ad esempio, "Sheet1" o "Sheet2"). Se non specificato, viene usato "Senza titolo" come impostazione predefinita.

  • CDocTemplate::fileNewName Nome del tipo di documento. Se l'applicazione supporta più tipi di documento, questa stringa viene visualizzata nella finestra di dialogo Nuovo file , ad esempio "Foglio di lavoro". Se non specificato, il tipo di documento non è accessibile usando il comando File Nuovo .

  • CDocTemplate::filterName Descrizione del tipo di documento e di un filtro con caratteri jolly corrispondenti ai documenti di questo tipo. Questa stringa viene visualizzata nell'elenco a discesa Elenco file di tipo nella finestra di dialogo Apri file , ad esempio "Fogli di lavoro (*.xls)"). Se non specificato, il tipo di documento non è accessibile usando il comando Apri file.

  • CDocTemplate::filterExt Estensione per i documenti di questo tipo (ad esempio, ".xls"). Se non specificato, il tipo di documento non è accessibile usando il comando Apri file.

  • CDocTemplate::regFileTypeId Identificatore del tipo di documento da archiviare nel database di registrazione gestito da Windows. Questa stringa è solo per uso interno (ad esempio, "ExcelWorksheet"). Se non specificato, il tipo di documento non può essere registrato con Gestione file di Windows.

  • CDocTemplate::regFileTypeName Nome del tipo di documento da archiviare nel database di registrazione. Questa stringa può essere visualizzata nelle finestre di dialogo delle applicazioni che accedono al database di registrazione, ad esempio "Foglio di lavoro di Microsoft Excel".

Valore restituito

Diverso da zero se è stata trovata la sottostringa specificata; in caso contrario, 0.

Osservazioni:

Chiamare questa funzione per recuperare una sottostringa specifica che descrive il tipo di documento. La stringa contenente queste sottostringhe viene archiviata nel modello di documento ed è derivata da una stringa nel file di risorse per l'applicazione. Il framework chiama questa funzione per ottenere le stringhe necessarie per l'interfaccia utente dell'applicazione. Se è stata specificata un'estensione del nome file per i documenti dell'applicazione, il framework chiama anche questa funzione quando si aggiunge una voce al database di registrazione di Windows; in questo modo i documenti possono essere aperti da Gestione file di Windows.

Chiamare questa funzione solo se si deriva la propria classe da CDocTemplate.

CDocTemplate::GetFirstDocPosition

Recupera la posizione del primo documento associato a questo modello.

virtual POSITION GetFirstDocPosition() const = 0;

Valore restituito

Valore POSITION che può essere utilizzato per scorrere l'elenco di documenti associati a questo modello di documento oppure NULL se l'elenco è vuoto.

Osservazioni:

Utilizzare questa funzione per ottenere la posizione del primo documento nell'elenco di documenti associati a questo modello. Usare il POSITION valore come argomento per CDocTemplate::GetNextDoc scorrere l'elenco di documenti associati al modello.

CSingleDocTemplate ed entrambi CMultiDocTemplate eseguono l'override di questa funzione virtuale pura. Qualsiasi classe derivata da CDocTemplate deve anche eseguire l'override di questa funzione.

CDocTemplate::GetNextDoc

Recupera l'elemento elenco identificato da rPos, quindi imposta rPos sul POSITION valore della voce successiva nell'elenco.

virtual CDocument* GetNextDoc(POSITION& rPos) const = 0;

Valore restituito

Puntatore al documento successivo nell'elenco di documenti associati a questo modello.

Parametri

rPos
Riferimento a un POSITION valore restituito da una chiamata precedente a GetFirstDocPosition o GetNextDoc.

Osservazioni:

Se l'elemento recuperato è l'ultimo nell'elenco, il nuovo valore di rPos viene impostato su NULL.

È possibile usare GetNextDoc in un ciclo di iterazione in avanti se si stabilisce la posizione iniziale con una chiamata a GetFirstDocPosition.

È necessario assicurarsi che il POSITION valore rappresenti una posizione valida nell'elenco. Se non è valido, la versione debug della libreria di classi Microsoft Foundation asserisce.

CDocTemplate::InitialUpdateFrame

Inizializza la finestra cornice e, facoltativamente, la rende visibile.

virtual void InitialUpdateFrame(
    CFrameWnd* pFrame,
    CDocument* pDoc,
    BOOL bMakeVisible = TRUE);

Parametri

pFrame
Finestra cornice che richiede l'aggiornamento iniziale.

pDoc
Documento a cui è associato il frame. Può essere NULL.

bMakeVisible
Indica se il frame deve diventare visibile e attivo.

Osservazioni:

Chiamare IntitialUpdateFrame dopo aver creato un nuovo frame con CreateNewFrame. La chiamata a questa funzione fa sì che le visualizzazioni nella finestra cornice ricevano le chiamate OnInitialUpdate . Inoltre, se in precedenza non era presente una visualizzazione attiva, la visualizzazione principale della finestra cornice viene resa attiva; la visualizzazione primaria è una visualizzazione con un ID figlio di AFX_IDW_PANE_FIRST. Infine, la finestra cornice viene resa visibile se bMakeVisible è diverso da zero. Se bMakeVisible è zero, lo stato attivo corrente e lo stato visibile della finestra cornice rimarranno invariati.

Non è necessario chiamare questa funzione quando si usa l'implementazione del framework di File New e File Open.

CDocTemplate::LoadTemplate

Carica le risorse per una determinata CDocTemplate classe derivata o .

virtual void LoadTemplate();

Osservazioni:

Questa funzione membro viene chiamata dal framework per caricare le risorse per una determinata CDocTemplate classe derivata o . In genere viene chiamato durante la costruzione, tranne quando il modello viene costruito a livello globale. In tal caso, la chiamata a LoadTemplate viene ritardata fino a quando CWinApp::AddDocTemplate non viene chiamata.

CDocTemplate::MatchDocType

Determina il grado di confidenza nella corrispondenza tra un tipo di documento e questo modello.

virtual Confidence MatchDocType(
    LPCTSTR lpszPathName,
    CDocument*& rpDocMatch);

Parametri

lpszPathName
Percorso del file il cui tipo deve essere determinato.

rpDocMatch
Puntatore a un documento assegnato al documento corrispondente, se il file specificato da lpszPathName è già aperto.

Valore restituito

Valore dell'enumerazione Confidence , definito come segue:

enum Confidence
    {
    noAttempt,
    maybeAttemptForeign,
    maybeAttemptNative,
    yesAttemptForeign,
    yesAttemptNative,
    yesAlreadyOpen
    };

Osservazioni:

Utilizzare questa funzione per determinare il tipo di modello di documento da usare per l'apertura di un file. Se l'applicazione supporta più tipi di file, ad esempio, è possibile usare questa funzione per determinare quale dei modelli di documento disponibili è appropriato per un determinato file chiamando MatchDocType a sua volta per ogni modello e scegliendo un modello in base al valore di attendibilità restituito.

Se il file specificato da lpszPathName è già aperto, questa funzione restituisce CDocTemplate::yesAlreadyOpen e copia l'oggetto del CDocument file nell'oggetto in rpDocMatch.

Se il file non è aperto ma l'estensione in lpszPathName corrisponde all'estensione specificata da CDocTemplate::filterExt, questa funzione restituisce CDocTemplate::yesAttemptNative e imposta rpDocMatch su NULL. Per altre informazioni su CDocTemplate::filterExt, vedere CDocTemplate::GetDocString.

Se nessuna delle maiuscole e minuscole è true, la funzione restituisce CDocTemplate::yesAttemptForeign.

L'implementazione predefinita non restituisce CDocTemplate::maybeAttemptForeign o CDocTemplate::maybeAttemptNative. Eseguire l'override di questa funzione per implementare la logica di corrispondenza dei tipi appropriata per l'applicazione, ad esempio usando questi due valori dell'enumerazione Confidence .

CDocTemplate::OpenDocumentFile

Apre un file specificato da un percorso.

virtual CDocument* OpenDocumentFile(LPCTSTR lpszPathName) = 0;

virtual CDocument* OpenDocumentFile(
    LPCTSTR lpszPathName,
    BOOL bAddToMRU) = 0;

Parametri

lpszPathName
[in] Puntatore al percorso del file che contiene il documento da aprire.

bAddToMRU
[in] TRUE indica che il documento è uno dei file più recenti; FALSE indica che il documento non è uno dei file più recenti.

Valore restituito

Puntatore al documento il cui file è denominato da lpszPathName; NULL in caso di esito negativo.

Osservazioni:

Apre il file il cui percorso è specificato da lpszPathName. Se lpszPathName è NULL, viene creato un nuovo file contenente un documento del tipo associato a questo modello.

CDocTemplate::RemoveDocument

Rimuove il documento a pDoc cui punta dall'elenco di documenti associati a questo modello.

virtual void RemoveDocument(CDocument* pDoc);

Parametri

pDoc
Puntatore al documento da rimuovere.

Osservazioni:

Classi derivate CMultiDocTemplate ed CSingleDocTemplate eseguire l'override di questa funzione. Se si deriva la classe document-template personalizzata da CDocTemplate, la classe derivata deve eseguire l'override di questa funzione.

CDocTemplate::SaveAllModified

Salva tutti i documenti modificati.

virtual BOOL SaveAllModified();

Valore restituito

Diverso da zero se ha esito positivo; in caso contrario, 0.

CDocTemplate::SetContainerInfo

Determina le risorse per i contenitori OLE durante la modifica di un elemento OLE sul posto.

void SetContainerInfo(UINT nIDOleInPlaceContainer);

Parametri

nIDOleInPlaceContainer
ID delle risorse utilizzate quando viene attivato un oggetto incorporato.

Osservazioni:

Chiamare questa funzione per impostare le risorse da utilizzare quando un oggetto OLE è attivato sul posto. Queste risorse possono includere menu e tabelle di tasti di scelta rapida. Questa funzione viene in genere chiamata nella CWinApp::InitInstance funzione dell'applicazione.

Il menu associato a nIDOleInPlaceContainer contiene separatori che consentono al menu della voce sul posto attivata di unire il menu dell'applicazione contenitore. Per altre informazioni sull'unione di menu server e contenitori, vedere l'articolo Menu e risorse (OLE).

CDocTemplate::SetDefaultTitle

Chiamare questa funzione per caricare il titolo predefinito del documento e visualizzarlo nella barra del titolo del documento.

virtual void SetDefaultTitle(CDocument* pDocument) = 0;

Parametri

pDocument
Puntatore al documento il cui titolo deve essere impostato.

Osservazioni:

Per informazioni sul titolo predefinito, vedere la descrizione di CDocTemplate::docName in CDocTemplate::GetDocString.

CDocTemplate::SetServerInfo

Determina le risorse e le classi quando il documento del server è incorporato o modificato sul posto.

void SetServerInfo(
    UINT nIDOleEmbedding,
    UINT nIDOleInPlaceServer = 0,
    CRuntimeClass* pOleFrameClass = NULL,
    CRuntimeClass* pOleViewClass = NULL);

Parametri

nIDOleEmbedding
ID delle risorse utilizzate quando un oggetto incorporato viene aperto in una finestra separata.

nIDOleInPlaceServer
ID delle risorse utilizzate quando un oggetto incorporato viene attivato sul posto.

pOleFrameClass
Puntatore a una CRuntimeClass struttura contenente informazioni sulla classe per l'oggetto finestra cornice creato quando si verifica l'attivazione sul posto.

pOleViewClass
Puntatore a una CRuntimeClass struttura contenente informazioni sulla classe per l'oggetto view creato quando si verifica l'attivazione sul posto.

Osservazioni:

Chiamare questa funzione membro per identificare le risorse che verranno usate dall'applicazione server quando l'utente richiede l'attivazione di un oggetto incorporato. Queste risorse sono costituite da menu e tabelle di scelta rapida. Questa funzione viene in genere chiamata nell'oggetto InitInstance dell'applicazione.

Il menu associato a nIDOleInPlaceServer contiene separatori che consentono al menu del server di unire il menu del contenitore. Per altre informazioni sull'unione di menu server e contenitori, vedere l'articolo Menu e risorse (OLE).

CDocTemplate::CreatePreviewFrame

Crea un frame figlio utilizzato per Rich Preview.

CFrameWnd* CreatePreviewFrame(
    CWnd* pParentWnd,
    CDocument* pDoc);

Parametri

pParentWnd
Puntatore a una finestra padre (in genere fornita dalla shell).

pDoc
Puntatore a un oggetto documento, il cui contenuto verrà visualizzato in anteprima.

Valore restituito

Puntatore valido a un CFrameWnd oggetto o NULL se la creazione ha esito negativo.

Osservazioni:

CDocTemplate::SetPreviewInfo

Configura il gestore di anteprima out-of-process.

void SetPreviewInfo(
    UINT nIDPreviewFrame,
    CRuntimeClass* pPreviewFrameClass = NULL,
    CRuntimeClass* pPreviewViewClass = NULL);

Parametri

nIDPreviewFrame
Specifica un ID risorsa del frame di anteprima.

pPreviewFrameClass
Specifica un puntatore a una struttura di informazioni della classe di runtime del frame di anteprima.

pPreviewViewClass
Specifica un puntatore a una struttura di informazioni sulla classe di runtime della visualizzazione di anteprima.

Osservazioni:

Vedi anche

CCmdTarget Classe
Grafico della gerarchia
CSingleDocTemplate Classe
CMultiDocTemplate Classe
CDocument Classe
CView Classe
CScrollView Classe
CEditView Classe
CFormView Classe
CFrameWnd Classe
CMDIChildWnd Classe