Compartir a través de

Clase CDocTemplate

  • Artículo

Una clase base abstracta que define la funcionalidad básica para las plantillas de documento.

Sintaxis

class CDocTemplate : public CCmdTarget

Miembros

Constructores protegidos

Nombre Descripción
CDocTemplate::CDocTemplate Construye un objeto CDocTemplate.

Métodos públicos

Nombre Descripción
CDocTemplate::AddDocument Agrega un documento a una plantilla.
CDocTemplate::CloseAllDocuments Cierra todos los documentos asociados a la plantilla.
CDocTemplate::CreateNewDocument Esta función se usa para crear un nuevo documento.
CDocTemplate::CreateNewFrame Crea una nueva ventana de marco que contiene un documento y una vista.
CDocTemplate::CreateOleFrame Crea una ventana de marco habilitada para OLE.
CDocTemplate::CreatePreviewFrame Crea un marco secundario que se usa para la vista previa enriquecida.
CDocTemplate::GetDocString Recupera una cadena asociada al tipo de documento.
CDocTemplate::GetFirstDocPosition Recupera la posición del primer documento asociado a la plantilla.
CDocTemplate::GetNextDoc Recupera un documento y la posición del siguiente.
CDocTemplate::InitialUpdateFrame Inicializa la ventana de marco y de forma opcional la hace visible.
CDocTemplate::LoadTemplate Carga los recursos de determinada CDocTemplate o clase derivada.
CDocTemplate::MatchDocType Determina el grado de confianza en la coincidencia entre un tipo de documento y la plantilla.
CDocTemplate::OpenDocumentFile Abre un archivo especificado por un nombre de ruta de acceso.
CDocTemplate::RemoveDocument Quita un documento de una plantilla.
CDocTemplate::SaveAllModified Guarda todos los documentos modificados asociados a esta plantilla.
CDocTemplate::SetContainerInfo Determina los recursos de los contenedores OLE al editar un elemento OLE local.
CDocTemplate::SetDefaultTitle Muestra el título predeterminado en la barra de título de la ventana del documento.
CDocTemplate::SetPreviewInfo Configura el controlador de vista previa del proceso.
CDocTemplate::SetServerInfo Determina los recursos y las clases cuando el documento de servidor se incrusta o se edita localmente.

Comentarios

Normalmente se crean una o más plantillas de documento en la implementación de la función de la aplicación InitInstance. Una plantilla de documento define las relaciones entre tres tipos de clases:

  • Clase de documento, que se deriva de CDocument.

  • Clase de vista, que muestra datos de la clase de documento indicada anteriormente. Puede derivar esta clase de CView, CScrollView, CFormView o CEditView. (También puede usar CEditView directamente).

  • Clase de ventana de marco, que contiene la vista. Para una única aplicación de interfaz de documento (SDI), se deriva esta clase de CFrameWnd. Para una aplicación de varias interfaces de documento (MDI), se deriva esta clase de CMDIChildWnd. Si no necesita personalizar el comportamiento de la ventana de marco, puede usar CFrameWnd o CMDIChildWnd de forma directa sin derivar su propia clase.

La aplicación tiene una plantilla de documento para cada tipo de documento que admita. Por ejemplo, si la aplicación admite hojas de cálculo además de documentos de texto, la aplicación tiene dos objetos de plantilla de documento. Cada plantilla de documento es responsable de crear y administrar todos los documentos de su tipo.

La plantilla de documento almacena punteros a los objetos CRuntimeClass de las clases de ventana de marco, vista y documento. Los objetos CRuntimeClass se especifican al elaborar una plantilla de documento.

La plantilla de documento contiene el id. de los recursos usados con el tipo de documento, (como los recursos de menú, icono o tabla de acelerador). La plantilla de documento también tiene cadenas que contienen información adicional sobre el tipo de documento. Aquí se incluye el nombre del tipo de documento, por ejemplo, «Worksheet» y la extensión de fichero, por ejemplo, «.xls». De forma opcional, puede contener otras cadenas que usa la interfaz de usuario de la aplicación, el Administrador de archivos de Windows y la compatibilidad con la vinculación e incrustación de objetos (OLE).

Si la aplicación es un contenedor OLE y/o un servidor, la plantilla de documento también define el id. del menú usado durante la activación local. Si la aplicación es un servidor OLE, la plantilla de documento define el id. de la barra de herramientas y menú usado en la activación local. Puede especificar estos recursos OLE adicionales, al llamar a SetContainerInfo y SetServerInfo.

Dado que CDocTemplate es una clase abstracta, no puede usar la clase directamente. Una aplicación típica usa una o de las clases derivadas de CDocTemplate proporcionadas por la biblioteca MFC (Microsoft Foundation Class): CSingleDocTemplate, que implementa SDI, y CMultiDocTemplate, que implementa MDI. Consulte esas clases para obtener más información sobre cómo usar plantillas de documento.

Si la aplicación requiere un paradigma de interfaz de usuario que sea diferente fundamentalmente de SDI o MDI, puede derivar su propia clase de CDocTemplate.

Para más información sobre CDocTemplate, consulte Plantillas de documento y proceso de creación de documentos o vistas.

Jerarquía de herencia

CObject

CCmdTarget

CDocTemplate

Requisitos

Encabezado: afxwin.h

CDocTemplate::AddDocument

Use esta función para agregar un documento a una plantilla.

virtual void AddDocument(CDocument* pDoc);

Parámetros

pDoc
Un puntero al documento que se va a agregar.

Comentarios

Las clases derivadas CMultiDocTemplate y CSingleDocTemplate invalidan esta función. Si deriva su propia clase de plantilla de documento de CDocTemplate, su clase derivada debe invalidar esta función.

CDocTemplate::CDocTemplate

Construye un objeto CDocTemplate.

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

Parámetros

nIDResource
Especifica el identificador de los recursos usados con el tipo de documento. Esto puede incluir recursos de menú, icono, tabla aceleradora y cadena.

El recurso de cadena consta de hasta siete substrings separadas por el carácter \n, el carácter \n es necesario como marcador de posición si no se incluye una substring. Sin embargo, no son necesarios caracteres \n finales. Estas substrings describen el tipo de documento. Si desea más información sobre las substings, consulte GetDocString. Este recurso de cadena se encuentra en el archivo de recursos de la aplicación. Por ejemplo:

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

Tenga en cuenta que la cadena comienza con un carácter \n porque la primera substring no se usa para las aplicaciones MDI, por lo que no se incluye. Puede editar esta cadena mediante el editor de cadenas; toda la cadena aparece como una sola entrada en el Editor de cadenas, no como siete entradas independientes.

pDocClass
Apunta al objeto CRuntimeClass de la clase de documento. Esta clase es una clase derivada de CDocument que se define para representar los documentos.

pFrameClass
Apunta al objeto CRuntimeClass de la clase de ventana de marco. Esta clase puede ser una clase derivada de CFrameWnd o puede ser CFrameWnd propiamente dicho si quiere un comportamiento predeterminado para la ventana de marco principal.

pViewClass
Apunta al objeto CRuntimeClass de la clase de vista. Esta clase es una clase derivada de CView que se define para mostrar los documentos.

Comentarios

Use esta función miembro para construir un objeto CDocTemplate. Asigne dinámicamente un objeto CDocTemplate y páselo a CWinApp::AddDocTemplate desde la función miembro InitInstance de la clase de aplicación.

CDocTemplate::CloseAllDocuments

Llame a esta función miembro para cerrar todos los documentos abiertos.

virtual void CloseAllDocuments(BOOL bEndSession);

Parámetros

bEndSession
No se usa.

Comentarios

Esta función miembro se suele usar como parte del como Salir del archivo. La implementación predeterminada de la función llama a la función miembro CDocument::DeleteContents para eliminar los datos del documento y, a continuación, cierra las ventanas de marco de todas las vistas adjuntas al documento.

Invalide esta función si desea exigir al usuario que realice un procesamiento de limpieza especial antes de que se cierre el documento. Por ejemplo, si el documento representa un registro en una base de datos, quizás quiera invalidar esta función para cerrar la base de datos.

CDocTemplate::CreateNewDocument

Puede llamar a esta función miembro para crear un nuevo documento del tipo asociado a esta plantilla de documento.

virtual CDocument* CreateNewDocument();

Valor devuelto

Un puntero al documento recién creado o NULL si se produce un error.

CDocTemplate::CreateNewFrame

Crea una nueva ventana de marco que contiene un documento y una vista.

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

Parámetros

pDoc
El documento al que debe hacer referencia la nueva ventana de marco. Puede ser NULL.

pOther
La ventana de marco en la que la nueva ventana marco se va a basar. Puede ser NULL.

Valor devuelto

Un puntero a la ventana de marco recién creada o NULL si se produce un error.

Comentarios

CreateNewFrame usa los objetos CRuntimeClass que se pasan al constructor para crear una ventana de marco con una vista y un documento adjunto. Si el parámetro pDoc es NULL, el marco genera un mensaje TRACE.

El parámetro pOther se usa para implementar el comando Nueva ventana. Proporciona una ventana de marco en la que se va a modelar la nueva ventana de marco. La nueva ventana de marco normalmente se crea de forma invisible. Llame a esta función para crear ventanas de marco exteriores a la implementación del marco de Archivo nuevo y Abrir archivo.

CDocTemplate::CreateOleFrame

Crea una ventana de marco OLE.

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

Parámetros

pParentWnd
Puntero a la ventana primaria de marco.

pDoc
Puntero al documento al que la nueva ventana de marco OLE debe hacer referencia.

bCreateView
Determina si se crea una vista junto con el marco.

Valor devuelto

Puntero a una ventana de marco si se ejecuta correctamente; de lo contrario, NULL.

Comentarios

Si bCreateView es cero, se crea un marco vacío.

CDocTemplate::GetDocString

Recupera una cadena asociada al tipo de documento.

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

Parámetros

rString
Referencia a un objeto CString que contendrá la cadena cuando se devuelva la función.

index
Índice de la substring que se va a recuperar de la cadena que describe el tipo de documento. Este parámetro puede tener uno de los valores siguientes:

  • CDocTemplate::windowTitle Nombre que aparece en la barra de título de la ventana de la aplicación, por ejemplo, «Microsoft Excel». Solo está presente en la plantilla de documento para las aplicaciones SDI.

  • CDocTemplate::docName Raíz del nombre de documento predeterminado, por ejemplo, «Hoja». Esta raíz, además de un número, se usa para el nombre predeterminado de un nuevo documento de este tipo siempre que el usuario elija el comando Nuevo del menú Archivo, por ejemplo, «Sheet1», «Sheet2». Si no se especifica, «Sin título» es el valor predeterminado.

  • CDocTemplate::fileNewName Nombre del tipo de documento. Si la aplicación admite más de un tipo de documento, esta cadena se muestra en el cuadro de diálogo Archivo nuevo, por ejemplo, «Hoja de cálculo». Si no se especifica, el tipo de documento no es accesible mediante el comando Archivo nuevo.

  • CDocTemplate::filterName Descripción del tipo de documento y un filtro con caracteres comodín que coinciden con documentos de este tipo. Esta cadena se muestra en la lista desplegable Lista de archivos de tipo en el cuadro de diálogo Abrir archivo, por ejemplo, «Hojas de cálculo», [*.xls]». Si no se especifica, el tipo de documento no es accesible mediante el comando Abrir archivo.

  • CDocTemplate::filterExt Extensión de documentos de este tipo, por ejemplo, «.xls». Si no se especifica, el tipo de documento no es accesible mediante el comando Abrir archivo.

  • CDocTemplate::regFileTypeId Identificador del tipo de documento que se va a almacenar en la base de datos de registro que mantiene Windows. Esta cadena es solo para uso interno, por ejemplo, «ExcelWorksheet». Si no se especifica, el tipo de documento no se puede registrar con el Administrador de archivos de Windows.

  • CDocTemplate::regFileTypeName Nombre del tipo de documento que se va almacenar en la base de datos de registro. Esta cadena se muestra mostrar en cajas de diálogo de las aplicaciones que acceden a la base de datos del registro, por ejemplo, «Hoja de cálculo de Microsoft Excel».

Valor devuelto

Distinto de cero si se encontró la substring especificada, de lo contrario 0.

Comentarios

Llame a esta función para recuperar una substring específica que describe el tipo de documento. La cadena que contiene estas substrings se almacena en la plantilla de documento y se deriva de una cadena en la plantilla de recursos de la aplicación. El marco llama a esta función para obtener las cadenas que necesita para la interfaz de usuario de la aplicación. Si ha especificado una extensión de nombre de archivo para los documentos de la aplicación, el marco también llama a esta función al agregar una entrada a la base de datos de registro de Windows, con lo que se permiten que los documentos se abran desde el Administrador de archivos de Windows.

Llame solo a esta función si deriva su propia clase de CDocTemplate.

CDocTemplate::GetFirstDocPosition

Recupera la posición del primer documento asociado a la plantilla.

virtual POSITION GetFirstDocPosition() const = 0;

Valor devuelto

Valor POSITION que se puede usar para recorrer en iteración la lista de documentos asociados a esta plantilla de documento o NULL si la lista está vacía.

Comentarios

Use esta función para obtener la posición del primer documento de la lista de documentos asociados a esta plantilla. Use el valor POSITION como argumento de CDocTemplate::GetNextDoc para recorrer en iteración la lista de documentos asociados a la plantilla.

CSingleDocTemplate y CMultiDocTemplate invalidan esta función virtual pura. Cualquier clase que derive de CDocTemplate también debe invalidar esta función.

CDocTemplate::GetNextDoc

Recupera el elemento de la lista identificado por rPos y, luego, establece rPos en el valor POSITION de la entrada siguiente de la lista.

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

Valor devuelto

Puntero al siguiente documento de la lista de documentos asociados a esta plantilla.

Parámetros

rPos
Referencia a un valor POSITION devuelto a una llamada anterior a GetFirstDocPosition o GetNextDoc.

Comentarios

Si el elemento recuperado es el último de la lista, el valor nuevo de rPos se establece en NULL.

Puede usar GetNextDoc en un bucle de iteración hacia delante si establece la posición inicial con una llamada a GetFirstDocPosition.

Debe asegurarse de que el valor POSITION representa una posición válida en la lista. Si no es válida, se impone la versión de depuración de la biblioteca MFC (Microsoft Foundation Class).

CDocTemplate::InitialUpdateFrame

Inicializa la ventana de marco y de forma opcional la hace visible.

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

Parámetros

pFrame
Ventana de marco que necesita la actualización inicial.

pDoc
Documento al que está asociado el marco. Puede ser NULL.

bMakeVisible
Indica si el marco debe hacerse visible y activo.

Comentarios

Llame a IntitialUpdateFrame después de crear un nuevo marco con CreateNewFrame. Al llamar a esta función, las vistas en la ventana de marco reciben sus llamadas OnInitialUpdate. Además, si no había anteriormente una vista activa, la vista principal de la ventana de marco se activa, la vista principal es una vista con un id. secundario de AFX_IDW_PANE_FIRST. Por último, la ventana de marco se hace visible si bMakeVisible no es cero. Si bMakeVisible es cero, el foco actual y el estado visible de la ventana de marco permanecerán sin cambios.

No es necesario llamar a esta función al usar la implementación del marco de Archivo nuevo y Abrir archivo.

CDocTemplate::LoadTemplate

Carga los recursos de determinada CDocTemplate o clase derivada.

virtual void LoadTemplate();

Comentarios

El marco llama a esta función miembro para cargar los recursos de una determinada CDocTemplate o clase derivada. Se suele llamar durante la construcción, excepto cuando la plantilla se construye globalmente. En ese caso, la llamada a LoadTemplate se retrasa hasta que se llama a CWinApp::AddDocTemplate.

CDocTemplate::MatchDocType

Determina el grado de confianza en la coincidencia entre un tipo de documento y la plantilla.

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

Parámetros

lpszPathName
Nombre de la ruta de acceso del archivo cuyo tipo se va a determinar.

rpDocMatch
Puntero a un documento al que se asigna el documento coincidente, si el archivo que especifica lpszPathName ya está abierto.

Valor devuelto

Valor de la enumeración Confidence, que se define como se señala a continuación:

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

Comentarios

Use esta función para determinar el tipo de la plantilla del documento que se usa para abrir un archivo. Si la aplicación admite varios tipos de archivo, por ejemplo, puede usar esta función para determinar cuál de esas plantillas de documento disponibles es la adecuada para determinado archivo al llamar a MatchDocType para cada plantilla a su vez y al elegir una plantilla en función del valor de confianza devuelto.

Si el archivo que especifica lpszPathName ya está abierto, esta función devuelve CDocTemplate::yesAlreadyOpen y copia el objeto de CDocument en el objeto en rpDocMatch.

Si el archivo no está abierto pero la extensión de lpszPathName coincide con la extensión que especifica CDocTemplate::filterExt, esta función devuelve CDocTemplate::yesAttemptNative y establece rpDocMatch en NULL. Para más información sobre CDocTemplate::filterExt, consulte CDocTemplate::GetDocString.

Si ningún caso es True, la función devuelve CDocTemplate::yesAttemptForeign.

La implementación predeterminada no devuelve CDocTemplate::maybeAttemptForeign ni CDocTemplate::maybeAttemptNative. Invalide esta función para implementar la lógica de coincidencia de tipos adecuada para la aplicación, quizás con estos dos valores de la enumeración Confidence.

CDocTemplate::OpenDocumentFile

Abre un archivo que especifica una ruta de acceso.

virtual CDocument* OpenDocumentFile(LPCTSTR lpszPathName) = 0;

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

Parámetros

lpszPathName
[in] Puntero a la ruta de acceso del archivo que contiene el documento que se va a abrir.

bAddToMRU
[in] TRUE indica que el documento es uno de los archivos más recientes; FALSE indica que el documento no es uno de los archivos más recientes.

Valor devuelto

Puntero al documento cuyo archivo recibe el nombre de lpszPathName; si no se realiza correctamente NULL.

Comentarios

Abre el archivo cuya ruta de acceso se especifica mediante lpszPathName. Si lpszPathName es NULL, se crea un nuevo archivo contiene un documento del tipo asociado a esta plantilla.

CDocTemplate::RemoveDocument

Quita el documento al que apunta pDoc de la lista de documentos asociados a esta plantilla.

virtual void RemoveDocument(CDocument* pDoc);

Parámetros

pDoc
Puntero al documento que se va a quitar.

Comentarios

Las clases derivadas CMultiDocTemplate y CSingleDocTemplate invalidan esta función. Si deriva su propia clase de plantilla de documento de CDocTemplate, su clase derivada debe invalidar esta función.

CDocTemplate::SaveAllModified

Guarda todos los documentos modificados.

virtual BOOL SaveAllModified();

Valor devuelto

Si la función se ejecuta correctamente, el valor devuelto será distinto de cero. En caso contrario, será 0.

CDocTemplate::SetContainerInfo

Determina los recursos de los contenedores OLE al editar un elemento OLE local.

void SetContainerInfo(UINT nIDOleInPlaceContainer);

Parámetros

nIDOleInPlaceContainer
Id. de los recursos usados cuando se activa un objeto incrustado.

Comentarios

Llame a esta función para establecer los recursos que se van a usar cuando se activan localmente objetos OLE. Entre estos recursos se pueden incluir menús y tablas de aceleradores. Esta función se suele llamar en la función CWinApp::InitInstance de la aplicación.

El menú asociado a nIDOleInPlaceContainer contiene separadores que permiten que el menú del elemento local activado para que se combine con el menú de la aplicación contenedora. Si desea más información sobre cómo combinar menús de contenedor y servidor, consulte el artículo Menus and Resources (OLE), (Menús y recursos [OLE]).

CDocTemplate::SetDefaultTitle

Puede llamar a esta función para cargar el título predeterminado del documento y lo muestra en la barra de título del documento.

virtual void SetDefaultTitle(CDocument* pDocument) = 0;

Parámetros

pDocument
Puntero al documento cuyo título se va a establecer.

Comentarios

Para obtener más información sobre el título predeterminado, consulte la descripción de CDocTemplate::docName en CDocTemplate::GetDocString.

CDocTemplate::SetServerInfo

Determina los recursos y las clases cuando el documento de servidor se incrusta o se edita localmente.

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

Parámetros

nIDOleEmbedding
Id. de los recursos usados cuando se abre una objeto incrustado en una ventana independiente.

nIDOleInPlaceServer
Id. de los recursos usados cuando se activa localmente un objeto incrustado.

pOleFrameClass
Puntero a una estructura CRuntimeClass que contiene información de clase para el objeto de ventana de marco creado cuando se produce la activación en contexto.

pOleViewClass
Puntero a una estructura CRuntimeClass que contiene información de clase para el objeto de vista creado cuando se produce la activación en contexto.

Comentarios

Llame a esta función miembro para identificar recursos que usará la aplicación de servidor cuando se solicita la activación de un objeto incrustado. Estos recursos constan de menús y tablas de aceleradores. Esta función se suele llamar en la InitInstance de la aplicación.

El menú asociado a nIDOleInPlaceServer contiene separadores que permiten que el menú de servidor se combine con el menú del contenedor. Si desea más información sobre cómo combinar menús de contenedor y servidor, consulte el artículo Menus and Resources (OLE), (Menús y recursos [OLE]).

CDocTemplate::CreatePreviewFrame

Crea un marco secundario que se usa para la vista previa enriquecida.

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

Parámetros

pParentWnd
Puntero a una ventana primaria, que proporciona normalmente Shell.

pDoc
Puntero a un objeto de documento, cuyo contenido se mostrará en vista previa.

Valor devuelto

Puntero válido a un objeto CFrameWnd o NULL si se produce error en la creación.

Comentarios

CDocTemplate::SetPreviewInfo

Configura el controlador de vista previa.

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

Parámetros

nIDPreviewFrame
Especifica un id. de recurso de marco de vista previa.

pPreviewFrameClass
Especifica un puntero a una estructura de información de clase en tiempo de ejecución del marco de vista previa.

pPreviewViewClass
Especifica un puntero a una estructura de información de clase en tiempo de ejecución de la vista previa.

Comentarios

Consulte también

CCmdTarget (clase)
Gráfico de jerarquías
CSingleDocTemplate (clase)
CMultiDocTemplate (clase)
CDocument (clase)
CView (clase)
CScrollView (clase)
CEditView (clase)
CFormView (clase)
CFrameWnd (clase)
CMDIChildWnd (clase)