Classe CDocTemplate

  • Artigo

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

Sintaxe

class CDocTemplate : public CCmdTarget

Membros

Construtores Protegidos

Nome Descrição
CDocTemplate::CDocTemplate Constrói um objeto CDocTemplate.

Métodos públicos

Nome Descrição
CDocTemplate::AddDocument Adiciona um documento a um modelo.
CDocTemplate::CloseAllDocuments Fecha todos os documentos associados a este modelo.
CDocTemplate::CreateNewDocument Cria um documento.
CDocTemplate::CreateNewFrame Cria uma janela de quadro contendo um documento e uma exibição.
CDocTemplate::CreateOleFrame Cria uma janela de quadro habilitada para OLE.
CDocTemplate::CreatePreviewFrame Cria um quadro filho usado para Visualização Avançada.
CDocTemplate::GetDocString Recupera uma cadeia de caracteres associada ao tipo de documento.
CDocTemplate::GetFirstDocPosition Recupera a posição do primeiro documento associado a este modelo.
CDocTemplate::GetNextDoc Recupera um documento e a posição do próximo.
CDocTemplate::InitialUpdateFrame Inicializa a janela de quadro e, opcionalmente, a torna visível.
CDocTemplate::LoadTemplate Carrega os recursos de uma determinada CDocTemplate ou classe derivada.
CDocTemplate::MatchDocType Determina o grau de confiança na correspondência entre um tipo de documento e este modelo.
CDocTemplate::OpenDocumentFile Abre um arquivo especificado por um nome de caminho.
CDocTemplate::RemoveDocument Remove um documento de um modelo.
CDocTemplate::SaveAllModified Salva todos os documentos associados a este modelo, que foram modificados.
CDocTemplate::SetContainerInfo Determina os recursos para contêineres OLE ao editar um item OLE no local.
CDocTemplate::SetDefaultTitle Exibe o título padrão na barra de título da janela do documento.
CDocTemplate::SetPreviewInfo Configura o manipulador de visualização fora do processo.
CDocTemplate::SetServerInfo Determina os recursos e as classes quando o documento do servidor é inserido ou editado no local.

Comentários

Geralmente, você cria um ou mais modelos de documento na implementação da função InitInstance do aplicativo. Um modelo de documento define as relações entre três tipos de classes:

  • Uma classe de documento, que você deriva de CDocument.

  • Uma classe de exibição, que exibe dados da classe de documento listada acima. Você pode derivar essa classe de CView, CScrollView, CFormView ou CEditView. (Você também pode usar CEditView diretamente.)

  • Uma classe de janela de quadro que contém a exibição. Para um aplicativo de SDI (interface de documento único), você deriva essa classe de CFrameWnd. Para um aplicativo de MDI (interface de vários documentos), você deriva essa classe de CMDIChildWnd. Se não precisar personalizar o comportamento da janela de quadro, você poderá usar CFrameWnd ou CMDIChildWnd diretamente sem derivar sua classe.

O aplicativo tem um modelo de documento para cada tipo de documento a que dá suporte. Por exemplo, se o aplicativo der suporte a planilhas e documentos de texto, ele terá dois objetos de modelo de documento. Cada modelo de documento é responsável por criar e gerenciar todos os documentos do respectivo tipo.

O modelo de documento armazena ponteiros para os objetos CRuntimeClass das classes de janela de quadro, documento e exibição. Esses objetos CRuntimeClass são especificados ao construir um modelo de documento.

O modelo de documento contém a ID dos recursos usados com o tipo de documento (por exemplo recursos de menu, ícone ou tabela de acelerador). O modelo de documento também tem cadeias de caracteres contendo informações adicionais sobre o tipo de documento. Elas incluem o nome do tipo de documento (por exemplo, "Planilha") e a extensão do arquivo (por exemplo, ".xls"). Opcionalmente, ele pode conter outras cadeias de caracteres usadas pela interface do usuário do aplicativo, o Gerenciador de Arquivos do Windows e suporte para OLE (Vinculação e Incorporação de Objetos).

Se o aplicativo for um servidor e/ou contêiner OLE, o modelo de documento também definirá a ID do menu usado durante a ativação no local. Se o aplicativo for um servidor OLE, o modelo de documento definirá a ID do menu e da barra de ferramentas usados durante a ativação no local. Especifique esses recursos de OLE adicionais chamando SetContainerInfo e SetServerInfo.

Como CDocTemplate é uma classe abstrata, você não pode usar a classe diretamente. Um aplicativo típico usa uma das duas classes derivadas de CDocTemplate fornecidas pela biblioteca Microsoft Foundation Class: CSingleDocTemplate, que implementa o SDI, e CMultiDocTemplate, que implementa o MDI. Consulte essas classes para obter mais informações sobre como usar modelos de documento.

Se o aplicativo exigir um paradigma de interface do usuário fundamentalmente diferente do SDI e do MDI, você poderá derivar sua classe de CDocTemplate.

Para obter mais informações sobre CDocTemplate, consulte Modelos de documentos e o processo de criação de documentos/exibições.

Hierarquia de herança

CObject

CCmdTarget

CDocTemplate

Requisitos

Cabeçalhoafxwin.h:

CDocTemplate::AddDocument

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

virtual void AddDocument(CDocument* pDoc);

Parâmetros

pDoc
Um ponteiro para o documento a ser adicionado.

Comentários

As classes derivadas CMultiDocTemplate e CSingleDocTemplate substituem essa função. Se você derivar sua classe de modelo de documento de CDocTemplate, a classe derivada deverá substituir essa função.

CDocTemplate::CDocTemplate

Constrói um objeto CDocTemplate.

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

Parâmetros

nIDResource
Especifica a ID dos recursos usados com o tipo de documento. Isso pode incluir recursos de menu, ícone, tabela aceleradora e cadeia de caracteres.

O recurso de cadeia de caracteres é composto por até sete substrings separadas pelo caractere \n (o caractere \n será necessário como um espaço reservado se uma substring não estiver incluída; no entanto, caracteres \n à direita não são necessários). Essas substring descrevem o tipo de documento. Para obter informações sobre as substrings, consulte GetDocString. Esse recurso de cadeia de caracteres é encontrado no arquivo de recurso do aplicativo. Por exemplo:

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

Observe que a cadeia de caracteres começa com um caractere \n. Isso ocorre porque a primeira substring não é usada para aplicativos MDI e, portanto, não está incluída. Você pode editar essa cadeia de caracteres usando o editor de cadeias de caracteres. A cadeia de caracteres inteira aparece como uma só entrada no Editor de Cadeias de Caracteres, não como sete entradas separadas.

pDocClass
Aponta para o objeto CRuntimeClass da classe de documento. Essa é uma classe derivada de CDocument que você define para representar seus documentos.

pFrameClass
Aponta para o objeto CRuntimeClass da classe de janela de quadro. Essa pode ser uma classe derivada de CFrameWnd ou pode ser CFrameWnd se você deseja o comportamento padrão para a janela de quadro principal.

pViewClass
Aponta para o objeto CRuntimeClass da classe de exibição. Essa é uma classe derivada de CView que você define para exibir seus documentos.

Comentários

Use essa função membro para construir um objeto CDocTemplate. Aloque dinamicamente um objeto CDocTemplate e passe-o para CWinApp::AddDocTemplate da função membro InitInstance da classe de aplicativo.

CDocTemplate::CloseAllDocuments

Chame essa função membro para fechar todos os documentos abertos.

virtual void CloseAllDocuments(BOOL bEndSession);

Parâmetros

bEndSession
Não usado.

Comentários

Essa função membro normalmente é usada como parte do comando File Exit. A implementação padrão dessa função chama a função membro CDocument::DeleteContents para excluir os dados do documento e fecha as janelas de quadro para todas as exibições anexadas ao documento.

Substitua essa função se quiser exigir que o usuário execute o processamento de limpeza especial antes que o documento seja fechado. Por exemplo, se o documento representa um registro em um banco de dados, talvez você queira substituir essa função para fechar o banco de dados.

CDocTemplate::CreateNewDocument

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

virtual CDocument* CreateNewDocument();

Valor de Devolução

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

CDocTemplate::CreateNewFrame

Cria uma janela de quadro contendo um documento e uma exibição.

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

Parâmetros

pDoc
O documento ao qual a nova janela de quadro deve fazer referência. Pode ser NULL.

pOther
A janela de quadro na qual a nova janela de quadro deve ser baseada. Pode ser NULL.

Valor de Devolução

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

Comentários

CreateNewFrame usa os objetos CRuntimeClass passados para o construtor para criar uma janela de quadro com uma exibição e um documento anexados. Se o parâmetro pDoc for NULL, a estrutura gerará uma mensagem TRACE.

O parâmetro pOther é usado para implementar o comando Window New. Ele fornece uma janela de quadro na qual modelar a nova janela de quadro. Geralmente, a nova janela de quadro é criada invisível. Chame essa função para criar janelas de quadro fora da implementação da estrutura padrão de File New e File Open.

CDocTemplate::CreateOleFrame

Cria uma janela de quadro OLE.

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

Parâmetros

pParentWnd
Um ponteiro para a janela pai do quadro.

pDoc
Um ponteiro para o documento a que a nova janela de quadro OLE deve fazer referência.

bCreateView
Determina se uma exibição é criada com o quadro.

Valor de Devolução

Um ponteiro para uma janela de quadro se tiver êxito; caso contrário, NULL.

Comentários

Se bCreateView for zero, um quadro vazio será criado.

CDocTemplate::GetDocString

Recupera uma cadeia de caracteres associada ao tipo de documento.

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

Parâmetros

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

index
Um índice da substring que está sendo recuperada da cadeia de caracteres que descreve o tipo de documento. Esse parâmetro pode ter um dos seguintes valores:

  • CDocTemplate::windowTitle Nome que aparece na barra de título da janela do aplicativo (por exemplo, "Microsoft Excel"). Presente somente no modelo de documento para aplicativos SDI.

  • CDocTemplate::docName Raiz do nome do documento padrão (por exemplo, "Planilha"). Essa raiz, com um número, é usada como nome padrão de um novo documento desse tipo sempre que o usuário escolhe o comando Novo comando no menu Arquivo (por exemplo, "Planilha1" ou "Planilha2"). Se não for especificado, "Sem título" será usado como padrão.

  • CDocTemplate::fileNewName Nome desde tipo de documento. Se o aplicativo der suporte a mais de um tipo de documento, essa cadeia de caracteres será exibida na caixa de diálogo Arquivo Novo (por exemplo, "Planilha"). Se não for especificada, o tipo de documento ficará inacessível usando o comando Arquivo Novo.

  • CDocTemplate::filterName Descrição do tipo de documento e um filtro curinga que correspondem a documentos desse tipo. Essa cadeia de caracteres é exibida na lista suspensa Listar Arquivos do Tipo na caixa de diálogo Abrir Arquivo (por exemplo, "Planilhas (*.xls)"). Se não for especificada, o tipo de documento ficará inacessível usando o comando Arquivo Abrir.

  • CDocTemplate::filterExt Extensão para documentos desse tipo (por exemplo, ".xls"). Se não for especificada, o tipo de documento ficará inacessível usando o comando Arquivo Abrir.

  • CDocTemplate::regFileTypeId Identificador do tipo de documento a ser armazenado no banco de dados de registro mantido pelo Windows. Essa cadeia de caracteres é somente para uso interno (por exemplo, "ExcelWorksheet"). Se não for especificado, o tipo de documento não poderá ser registrado no Gerenciador de Arquivos do Windows.

  • CDocTemplate::regFileTypeName Nome do tipo de documento a ser armazenado no banco de dados de registro. Essa cadeia de caracteres pode ser exibida em caixas de diálogo de aplicativos que acessam o banco de dados de registro (por exemplo, "Planilha do Microsoft Excel").

Valor de Devolução

Diferente de zero se a substring especificada foi encontrada; caso contrário, 0.

Comentários

Chame essa função para recuperar uma substring específica que descreve o tipo de documento. A cadeia de caracteres que contém essas substrings é armazenada no modelo de documento e é derivada de uma cadeia de caracteres no arquivo de recurso do aplicativo. A estrutura chama essa função para obter as cadeias de caracteres de que precisa para a interface do usuário do aplicativo. Se você especificou uma extensão de nome de arquivo para os documentos do aplicativo, a estrutura também chamará essa função ao adicionar uma entrada ao banco de dados de registro do Windows. Isso permite que documentos sejam abertos no Gerenciador de Arquivos do Windows.

Chame essa função somente se você estiver derivando sua classe de CDocTemplate.

CDocTemplate::GetFirstDocPosition

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

virtual POSITION GetFirstDocPosition() const = 0;

Valor de Devolução

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

Comentários

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

CSingleDocTemplate e CMultiDocTemplate substituem essa função virtual pura. Qualquer classe derivada de CDocTemplate também deve substituir essa função.

CDocTemplate::GetNextDoc

Recupera o elemento de lista identificado por rPos e define rPos como o valor POSITION da próxima entrada na lista.

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

Valor de Devolução

Um ponteiro para o próximo documento na lista de documentos associados ao modelo.

Parâmetros

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

Comentários

Se o elemento recuperado for o último na lista, o novo valor de rPos será definido como NULL.

Você poderá usar GetNextDoc em um loop de iteração para frente se estabelecer a posição inicial com uma chamada para GetFirstDocPosition.

Você deve garantir que o valor de POSITION represente uma posição válida na lista. Se ele for inválido, a versão de Depuração da biblioteca Microsoft Foundation Class será declarada.

CDocTemplate::InitialUpdateFrame

Inicializa a janela de quadro e, opcionalmente, a torna visível.

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

Parâmetros

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

pDoc
O documento ao qual o quadro está associado. Pode ser NULL.

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

Comentários

Chame IntitialUpdateFrame depois de criar um quadro com CreateNewFrame. Chamar essa função faz com que as exibições nessa janela de quadro recebam suas chamadas de OnInitialUpdate. Além disso, se não havia uma exibição ativa anteriormente, a exibição primária da janela de quadro será ativada. A exibição primária é uma exibição com uma ID filho AFX_IDW_PANE_FIRST. Por fim, a janela de quadro fica visível quando bMakeVisible é diferente de zero. Se bMakeVisible for zero, o foco atual e o estado visível da janela de quadro permanecerão inalterados.

Não é necessário chamar essa função ao usar a implementação da estrutura de Arquivo Novo e Arquivo Aberto.

CDocTemplate::LoadTemplate

Carrega os recursos de uma determinada CDocTemplate ou classe derivada.

virtual void LoadTemplate();

Comentários

Essa função membro é chamada pela estrutura para carregar os recursos para um CDocTemplate ou uma classe derivada determinada. Normalmente, ela é chamada durante a construção, exceto quando o modelo está sendo construído globalmente. Nesse caso, a chamada para LoadTemplate será adiada até que CWinApp::AddDocTemplate seja chamado.

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 arquivo cujo tipo deve ser determinado.

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

Valor de Devolução

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

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

Comentários

Use essa função para determinar o tipo de modelo de documento a ser usado para abrir um arquivo. Se o aplicativo der suporte a vários tipos de arquivo, por exemplo, você poderá usar essa função para determinar qual dos modelos de documento disponíveis é apropriado para um determinado arquivo chamando MatchDocType para cada modelo por vez e escolhendo um modelo de acordo com o valor de confiança retornado.

Se o arquivo especificado por lpszPathName já estiver aberto, essa função retornará CDocTemplate::yesAlreadyOpen e copiará o objeto CDocument do arquivo no objeto em rpDocMatch.

Se o arquivo não estiver aberto, mas a extensão em lpszPathName corresponder à extensão especificada por CDocTemplate::filterExt, essa função retornará CDocTemplate::yesAttemptNative e definirá rpDocMatch como NULL. Para obter mais informações sobre CDocTemplate::filterExto , consulte CDocTemplate::GetDocString.

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

A implementação padrão não retorna CDocTemplate::maybeAttemptForeign nem CDocTemplate::maybeAttemptNative. Substitua essa função para implementar a lógica de correspondência de tipos apropriada em seu aplicativo, talvez usando esses dois valores da enumeração Confidence.

CDocTemplate::OpenDocumentFile

Abre um arquivo especificado por um caminho.

virtual CDocument* OpenDocumentFile(LPCTSTR lpszPathName) = 0;

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

Parâmetros

lpszPathName
[in] Ponteiro para o caminho do arquivo que contém o documento a ser aberto.

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

Valor de Devolução

Um ponteiro para o documento cujo arquivo é nomeado por lpszPathName; NULL se não tiver êxito.

Comentários

Abre o arquivo cujo caminho é especificado por lpszPathName. Se lpszPathName for NULL, um arquivo que contém um documento do tipo associado a esse modelo será criado.

CDocTemplate::RemoveDocument

Remove o documento para o qual pDoc apontou da lista de documentos associados a esse modelo.

virtual void RemoveDocument(CDocument* pDoc);

Parâmetros

pDoc
Ponteiro para o documento a ser removido.

Comentários

As classes derivadas CMultiDocTemplate e CSingleDocTemplate substituem essa função. Se você derivar sua classe de modelo de documento de CDocTemplate, a classe derivada deverá substituir essa função.

CDocTemplate::SaveAllModified

Salva todos os documentos que foram modificados.

virtual BOOL SaveAllModified();

Valor de Devolução

Diferente de zero se tiver êxito, caso contrário, 0.

CDocTemplate::SetContainerInfo

Determina os recursos para contêineres OLE ao editar um item OLE no local.

void SetContainerInfo(UINT nIDOleInPlaceContainer);

Parâmetros

nIDOleInPlaceContainer
A ID dos recursos usados quando um objeto inserido é ativado.

Comentários

Chame essa função para definir os recursos a serem usados quando um objeto OLE for ativado no local. Esses recursos podem incluir menus e tabelas de acelerador. Essa função geralmente é chamada na função CWinApp::InitInstance do aplicativo.

O menu associado a nIDOleInPlaceContainer contém separadores que permitem que o menu do item ativado no local seja mesclado com o menu do aplicativo de contêiner. Para obter mais informações sobre como mesclar menus de servidor e de contêiner, consulte o artigo Menus e Recursos (OLE).

CDocTemplate::SetDefaultTitle

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

virtual void SetDefaultTitle(CDocument* pDocument) = 0;

Parâmetros

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

Comentários

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

CDocTemplate::SetServerInfo

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

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

Parâmetros

nIDOleEmbedding
A ID dos recursos usados quando um objeto inserido é aberto em uma janela separada.

nIDOleInPlaceServer
A ID dos recursos usados quando um objeto inserido é ativado no local.

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

pOleViewClass
Ponteiro para uma estrutura CRuntimeClass que contém informações de classe para o objeto de exibição criado quando ocorre a ativação no local.

Comentários

Chame essa função membro para identificar os recursos que serão usados pelo aplicativo de servidor quando o usuário solicitar a ativação de um objeto inserido. Esses recursos são compostos por menus e tabelas de acelerador. Essa função geralmente é chamada no InitInstance do aplicativo.

O menu associado a nIDOleInPlaceServer contém separadores que permitem que o menu do servidor seja mesclado com o menu do contêiner. Para obter mais informações sobre como mesclar menus de servidor e de contêiner, consulte o artigo Menus e Recursos (OLE).

CDocTemplate::CreatePreviewFrame

Cria um quadro filho usado para Visualização Avançada.

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

Parâmetros

pParentWnd
Um ponteiro para uma janela pai (geralmente fornecido pelo Shell).

pDoc
Um ponteiro para um objeto de documento cujo conteúdo será visualizado.

Valor de Devolução

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

Comentários

CDocTemplate::SetPreviewInfo

Configura o manipulador de visualização fora do processo.

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

Parâmetros

nIDPreviewFrame
Especifica uma ID do recurso do quadro de visualização.

pPreviewFrameClass
Especifica um ponteiro para uma estrutura de informações de classe de runtime do quadro de visualização.

pPreviewViewClass
Especifica um ponteiro para uma estrutura de informações de classe de runtime da exibição de visualização.

Comentários

Confira também

Classe CCmdTarget
Gráfico da hierarquia
Classe CSingleDocTemplate
Classe CMultiDocTemplate
Classe CDocument
Classe CView
Classe CScrollView
Classe CEditView
Classe CFormView
Classe CFrameWnd
Classe CMDIChildWnd