Compartir a través de

Agregar una página de propiedades (Tutorial de ATL, Parte 6)

  • Artículo

Nota:

El Asistente para proveedores OLE DB ATL no está disponible en Visual Studio 2019 ni en versiones posteriores.

Las páginas de propiedades se implementan como objetos COM independientes, lo que permite compartirlas si es necesario. En este paso, realizará las tareas siguientes para agregar una página de propiedades al control:

  • Crear el recurso de página de propiedades

  • Agregar código para crear y administrar la página de propiedades

  • Agregar la página de propiedades al control

Crear el recurso de página de propiedades

Para agregar una página de propiedades al control, use la plantilla de página de propiedades ATL.

Agregar una página de propiedades

  1. En el Explorador de soluciones, haga clic con el botón derecho en Polygon.

  2. En el menú contextual, haga clic en Agregar>Nuevo elemento.

  3. En la lista de plantillas, seleccione ATL>Página de propiedades ATL y haga clic en Agregar.

  4. Cuando el Asistente para páginas de propiedades ATL aparece, escriba PolyProp como nombre corto.

  5. Haga clic en Cadenas para abrir la página Cadenas y escriba &Polígono como título.

    El título de la página de propiedades es la cadena que aparece en la pestaña de esa página. La cadena de documento es una descripción que usa un marco de propiedades para colocar una sugerencia de línea o información sobre herramientas. Tenga en cuenta que el marco de propiedades estándar actualmente no usa esta cadena, por lo que puede conservar el contenido predeterminado. No se generará un archivo de ayuda en este momento, así que elimine la entrada en ese cuadro de texto.

  6. Haga clic en Finalizar; se creará el objeto de la página de propiedades.

Se crean los tres archivos siguientes:

Archivo Descripción
PolyProp.h Contiene la clase C++ CPolyProp, que implementa la página de propiedades.
PolyProp.cpp Incluye el archivo PolyProp.h.
PolyProp.rgs El script de registro que registra el objeto de la página de propiedades.

Los cambios siguientes de código también son posibles:

  • La página de propiedades nueva se agrega a la asignación de entrada de objetos en Polygon.cpp.

  • La clase PolyProp se agrega al archivo Polygon.idl.

  • El nuevo archivo de script de registro PolyProp.rgs se agrega a los recursos del proyecto.

  • Una plantilla de cuadro de diálogo se agrega a los recursos del proyecto de la página de propiedades.

  • Las cadenas de propiedades que ha especificado se agregan a la tabla de cadenas de recursos.

Ahora agregue los campos que desea que aparezcan en la página de propiedades.

Agregar campos a la página de propiedades

  1. En el Explorador de soluciones, haga doble clic en el archivo de recursos Polygon.rc. Se abrirá Vista de recursos.

  2. En Vista de recursos, expanda el nodo Dialog y haga doble clic en IDD_POLYPROP. Tenga en cuenta que el cuadro de diálogo que aparece se muestra vacío, salvo por una etiqueta que indica si debe inserte aquí los controles.

  3. Seleccione esa etiqueta y cámbiela a Sides: de lectura modificando el texto Título de la ventana Propiedades.

  4. Cambie el tamaño del cuadro de etiqueta para que se ajuste el tamaño del texto.

  5. Arrastre un control Edit desde el cuadro de herramientas a la derecha de la etiqueta.

  6. Por último, cambie el identificador de control de edición a IDC_SIDES utilizando la ventana Propiedades.

Este paso completa el proceso de crear el recurso de página de propiedades.

Agregar código para crear y administrar la página de propiedades

Ahora que ha creado el recurso de página de propiedades, tiene que escribir el código de implementación.

En primer lugar, habilite la clase CPolyProp para establecer el número de lados en el objeto cuando se pulse el botón Aplicar.

Modificar la función Aplicar para establecer el número de lados

  1. Reemplace la función Apply en PolyProp.h por el código siguiente:

    STDMETHOD(Apply)(void)
{
   USES_CONVERSION;
   ATLTRACE(_T("CPolyProp::Apply\n"));
   for (UINT i = 0; i < m_nObjects; i++)
   {
      CComQIPtr<IPolyCtl, &IID_IPolyCtl> pPoly(m_ppUnk[i]);
      short nSides = (short)GetDlgItemInt(IDC_SIDES);
      if FAILED(pPoly->put_Sides(nSides))
      {
         CComPtr<IErrorInfo> pError;
         CComBSTR strError;
         GetErrorInfo(0, &pError);
         pError->GetDescription(&strError);
         MessageBox(OLE2T(strError), _T("Error"), MB_ICONEXCLAMATION);
         return E_FAIL;
      }
   }
   m_bDirty = FALSE;
   return S_OK;
}

Una página de propiedades puede tener más de un cliente asociado en cualquier momento, por lo que la función Apply reinicia el bucle y llama a put_Sides en cada cliente con el valor recuperado el cuadro de edición. Está usando la clase CComQIPtr, que lleva a cabo la operación QueryInterface en cada objeto para obtener la interfaz IPolyCtl de la interfaz IUnknown (almacenada en la matriz m_ppUnk).

Ahora, el código comprueba que la propiedad Sides realmente funcione. Si se produce un error, el código muestra un cuadro de mensaje con los detalles del error de la interfaz IErrorInfo. Normalmente, un contenedor solicita un objeto para la interfaz ISupportErrorInfo y llama a InterfaceSupportsErrorInfo primero, para determinar si el objeto admite la información de error de configuración. Puede omitir esta tarea.

CComPtr lo ayuda a controlar automáticamente el recuento de referencias, por lo que no es necesario llamar a Release en la interfaz. CComBSTR lo ayuda con el procesamiento de BSTR, por lo que no es necesario que realizar la llamada a SysFreeString final. También usa una de las diferentes clases de conversión de cadenas, por lo que puede convertir BSTR si es necesario (motivo por el cual la macro USES_CONVERSION se encuentra al principio de la función).

También deberá establecer la marca de modificado de la página de propiedades para indicar que el botón Aplicar debe estar habilitado. Esto se produce cuando el usuario cambia el valor en el cuadro de texto Lados.

Controlar el botón Aplicar

  1. En Vista de clases, haga clic en el botón derecho en CPolyProp y en Propiedades en el menú contextual.

  2. En la ventana Propiedades, haga clic en la pestaña Eventos.

  3. Expanda el nodo IDC_SIDES en la lista de eventos.

  4. Seleccione EN_CHANGE y, en el menú desplegable de la derecha, haga clic en <Agregar> OnEnChangeSides. La declaración del controlador OnEnChangeSides se agregará a Polyprop.h y la implementación del controlador a Polyprop.cpp.

A continuación, modificará el controlador.

Modificar el método OnEnChangeSides

  1. Agregue el código siguiente en Polyprop.cpp al método OnEnChangeSides (eliminando cualquier código que el Asistente coloque allí):

    LRESULT CPolyProp::OnEnChangeSides(WORD /*wNotifyCode*/, WORD /*wID*/, 
   HWND /*hWndCtl*/, BOOL& /*bHandled*/)
{
   SetDirty(TRUE);

   return 0;
}

Se llamará a OnEnChangeSides cuando se envía un mensaje WM_COMMAND con la notificación EN_CHANGE para el control IDC_SIDES. OnEnChangeSides a continuación llama a SetDirty y pasa TRUE para indicar que la página de propiedades ahora está modificada y el botón Aplicar debe estar habilitado.

Agregar la página de propiedades al control

La plantilla de página de propiedades ATL y el asistente no agregan la página de propiedades al control automáticamente, ya que podría haber varios controles en el proyecto. Deberá agregar una entrada a la asignación de propiedades del control.

Agregar la página de propiedades

  1. Abra PolyCtl.h y agregue estas líneas a la asignación de propiedades:

    PROP_ENTRY_TYPE("Sides", 1, CLSID_PolyProp, VT_INT)
PROP_PAGE(CLSID_PolyProp)

La asignación de propiedad del control ahora tendrá este aspecto:

BEGIN_PROP_MAP(CPolyCtl)
   PROP_DATA_ENTRY("_cx", m_sizeExtent.cx, VT_UI4)
   PROP_DATA_ENTRY("_cy", m_sizeExtent.cy, VT_UI4)
#ifndef _WIN32_WCE
   PROP_ENTRY_TYPE("FillColor", DISPID_FILLCOLOR, CLSID_StockColorPage, VT_UI4)
#endif
   PROP_ENTRY_TYPE("Sides", 1, CLSID_PolyProp, VT_INT)
   PROP_PAGE(CLSID_PolyProp)
   // Example entries
   // PROP_ENTRY("Property Description", dispid, clsid)
   // PROP_PAGE(CLSID_StockColorPage)
END_PROP_MAP()

Podría haber agregado una macro PROP_PAGE con el identificador CLSID de la página de propiedades, pero si utiliza la macro PROP_ENTRY tal como se muestra, el valor de propiedad Sides también se guarda cuando se guarda el control.

Los tres parámetros de la macro son la descripción de la propiedad, el identificador DISPID de la propiedad y el identificador CLSID de la página de propiedades que tiene la propiedad. Esto es útil si, por ejemplo, carga el control en Visual Basic y establece el número de lados en el tiempo de diseño. Como el número de lados se guarda, al volver a cargar el proyecto de Visual Basic, se restaurará el número de lados.

Compilar y probar el control

Ahora, genere el control e insértelo en ActiveX Control Test Container. En Test Container, en el menú Editar, haga clic en Objeto de la clase de PolyCtl. Aparece la página de propiedades con la información que agregó.

El botón Aplicar está deshabilitado inicialmente. Comience a escribir un valor en el cuadro Lados y el botón Aplicar se habilitará. Cuando haya terminado de escribir el valor, haga clic en el botón Aplicar. La visualización del control cambia y el botón Aplicar se deshabilita de nuevo. Pruebe a escribir un valor no válido. Verá un cuadro de mensaje que contiene la descripción del error que establece desde la función put_Sides.

A continuación, colocará el control en una página web.

Volver al Paso 5 | Avanzar al Paso 7

Consulte también

Tutorial