Versões de controle comum

  • Artigo

Este tópico lista as versões disponíveis da biblioteca de controle comum (ComCtl32.dll), descreve como identificar a versão que seu aplicativo está usando e explica como direcionar seu aplicativo para uma versão específica.

Este tópico inclui as seções a seguir.

Números de versões comuns da DLL de controle

O suporte para controles comuns é fornecido pelo ComCtl32.dll, que todas as versões de 32 bits e 64 bits do Windows incluem. Cada versão sucessiva da DLL suporta os recursos e a API de versões anteriores e adiciona novos recursos.

Como várias versões do ComCtl32.dll foram distribuídas com o Internet Explorer, a versão que está ativa às vezes é diferente da versão que foi fornecida com o sistema operacional. Portanto, seu aplicativo deve determinar diretamente qual versão do ComCtl32.dll está presente.

Na documentação de referência de controles comuns, muitos elementos de programação especificam um número mínimo de versão da DLL com suporte. Esse número de versão indica que o elemento de programação é implementado nessa versão e nas versões subsequentes da DLL, a menos que especificado de outra forma. Se nenhum número de versão for especificado, o elemento de programação será implementado em todas as versões existentes da DLL.

A tabela a seguir descreve as diferentes versões de DLL e como elas foram distribuídas em sistemas operacionais com suporte.

ComCtl32.dll

Versão

Plataforma de Distribuição

5.81

Microsoft Internet Explorer 5.01, Microsoft Internet Explorer 5.5 e Microsoft Internet Explorer 6

5.82

Windows Server 2003, Windows Vista, Windows Server 2008 e Windows 7

6,0

Windows Server 2003

6.10

Windows Vista, Windows Server 2008 e Windows 7

 

Tamanhos de estrutura para diferentes versões de controle comuns

Os contínuos aperfeiçoamentos dos controlos comuns resultaram na necessidade de alargar muitas das estruturas. Por esta razão, o tamanho das estruturas mudou entre as diferentes versões do Commctrl.h. Como a maioria das estruturas de controle comuns usa um tamanho de estrutura como um dos parâmetros, uma mensagem ou função pode falhar se o tamanho não for reconhecido. Para remediar isso, constantes de tamanho de estrutura foram definidas para ajudar a direcionar diferentes versões de ComCtl32.dll. A lista a seguir define as constantes de tamanho da estrutura.

Constante de tamanho da estrutura Definição
HDITEM_V1_SIZE O tamanho da estrutura HDITEM na versão 4.0.
IMAGELISTDRAWPARAMS_V3_SIZE O tamanho da estrutura IMAGELISTDRAWPARAMS na versão 5.9.
LVCOLUMN_V1_SIZE O tamanho da estrutura LVCOLUMN na versão 4.0.
LVGROUP_V5_SIZE O tamanho da estrutura do grupo VE na versão 6.0.
LVHITTESTINFO_V1_SIZE O tamanho da estrutura LVHITTESTINFO na versão 4.0.
LVITEM_V1_SIZE O tamanho da estrutura LVITEM na versão 4.0.
LVITEM_V5_SIZE O tamanho da estrutura LVITEM na versão 6.0.
LVTILEINFO_V5_SIZE O tamanho da estrutura LVTILEINFO na versão 6.0.
MCHITTESTINFO_V1_SIZE O tamanho da estrutura MCHITTESTINFO na versão 4.0.
NMLVCUSTOMDRAW_V3_SIZE O tamanho da estrutura NMLVCUSTOMDRAW na versão 4.7.
NMTTDISPINFO_V1_SIZE O tamanho da estrutura NMTTDISPINFO na versão 4.0.
NMTVCUSTOMDRAW_V3_SIZE O tamanho da estrutura NMTVCUSTOMDRAW na versão 4.7.
PROPSHEETHEADER_V1_SIZE O tamanho da estrutura PROPSHEETHEADER na versão 4.0.
PROPSHEETPAGE_V1_SIZE O tamanho da estrutura PROPSHEETPAGE na versão 4.0.
REBARBANDINFO_V3_SIZE O tamanho da estrutura REBARBANDINFO na versão 4.7.
REBARBANDINFO_V6_SIZE O tamanho da estrutura REBARBANDINFO na versão 6.0.
TTTOOLINFO_V1_SIZE O tamanho da estrutura TOOLINFO na versão 4.0.
TTTOOLINFO_V2_SIZE O tamanho da estrutura TOOLINFO na versão 4.7.
TTTOOLINFO_V3_SIZE O tamanho da estrutura TOOLINFO na versão 6.0.
TVINSERTSTRUCT_V1_SIZE O tamanho da estrutura TVINSERTSTRUCT na versão 4.0.

 

Usando DllGetVersion para determinar o número da versão

A função DllGetVersion pode ser chamada por um aplicativo para determinar qual versão da DLL está presente no sistema.

DllGetVersion retorna uma estrutura DLLVERSIONINFO2. Além das informações fornecidas por meio de DLLVERSIONINFO, DLLVERSIONINFO2 também fornece o número de hotfix que identifica o service pack instalado mais recente, que fornece uma maneira mais robusta de comparar números de versão. Como o primeiro membro do DLLVERSIONINFO2 é uma estrutura DLLVERSIONINFO , a estrutura posterior é compatível com versões anteriores.

A função de exemplo a seguir carrega uma DLL especificada e tenta chamar sua função DllGetVersion.GetVersion Se for bem-sucedido, ele usará uma macro para empacotar os números de versão principal e secundária da estrutura DLLVERSIONINFO em um DWORD que é retornado ao aplicativo de chamada. Se a DLL não exportar DllGetVersion, a função retorna zero. Você pode modificar a função para manipular a possibilidade de que DllGetVersion retorna uma estrutura DLLVERSIONINFO2 . Em caso afirmativo, use as informações no membro ullVersion dessa estrutura DLLVERSIONINFO2 para comparar versões, números de compilação e versões de service pack. A macro MAKEDLLVERULL simplifica a tarefa de comparar esses valores com aqueles em ullVersion.

Observação

Usar LoadLibrary incorretamente pode representar riscos de segurança. Consulte a documentação da LoadLibrary para obter informações sobre como carregar corretamente DLLs com versões diferentes do Windows.

 

#include "stdafx.h"
#include "windows.h"
#include "windef.h"
#include "winbase.h"
#include "shlwapi.h"

#define PACKVERSION(major,minor) MAKELONG(minor,major)

DWORD GetVersion(LPCTSTR lpszDllName)
{
    HINSTANCE hinstDll;
    DWORD dwVersion = 0;

    // For security purposes, LoadLibrary should be provided with a fully qualified 
    // path to the DLL. The lpszDllName variable should be tested to ensure that it 
    // is a fully qualified path before it is used. 
    hinstDll = LoadLibrary(lpszDllName);
    
    if(hinstDll)
    {
        DLLGETVERSIONPROC pDllGetVersion;
        pDllGetVersion = (DLLGETVERSIONPROC)GetProcAddress(hinstDll, "DllGetVersion");

        // Because some DLLs might not implement this function, you must test for 
        // it explicitly. Depending on the particular DLL, the lack of a DllGetVersion 
        // function can be a useful indicator of the version. 

        if(pDllGetVersion)
        {
            DLLVERSIONINFO dvi;
            HRESULT hr;

            ZeroMemory(&dvi, sizeof(dvi));
            dvi.info1.cbSize = sizeof(dvi);

            hr = (*pDllGetVersion)(&dvi);

            if(SUCCEEDED(hr))
            {
               dwVersion = PACKVERSION(dvi.info1.dwMajorVersion, dvi.info1.dwMinorVersion);
            }
        }
        FreeLibrary(hinstDll);
    }
    return dwVersion;
}

O exemplo de código a seguir mostra como você pode usar GetVersion para testar se ComCtl32.dll é a versão 6.0 ou posterior.

LPCTSTR lpszDllName = L"C:\\Windows\\System32\\ComCtl32.dll";
DWORD dwVer = GetVersion(lpszDllName);
DWORD dwTarget = PACKVERSION(6,0);

if(dwVer >= dwTarget)
{
    // This version of ComCtl32.dll is version 6.0 or later.
}
else
{
    // Proceed knowing that version 6.0 or later additions are not available.
    // Use an alternate approach for older the DLL version.
}

Versões do projeto

Para garantir que seu aplicativo seja compatível com diferentes versões de destino de um arquivo .dll, as macros de versão estão presentes nos arquivos de cabeçalho. Essas macros são usadas para definir, excluir ou redefinir determinadas definições para diferentes versões da DLL. Consulte Usando os cabeçalhos do Windows para obter uma descrição detalhada dessas macros .

Por exemplo, o nome da macro _WIN32_IE é comumente encontrado em cabeçalhos mais antigos. Você é responsável por definir a macro como um número hexadecimal. Esse número de versão define a versão de destino do aplicativo que está usando a DLL. A tabela a seguir mostra os números de versão disponíveis e o efeito que cada um tem em seu aplicativo.

Versão Descrição
0x0300 O aplicativo é compatível com ComCtl32.dll versão 4.70 e posterior. O aplicativo não pode implementar recursos que foram adicionados após a versão 4.70.
0x0400 O aplicativo é compatível com ComCtl32.dll versão 4.71 e posterior. O aplicativo não pode implementar recursos que foram adicionados após a versão 4.71.
0x0401 O aplicativo é compatível com ComCtl32.dll versão 4.72 e posterior. O aplicativo não pode implementar recursos que foram adicionados após a versão 4.72.
0x0500 O aplicativo é compatível com ComCtl32.dll versão 5.80 e posterior. O aplicativo não pode implementar recursos que foram adicionados após a versão 5.80.
0x0501 O aplicativo é compatível com ComCtl32.dll versão 5.81 e posterior. O aplicativo não pode implementar recursos que foram adicionados após a versão 5.81.
0x0600 O aplicativo é compatível com ComCtl32.dll versão 6.0 e posterior. O aplicativo não pode implementar recursos que foram adicionados após a versão 6.0.

 

Se você não definir a macro _WIN32_IE em seu projeto, ela será definida automaticamente como 0x0500. Para definir um valor diferente, você pode adicionar o seguinte às diretivas do compilador em seu arquivo make; Substitua o número de versão desejado por 0x0400.

/D _WIN32_IE=0x0400

Outro método é adicionar uma linha semelhante à seguinte em seu código-fonte antes de incluir os arquivos de cabeçalho do Shell. Substitua o número da versão desejada por 0x0400.

#define _WIN32_IE 0x0400
#include <commctrl.h>

Sobre controles comuns