CDocTemplate Classe

Uma classe base abstrata que define a funcionalidade básica para modelos de documentos.

Sintaxe

class CDocTemplate : public CCmdTarget

Membros

Construtores Protegidos

Métodos Públicos

Observações

Normalmente, cria um ou mais modelos de documentos na implementação da função da InitInstance sua aplicação. Um modelo de documento define as relações entre três tipos de classes:

• Uma classe document, que se deriva de CDocument.

• Uma classe de visualização, que apresenta dados da classe documento mencionada acima. Pode derivar esta classe a partir de CView, CScrollView, CFormView, ou CEditView. (Também pode usar CEditView diretamente.)

• Uma classe frame window, que contém a visualização. Para uma aplicação de interface de documento único (SDI), deriva-se esta classe a partir de CFrameWnd. Para uma aplicação de interface múltipla de documentos (MDI), deriva-se esta classe a partir de CMDIChildWnd. Se não precisares de personalizar o comportamento da janela de frame, podes usar CFrameWnd ou CMDIChildWnd usar diretamente sem deduzir a tua própria classe.

A sua candidatura tem um modelo de documento para cada tipo de documento que suporta. Por exemplo, se a sua aplicação suporta tanto folhas de cálculo como documentos de texto, a aplicação tem dois objetos modelo de documento. Cada modelo de documento é responsável por criar e gerir todos os documentos do seu tipo.

O modelo do documento armazena ponteiros para os CRuntimeClass objetos das classes de documento, vista e janela de frame. Estes CRuntimeClass objetos são especificados ao construir um modelo de documento.

O modelo do documento contém o ID dos recursos usados com o tipo de documento (como menu, ícone ou tabelas de aceleração). O modelo de documento também contém strings que contêm informações adicionais sobre o seu tipo de documento. Estas incluem o nome do tipo de documento (por exemplo, "Worksheet") e a extensão do ficheiro (por exemplo, ".xls"). Opcionalmente, pode conter outras strings usadas pela interface de utilizador da aplicação, pelo Gestor de Ficheiros do Windows e pelo suporte ao Object Linking and Embedding (OLE).

Se a sua aplicação for um contentor OLE e/ou servidor, o modelo do documento também define o ID do menu usado durante a ativação no local. Se a sua aplicação for um servidor OLE, o modelo do documento define o ID da barra de ferramentas e do menu usados durante a ativação no local. Especifica estes recursos OLE adicionais chamando SetContainerInfo e SetServerInfo.

Como CDocTemplate é uma classe abstrata, não podes usar a classe diretamente. Uma aplicação típica utiliza uma das duas CDocTemplateclasses derivadas em fornecidas pela Microsoft Foundation Class Library: CSingleDocTemplate, que implementa SDI, e CMultiDocTemplate, que implementa MDI. Consulte essas aulas para mais informações sobre o uso de modelos de documentos.

Se a sua aplicação requer um paradigma de interface de utilizador fundamentalmente diferente do SDI ou MDI, pode derivar a sua própria classe a partir CDocTemplatede .

Para mais informações sobre CDocTemplate, consulte Modelos de Documentos e o Processo de Criação de Documentos/Vistas.

Hierarquia de herança

CObject

CCmdTarget

CDocTemplate

Requerimentos

Cabeçalho:afxwin.h

CDocTemplate::AddDocument

Use esta função para adicionar um documento a um modelo.

virtual void AddDocument(CDocument* pDoc);

Parâmetros

pDoc
Um indicador para o documento a ser adicionado.

Observações

As classes CMultiDocTemplate derivadas e CSingleDocTemplate sobrepõem esta função. Se derivar a sua própria classe modelo de documento a partir de CDocTemplate, a sua classe derivada deve sobrepor-se a esta função.

CDocTemplate::CDocTemplate

Constrói um CDocTemplate objeto.

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

Parâmetros

nIDResource
Especifica o ID dos recursos usados com o tipo de documento. Isto pode incluir menus, ícones, tabela aceleradora e recursos de string.

O recurso de strings consiste em até sete substrings separadas pelo \n carácter (o \n carácter é necessário como marcador de posição se não for incluído um substring; no entanto, caracteres finais \n não são necessários); estas substrings descrevem o tipo de documento. Para informações sobre as subcordas, veja GetDocString. Este recurso string encontra-se no ficheiro de recursos da aplicação. Por exemplo:

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

Note que a cadeia começa com um \n carácter; isto porque a primeira subcadeia não é usada para aplicações MDI e, por isso, não está incluída. Pode editar esta cadeia usando o editor de cadeias; a sequência inteira aparece como uma única entrada no Editor de Cordas, e não como sete entradas separadas.

pDocClass
Aponta para o CRuntimeClass objeto da classe document. Esta classe é uma CDocumentclasse derivada em que define para representar os seus documentos.

pFrameClass
Aponta para o CRuntimeClass objeto da classe janela de moldura. Esta classe pode ser uma CFrameWndclasse derivada de -, ou pode ser CFrameWnd ela própria se quiseres comportamento padrão para a tua janela principal.

pViewClass
Aponta para o CRuntimeClass objeto da classe de visão. Esta classe é uma CViewclasse derivada em que defines para exibir os teus documentos.

Observações

Use esta função membro para construir um CDocTemplate objeto. Aloca dinamicamente um CDocTemplate objeto e passa-o a CWinApp::AddDocTemplate partir da InitInstance função membro da tua classe de aplicação.

CDocTemplate::CloseAllDocuments

Chame esta função de membro para encerrar todos os documentos abertos.

virtual void CloseAllDocuments(BOOL bEndSession);

Parâmetros

bEndSession
Não utilizado.

Observações

Esta função membro é normalmente usada como parte do comando File Exit. A implementação padrão desta função chama a CDocument::DeleteContents função membro para eliminar os dados do documento e depois fecha as janelas de frames para todas as vistas associadas ao documento.

Substitua esta função se quiser exigir que o utilizador realize um processamento especial de limpeza antes do encerramento do documento. Por exemplo, se o documento representa um registo numa base de dados, pode querer sobrepor esta função para fechar a base de dados.

CDocTemplate::CreateNewDocument

Chame esta função membro para criar um novo documento do tipo associado a este modelo de documento.

virtual CDocument* CreateNewDocument();

Valor de retorno

Um ponteiro para o documento recém-criado, ou NULL se ocorrer um erro.

CDocTemplate::CreateNewFrame

Cria uma nova janela de frame contendo um documento e uma vista.

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

Parâmetros

pDoc
O documento ao qual a nova janela de moldura deve referir-se. Pode ser NULL.

pOther
A janela de moldura em que a nova janela de moldura será baseada. Pode ser NULL.

Valor de retorno

Um ponteiro para a janela de frame recém-criada, ou NULL se ocorrer um erro.

Observações

CreateNewFrame utiliza os CRuntimeClass objetos passados ao construtor para criar uma nova janela de frame com uma vista e um documento anexados. Se o pDoc parâmetro for NULL, a estrutura gera uma TRACE mensagem.

O pOther parâmetro é usado para implementar o comando Window New. Fornece uma janela de moldura onde se pode modelar a nova janela de frame. A nova janela de moldura é normalmente criada invisível. Chame esta função para criar janelas de frames fora da implementação padrão do framework Ficheiro Novo e Ficheiro Aberto.

CDocTemplate::CreateOleFrame

Cria uma janela de moldura OLE.

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

Parâmetros

pParentWnd
Um apontador para a janela principal da moldura.

pDoc
Um ponteiro para o documento ao qual a nova janela de moldura OLE deve referir-se.

bCreateView
Determina se uma vista é criada juntamente com o enquadramento.

Valor de retorno

Um apontador para uma janela de frame, se bem-sucedido; caso contrário NULL.

Observações

Se bCreateView for zero, é criado um referencial vazio.

CDocTemplate::GetDocString

Recupera uma string associada ao tipo de documento.

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

Parâmetros

rString
Uma referência a um CString objeto que conterá a cadeia quando a função regressar.

index
Um índice da substring a ser recuperado da string que descreve o tipo de documento. Este parâmetro pode ter um dos seguintes valores:

• CDocTemplate::windowTitle Nome que aparece na barra de título da janela da aplicação (por exemplo, "Microsoft Excel"). Está presente apenas no modelo de documento para aplicações SDI.

• CDocTemplate::docName Root para o nome padrão do documento (por exemplo, "Sheet"). Esta raiz, mais um número, é usada como nome padrão de um novo documento deste tipo sempre que o utilizador escolhe o comando Novo no menu Ficheiro (por exemplo, "Sheet1" ou "Sheet2"). Se não for especificado, "Sem Título" é usado como padrão.

• CDocTemplate::fileNewName Nome deste tipo de documento. Se a aplicação suportar mais do que um tipo de documento, esta cadeia é exibida na caixa de diálogo Ficheiro Novo (por exemplo, "Folha de Trabalho"). Se não for especificado, o tipo de documento fica inacessível usando o comando Ficheiro Novo .

• CDocTemplate::filterName Descrição do tipo de documento e um filtro coringa correspondente a documentos deste tipo. Esta cadeia é exibida na lista suspensa List Files Of Type na caixa de diálogo File Open (por exemplo, "Worksheets (*.xls)"). Se não for especificado, o tipo de documento é inacessível usando o comando File Open .

• CDocTemplate::filterExt Extensão para documentos deste tipo (por exemplo, ".xls"). Se não for especificado, o tipo de documento é inacessível usando o comando File Open .

• CDocTemplate::regFileTypeId Identificador do tipo de documento a ser armazenado na base de dados de registos mantida pelo Windows. Esta cadeia é apenas para uso interno (por exemplo, "ExcelWorksheet"). Se não for especificado, o tipo de documento não pode ser registado no Gestor de Ficheiros do Windows.

• CDocTemplate::regFileTypeName Nome do tipo de documento a ser armazenado na base de dados de registo. Esta cadeia pode ser exibida nas caixas de diálogo das aplicações que acedem à base de dados de registo (por exemplo, "Microsoft Excel Worksheet").

Valor de retorno

Não nula se a subcadeia especificada for encontrada; caso contrário, 0.

Observações

Chame esta função para recuperar uma substring específica que descreva o tipo de documento. A cadeia que contém estas substrings é armazenada no modelo do documento e é derivada de uma string no ficheiro de recursos da aplicação. O framework chama esta função para obter as strings necessárias para a interface de utilizador da aplicação. Se especificou uma extensão de nome de ficheiro para os documentos da sua aplicação, o framework também chama esta função ao adicionar uma entrada à base de dados de registo do Windows; isto permite abrir documentos a partir do Gestor de Ficheiros do Windows.

Chame a esta função apenas se estiver a derivar a sua própria classe a partir de CDocTemplate.

CDocTemplate::GetFirstDocPosition

Recupera a posição do primeiro documento associado a este modelo.

virtual POSITION GetFirstDocPosition() const = 0;

Valor de retorno

Um POSITION valor que pode ser usado para iterar pela lista de documentos associados a este modelo de documento; ou NULL se a lista estiver vazia.

Observações

Use esta função para obter a posição do primeiro documento na lista de documentos associados a este modelo. Use o POSITION valor como argumento para CDocTemplate::GetNextDoc iterar pela lista de documentos associados ao modelo.

CSingleDocTemplate e CMultiDocTemplate ambos sobrepõem esta função puramente virtual. Qualquer classe de onde CDocTemplate derive também deve sobrepor esta função.

CDocTemplate::GetNextDoc

Recupera o elemento da lista identificado por rPos, depois define rPos para o POSITION valor da próxima entrada na lista.

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

Valor de retorno

Um apontador para o próximo documento na lista de documentos associados a este modelo.

Parâmetros

rPos
Uma referência a um POSITION valor devolvido por uma chamada anterior para GetFirstDocPosition ou GetNextDoc.

Observações

Se o elemento recuperado for o último na lista, então o novo valor de rPos é definido como NULL.

Pode usar GetNextDoc num ciclo de iteração direta se estabelecer a posição inicial com uma chamada para GetFirstDocPosition.

Deve garantir que o seu POSITION valor representa uma posição válida na lista. Se for inválido, então a versão Debug da Microsoft Foundation Class Library afirma.

CDocTemplate::InitialUpdateFrame

Inicializa a janela da moldura e, opcionalmente, torna-a visível.

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

Parâmetros

pFrame
A janela de moldura que precisa da atualização inicial.

pDoc
O documento ao qual a moldura está associada. Pode ser NULL.

bMakeVisible
Indica se o quadro deve tornar-se visível e ativo.

Observações

Chame IntitialUpdateFrame após criar um novo frame com CreateNewFrame. Chamar esta função faz com que as vistas nessa janela de frames recebam as suas OnInitialUpdate chamadas. Além disso, se anteriormente não havia uma vista ativa, a vista principal da janela do frame torna-se ativa; a vista principal é uma vista com um ID filho de AFX_IDW_PANE_FIRST. Finalmente, a janela de enquadramento é tornada visível se bMakeVisible for diferente de zero. Se bMakeVisible for zero, o foco atual e o estado visível da janela do frame permanecerão inalterados.

Não é necessário chamar esta função ao usar a implementação do framework de Ficheiro Novo e Ficheiro Aberto.

CDocTemplate::LoadTemplate

Carrega os recursos para uma dada CDocTemplate ou derivada classe.

virtual void LoadTemplate();

Observações

Esta função membro é chamada pelo framework para carregar os recursos de uma dada CDocTemplate ou derivada classe. Normalmente é chamado durante a construção, exceto quando o modelo está a ser construído globalmente. Nesse caso, a chamada LoadTemplate é adiada até CWinApp::AddDocTemplate ser chamada.

CDocTemplate::MatchDocType

Determina o grau de confiança na correspondência entre um tipo de documento e este modelo.

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

Parâmetros

lpszPathName
Nome do caminho do ficheiro cujo tipo deve ser determinado.

rpDocMatch
Apontar para um documento atribuído ao documento correspondente, se o ficheiro especificado por lpszPathName já estiver aberto.

Valor de retorno

Um valor da Confidence enumeração, que é definido da seguinte forma:

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

Observações

Use esta função para determinar o tipo de modelo de documento a usar para abrir um ficheiro. Se a sua aplicação suportar múltiplos tipos de ficheiros, por exemplo, pode usar esta função para determinar qual dos modelos de documentos disponíveis é adequado para um dado ficheiro, chamando MatchDocType cada modelo por sua vez e escolhendo um modelo de acordo com o valor de confiança devolvido.

Se o ficheiro especificado por lpszPathName já estiver aberto, esta função devolve CDocTemplate::yesAlreadyOpen e copia o objeto do CDocument ficheiro para o objeto em rpDocMatch.

Se o ficheiro não estiver aberto mas a extensão em lpszPathName corresponder à extensão especificada por CDocTemplate::filterExt, esta função devolve CDocTemplate::yesAttemptNative e define rpDocMatch como NULL. Para mais informações sobre CDocTemplate::filterExt, veja CDocTemplate::GetDocString.

Se nenhum dos casos for verdadeiro, a função devolve CDocTemplate::yesAttemptForeign.

A implementação padrão não retorna CDocTemplate::maybeAttemptForeign nem CDocTemplate::maybeAttemptNative. Substitua esta função para implementar lógica de correspondência de tipos adequada à sua aplicação, talvez usando estes dois valores da Confidence enumeração.

CDocTemplate::OpenDocumentFile

Abre um ficheiro especificado por um caminho.

virtual CDocument* OpenDocumentFile(LPCTSTR lpszPathName) = 0;

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

Parâmetros

lpszPathName
[dentro] Apontador para o caminho do ficheiro que contém o documento a ser aberto.

bAddToMRU
[dentro] TRUE indica que o documento é um dos ficheiros mais recentes; FALSE indica que o documento não é um dos ficheiros mais recentes.

Valor de retorno

Um apontador para o documento cujo ficheiro é nomeado por lpszPathName; NULL se não for bem-sucedido.

Observações

Abre o ficheiro cujo caminho é especificado por lpszPathName. Se lpszPathName for NULL, é criado um novo ficheiro que contém um documento do tipo associado a este modelo.

CDocTemplate::RemoveDocument

Remove o documento apontado por pDoc da lista de documentos associados a este modelo.

virtual void RemoveDocument(CDocument* pDoc);

Parâmetros

pDoc
Apontar para o documento a remover.

Observações

As classes CMultiDocTemplate derivadas e CSingleDocTemplate sobrepõem esta função. Se derivar a sua própria classe modelo de documento a partir de CDocTemplate, a sua classe derivada deve sobrepor-se a esta função.

CDocTemplate::SaveAllModified

Guarda todos os documentos que foram modificados.

virtual BOOL SaveAllModified();

Valor de retorno

Não nulo se for bem-sucedido; caso contrário, 0.

CDocTemplate::SetContainerInfo

Determina os recursos para contentores OLE ao editar um item OLE no local.

void SetContainerInfo(UINT nIDOleInPlaceContainer);

Parâmetros

nIDOleInPlaceContainer
O ID dos recursos usados quando um objeto embutido é ativado.

Observações

Chame esta função para definir os recursos a serem usados quando um objeto OLE estiver ativado no local. Estes recursos podem incluir menus e tabelas aceleradoras. Esta função é normalmente chamada na CWinApp::InitInstance função da sua aplicação.

O menu associado a nIDOleInPlaceContainer contém separadores que permitem que o menu do item ativado no local se funda com o menu da aplicação do contentor. Para mais informações sobre a fusão de menus de servidores e contentores, consulte o artigo Menus and Resources (OLE).

CDocTemplate::SetDefaultTitle

Chame esta função para carregar o título padrão do documento e mostrá-lo na barra de título do documento.

virtual void SetDefaultTitle(CDocument* pDocument) = 0;

Parâmetros

pDocument
Apontar para o documento cujo título deve ser definido.

Observações

Para informações sobre o título padrão, veja a descrição de CDocTemplate::docName em CDocTemplate::GetDocString.

CDocTemplate::SetServerInfo

Determina os recursos e classes quando o documento do servidor é incorporado ou editado no local.

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

Parâmetros

nIDOleEmbedding
O ID dos recursos usados quando um objeto embutido é aberto numa janela separada.

nIDOleInPlaceServer
O ID dos recursos usados quando um objeto embutido é ativado no local.

pOleFrameClass
Apontador para uma CRuntimeClass estrutura que contém informação de classe para o objeto janela de quadro criado quando ocorre ativação no local.

pOleViewClass
Apontador para uma CRuntimeClass estrutura contendo informação de classe para o objeto de visualização criado quando ocorre ativação no local.

Observações

Chame esta função membro para identificar recursos que serão usados pela aplicação servidor quando o utilizador solicitar a ativação de um objeto incorporado. Estes recursos consistem em menus e tabelas aceleradoras. Esta função é normalmente chamada na InitInstance sua aplicação.

O menu associado a nIDOleInPlaceServer contém separadores que permitem que o menu do servidor se funda com o menu do contentor. Para mais informações sobre a fusão de menus de servidores e contentores, consulte o artigo Menus and Resources (OLE).

CDocTemplate::CreatePreviewFrame

Cria um frame filho usado para o Rich Preview.

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

Parâmetros

pParentWnd
Um ponteiro para uma janela pai (normalmente fornecida pela Shell).

pDoc
Um apontador para um objeto do documento, cujo conteúdo será pré-visualizado.

Valor de retorno

Um ponteiro válido para um CFrameWnd objeto, ou NULL se a criação falhar.

Observações

CDocTemplate::SetPreviewInfo

Configura o gestor de pré-visualização fora do processo.

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

Parâmetros

nIDPreviewFrame
Especifica um ID de recurso do frame de pré-visualização.

pPreviewFrameClass
Especifica um ponteiro para uma estrutura de informação de classe em tempo de execução do quadro de pré-visualização.

pPreviewViewClass
Especifica um ponteiro para uma estrutura de informação de classe em tempo de execução da vista de pré-visualização.

Observações

Consulte também

CCmdTarget Classe
Gráfico de Hierarquia
CSingleDocTemplate Classe
CMultiDocTemplate Classe
CDocument Classe
CView Classe
CScrollView Classe
CEditView Classe
CFormView Classe
CFrameWnd Classe
CMDIChildWnd Classe