Função DlgDirListA (winuser.h)

Artigo
08/27/2023

Substitui o conteúdo de uma caixa de listagem pelos nomes dos subdiretórios e arquivos em um diretório especificado. Você pode filtrar a lista de nomes especificando um conjunto de atributos de arquivo. Opcionalmente, a lista pode incluir unidades mapeadas.

Sintaxe

int DlgDirListA(
  [in]      HWND  hDlg,
  [in, out] LPSTR lpPathSpec,
  [in]      int   nIDListBox,
  [in]      int   nIDStaticPath,
  [in]      UINT  uFileType
);

Parâmetros

[in] hDlg

Tipo: HWND

Um identificador para a caixa de diálogo que contém a caixa de listagem.

[in, out] lpPathSpec

Tipo: LPTSTR

Um ponteiro para um buffer que contém uma cadeia de caracteres terminada em nulo que especifica um caminho absoluto, um caminho relativo ou um nome de arquivo. Um caminho absoluto pode começar com uma letra de unidade (por exemplo, d:) ou um nome UNC (por exemplo, \<i>machinename\sharename).

A função divide a cadeia de caracteres em um diretório e um nome de arquivo. A função pesquisa o diretório em busca de nomes que correspondam ao nome do arquivo. Se a cadeia de caracteres não especificar um diretório, a função pesquisa o diretório atual.

Se a cadeia de caracteres incluir um nome de arquivo, o nome do arquivo deverá conter pelo menos um caractere curinga (? ou *). Se a cadeia de caracteres não incluir um nome de arquivo, a função se comportará como se você tivesse especificado o caractere curinga do asterisco (*) como o nome do arquivo. Todos os nomes no diretório especificado que correspondem ao nome do arquivo e têm os atributos especificados pelo parâmetro uFileType são adicionados à caixa de listagem.

[in] nIDListBox

Tipo: int

O identificador de uma caixa de listagem na caixa de diálogo hDlg . Se esse parâmetro for zero, DlgDirList não tentará preencher uma caixa de listagem.

[in] nIDStaticPath

Tipo: int

O identificador de um controle estático na caixa de diálogo hDlg . DlgDirList define o texto desse controle para exibir a unidade e o diretório atuais. Esse parâmetro poderá ser zero se você não quiser exibir a unidade e o diretório atuais.

[in] uFileType

Tipo: UINT

Especifica os atributos dos arquivos ou diretórios a serem adicionados à caixa de listagem. Esse parâmetro pode usar um dos valores a seguir.

Valor	Significado
DDL_ARCHIVE	Inclui arquivos arquivados.
DDL_DIRECTORY	Inclui subdiretórios. Os nomes de subdiretórios são colocados entre colchetes ([ ]).
DDL_DRIVES	Todas as unidades mapeadas são adicionadas à lista. As unidades são listadas no formulário [- x-], em que x é a letra da unidade.
DDL_EXCLUSIVE	Inclui apenas arquivos com os atributos especificados. Por padrão, os arquivos de leitura/gravação são listados mesmo se DDL_READWRITE não for especificado.
DDL_HIDDEN	Inclui arquivos ocultos.
DDL_READONLY	Inclui arquivos somente leitura.
DDL_READWRITE	Inclui arquivos de leitura/gravação sem atributos adicionais. Essa é a configuração padrão.
DDL_SYSTEM	Inclui arquivos do sistema.
DDL_POSTMSGS	Se definido, DlgDirList usará a função PostMessage para enviar mensagens para a caixa de listagem. Se não estiver definido, DlgDirList usará a função SendMessage .

Retornar valor

Tipo: int

Se a função for bem-sucedida, o valor retornado será diferente de zero.

Se a função falhar, o valor retornado será zero. Por exemplo, se a cadeia de caracteres especificada por lpPathSpec não for um caminho válido, a função falhará. Para obter outras informações sobre o erro, chame .

Comentários

Se lpPathSpec especificar um diretório, DlgDirListComboBox alterará o diretório atual para o diretório especificado antes de preencher a caixa de listagem. O texto do controle estático identificado pelo parâmetro nIDStaticPath é definido como o nome do novo diretório atual.

DlgDirList envia as mensagens LB_RESETCONTENT e LB_DIR para a caixa de listagem.

Se uFileType incluir o sinalizador DDL_DIRECTORY e lpPathSpec especificar um diretório de primeiro nível, como C:\TEMP, a caixa de listagem sempre incluirá uma entrada ".." para o diretório raiz. Isso é verdadeiro mesmo se o diretório raiz tiver atributos ocultos ou do sistema e os sinalizadores DDL_HIDDEN e DDL_SYSTEM não forem especificados. O diretório raiz de um volume NTFS tem atributos ocultos e do sistema.

A listagem de diretório exibe nomes de arquivo longos, se houver.

Exemplos

Para obter exemplos, consulte os seguintes tópicos: Criando uma listagem de diretórios em uma caixa de listagem de seleção única e Criando uma caixa de listagem de seleção múltipla.

Observação

O cabeçalho winuser.h define DlgDirList como um alias que seleciona automaticamente a versão ANSI ou Unicode dessa função com base na definição da constante de pré-processador UNICODE. Misturar o uso do alias neutro de codificação com código que não seja neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Convenções para protótipos de função.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows Vista [somente aplicativos da área de trabalho]
Servidor mínimo com suporte	Windows Server 2003 [somente aplicativos da área de trabalho]
Plataforma de Destino	Windows
Cabeçalho	winuser.h (inclua Windows.h)
Biblioteca	User32.lib
DLL	User32.dll