Struttura OPENFILENAMEW (commdlg.h)

[A partire da Windows Vista, le finestre di dialogo Comuni Apri e Salva con nome sono state sostituite dalla finestra di dialogo Elemento comune. È consigliabile usare l'API Finestra di dialogo elemento comune anziché queste finestre di dialogo dalla libreria delle finestre di dialogo comuni.

Contiene informazioni utilizzate dalle funzioni GetOpenFileName e GetSaveFileName per inizializzare una finestra di dialogo Apri o Salva con nome. Dopo che l'utente chiude la finestra di dialogo, il sistema restituisce informazioni sulla selezione dell'utente in questa struttura.

Sintassi

typedef struct tagOFNW {
  DWORD         lStructSize;
  HWND          hwndOwner;
  HINSTANCE     hInstance;
  LPCWSTR       lpstrFilter;
  LPWSTR        lpstrCustomFilter;
  DWORD         nMaxCustFilter;
  DWORD         nFilterIndex;
  LPWSTR        lpstrFile;
  DWORD         nMaxFile;
  LPWSTR        lpstrFileTitle;
  DWORD         nMaxFileTitle;
  LPCWSTR       lpstrInitialDir;
  LPCWSTR       lpstrTitle;
  DWORD         Flags;
  WORD          nFileOffset;
  WORD          nFileExtension;
  LPCWSTR       lpstrDefExt;
  LPARAM        lCustData;
  LPOFNHOOKPROC lpfnHook;
  LPCWSTR       lpTemplateName;
  LPEDITMENU    lpEditInfo;
  LPCSTR        lpstrPrompt;
  void          *pvReserved;
  DWORD         dwReserved;
  DWORD         FlagsEx;
} OPENFILENAMEW, *LPOPENFILENAMEW;

Members

lStructSize

Tipo: DWORD

Lunghezza, in byte, della struttura. Usare sizeof (OPENFILENAME) per questo parametro.

hwndOwner

Tipo: HWND

Handle per la finestra proprietaria della finestra di dialogo. Questo membro può essere qualsiasi handle di finestra valido oppure può essere NULL se la finestra di dialogo non ha proprietario.

hInstance

Tipo: HINSTANCE

Se il flag OFN_ENABLETEMPLATEHANDLE è impostato nel membro Flags , hInstance è un handle per un oggetto memoria contenente un modello di finestra di dialogo. Se il flag OFN_ENABLETEMPLATE è impostato, hInstance è un handle per un modulo che contiene un modello di finestra di dialogo denominato dal membro lpTemplateName . Se nessuno dei due flag è impostato, questo membro viene ignorato. Se il flag di OFN_EXPLORER è impostato, il sistema usa il modello specificato per creare una finestra di dialogo figlio della finestra di dialogo predefinita in stile Esplora risorse. Se il flag di OFN_EXPLORER non è impostato, il sistema usa il modello per creare una finestra di dialogo in stile precedente che sostituisce la finestra di dialogo predefinita.

lpstrFilter

Tipo: LPCTSTR

Buffer contenente coppie di stringhe di filtro con terminazione Null. L'ultima stringa nel buffer deve essere terminata da due caratteri NULL .

La prima stringa in ogni coppia è una stringa di visualizzazione che descrive il filtro (ad esempio , "File di testo") e la seconda stringa specifica il modello di filtro (ad esempio , ".TXT"). Per specificare più modelli di filtro per una singola stringa di visualizzazione, usare un punto e virgola per separare i modelli , ad esempio ".TXT; .DOC;. BAK"). Una stringa di criterio può essere una combinazione di caratteri di nome file validi e il carattere jolly asterisco (*) . Non includere spazi nella stringa del criterio.

Il sistema non modifica l'ordine dei filtri. Li visualizza nella casella combinata Tipi di file nell'ordine specificato in lpstrFilter.

Se lpstrFilter è NULL, la finestra di dialogo non visualizza alcun filtro.

Nel caso di un collegamento, se non è impostato alcun filtro, GetOpenFileName e GetSaveFileName recuperano il nome del file .lnk, non la destinazione. Questo comportamento equivale all'impostazione del flag OFN_NODEREFERENCELINKS nel membro Flags . Per recuperare la destinazione di un collegamento senza filtrare, usare la stringa "All Files\0*.*\0\0".

lpstrCustomFilter

Tipo: LPTSTR

Buffer statico che contiene una coppia di stringhe di filtro con terminazione Null per mantenere il modello di filtro scelto dall'utente. La prima stringa è la stringa di visualizzazione che descrive il filtro personalizzato e la seconda stringa è il modello di filtro selezionato dall'utente. La prima volta che l'applicazione crea la finestra di dialogo, specificare la prima stringa, che può essere qualsiasi stringa non valida. Quando l'utente seleziona un file, la finestra di dialogo copia il modello di filtro corrente nella seconda stringa. Il modello di filtro mantenuto può essere uno dei modelli specificati nel buffer lpstrFilter oppure può essere un criterio di filtro tipizzato dall'utente. Il sistema usa le stringhe per inizializzare il filtro file definito dall'utente alla successiva creazione della finestra di dialogo. Se il membro nFilterIndex è zero, la finestra di dialogo utilizza il filtro personalizzato.

Se questo membro è NULL, la finestra di dialogo non mantiene i criteri di filtro definiti dall'utente.

Se questo membro non è NULL, il valore del membro nMaxCustFilter deve specificare le dimensioni, in caratteri, del buffer lpstrCustomFilter .

nMaxCustFilter

Tipo: DWORD

Dimensione, in caratteri, del buffer identificato da lpstrCustomFilter. Questo buffer deve avere una lunghezza di almeno 40 caratteri. Questo membro viene ignorato se lpstrCustomFilter è NULL o punta a una stringa NULL .

nFilterIndex

Tipo: DWORD

Indice del filtro attualmente selezionato nel controllo Tipi di file . Il buffer a cui punta lpstrFilter contiene coppie di stringhe che definiscono i filtri. La prima coppia di stringhe ha un valore di indice pari a 1, la seconda coppia 2 e così via. Un indice pari a zero indica il filtro personalizzato specificato da lpstrCustomFilter. È possibile specificare un indice nell'input per indicare la descrizione del filtro iniziale e il modello di filtro per la finestra di dialogo. Quando l'utente seleziona un file, nFilterIndex restituisce l'indice del filtro attualmente visualizzato. Se nFilterIndex è zero e lpstrCustomFilter è NULL, il sistema usa il primo filtro nel buffer lpstrFilter . Se tutti e tre i membri sono zero o NULL, il sistema non utilizza filtri e non visualizza alcun file nel controllo elenco di file della finestra di dialogo.

lpstrFile

Tipo: LPTSTR

Nome file utilizzato per inizializzare il controllo di modifica nome file . Il primo carattere di questo buffer deve essere NULL se l'inizializzazione non è necessaria. Quando la funzione GetOpenFileName o GetSaveFileName viene restituita correttamente, questo buffer contiene l'indicatore, il percorso, il nome file e l'estensione del file selezionato.

Se il flag OFN_ALLOWMULTISELECT è impostato e l'utente seleziona più file, il buffer contiene la directory corrente seguita dai nomi di file dei file selezionati. Per le finestre di dialogo in stile Esplora risorse, le stringhe di directory e nome file sono separate da NULL , con un carattere NULL aggiuntivo dopo l'ultimo nome file. Per le finestre di dialogo in stile precedente, le stringhe sono separate da spazi e la funzione usa nomi di file brevi per i nomi di file con spazi. È possibile usare la funzione FindFirstFile per eseguire la conversione tra nomi di file lunghi e brevi. Se l'utente seleziona un solo file, la stringa lpstrFile non ha un separatore tra il percorso e il nome del file.

Se il buffer è troppo piccolo, la funzione restituisce FALSE e la funzione CommDlgExtendedError restituisce FNERR_BUFFERTOOSMALL. In questo caso, i primi due byte del buffer lpstrFile contengono le dimensioni necessarie, in byte o caratteri.

nMaxFile

Tipo: DWORD

Dimensione, in caratteri, del buffer a cui punta lpstrFile. Il buffer deve essere sufficientemente grande per archiviare il percorso e la stringa o le stringhe del nome file, incluso il carattere NULL di terminazione. Le funzioni GetOpenFileName e GetSaveFileName restituiscono FALSE se il buffer è troppo piccolo per contenere le informazioni sul file. Il buffer deve contenere almeno 256 caratteri.

lpstrFileTitle

Tipo: LPTSTR

Nome file e estensione (senza informazioni sul percorso) del file selezionato. Questo membro può essere NULL.

nMaxFileTitle

Tipo: DWORD

Dimensione, in caratteri, del buffer a cui punta lpstrFileTitle. Questo membro viene ignorato se lpstrFileTitle è NULL.

lpstrInitialDir

Tipo: LPCTSTR

Directory iniziale. L'algoritmo per la selezione della directory iniziale varia in base a piattaforme diverse.

Windows 7:

1. Se lpstrInitialDir ha lo stesso valore passato la prima volta che l'applicazione ha usato una finestra di dialogo Apri o Salva con nome, il percorso selezionato più di recente dall'utente viene usato come directory iniziale.
2. In caso contrario, se lpstrFile contiene un percorso, tale percorso è la directory iniziale.
3. In caso contrario, se lpstrInitialDir non è NULL, specifica la directory iniziale.
4. Se lpstrInitialDir è NULL e la directory corrente contiene tutti i file dei tipi di filtro specificati, la directory iniziale è la directory corrente.
5. In caso contrario, la directory iniziale è la directory dei file personali dell'utente corrente.
6. In caso contrario, la directory iniziale è la cartella Desktop.

1. Se lpstrFile contiene un percorso, tale percorso è la directory iniziale.
2. In caso contrario, lpstrInitialDir specifica la directory iniziale.
3. In caso contrario, se l'applicazione ha usato una finestra di dialogo Apri o Salva con nome in passato, il percorso usato più di recente viene selezionato come directory iniziale. Tuttavia, se un'applicazione non viene eseguita per molto tempo, il percorso selezionato salvato viene rimosso.
4. Se lpstrInitialDir è NULL e la directory corrente contiene tutti i file dei tipi di filtro specificati, la directory iniziale è la directory corrente.
5. In caso contrario, la directory iniziale è la directory dei file personali dell'utente corrente.
6. In caso contrario, la directory iniziale è la cartella Desktop.

lpstrTitle

Tipo: LPCTSTR

Stringa da inserire nella barra del titolo della finestra di dialogo. Se questo membro è NULL, il sistema usa il titolo predefinito, ovvero Salva con nome o Apri.

Flags

Tipo: DWORD

Un set di flag di bit che è possibile usare per inizializzare la finestra di dialogo. Quando la finestra di dialogo restituisce, imposta questi flag per indicare l'input dell'utente. Questo membro può essere una combinazione dei flag seguenti.

nFileOffset

Tipo: WORD

Offset in base zero, in caratteri, dall'inizio del percorso al nome del file nella stringa a cui punta lpstrFile. Per la versione ANSI, si tratta del numero di byte; per la versione Unicode, si tratta del numero di caratteri. Ad esempio, se lpstrFile punta alla stringa seguente, "c:\dir1\dir2\file.ext", questo membro contiene il valore 13 per indicare l'offset della stringa "file.ext". Se l'utente seleziona più file, nFileOffset è l'offset al nome del primo file.

nFileExtension

Tipo: WORD

Offset in base zero, in caratteri, dall'inizio del percorso all'estensione del nome file nella stringa a cui punta lpstrFile. Per la versione ANSI, si tratta del numero di byte; per la versione Unicode, si tratta del numero di caratteri. In genere l'estensione del nome file è la sottostringa che segue l'ultima occorrenza del carattere dot ("."). Ad esempio, txt è l'estensione del nome file readme.txt, html l'estensione di readme.txt.html. Pertanto, se lpstrFile punta alla stringa "c:\dir1\dir2\readme.txt", questo membro contiene il valore 20. Se lpstrFile punta alla stringa "c:\dir1\dir2\readme.txt.html", questo membro contiene il valore 24. Se lpstrFile punta alla stringa "c:\dir1\dir2\readme.txt.html.", questo membro contiene il valore 29. Se lpstrFile punta a una stringa che non contiene alcun carattere "." come "c:\dir1\dir2\readme", questo membro contiene zero.

lpstrDefExt

Tipo: LPCTSTR

Estensione predefinita. GetOpenFileName e GetSaveFileName aggiunge questa estensione al nome del file se l'utente non riesce a digitare un'estensione. Questa stringa può essere qualsiasi lunghezza, ma vengono accodati solo i primi tre caratteri. La stringa non deve contenere un punto (.). Se questo membro è NULL e l'utente non digita un'estensione, non viene aggiunta alcuna estensione.

lCustData

Tipo: LPARAM

Dati definiti dall'applicazione che il sistema passa alla procedura di hook identificata dal membro lpfnHook . Quando il sistema invia il messaggio di WM_INITDIALOG alla procedura di hook, il parametro lParam del messaggio è un puntatore alla struttura OPENFILENAME specificata al momento della creazione della finestra di dialogo. La procedura di hook può usare questo puntatore per ottenere il valore lCustData .

lpfnHook

Tipo: LPOFNHOOKPROC

Puntatore a una procedura di hook. Questo membro viene ignorato a meno che il membro Flags includa il flag di OFN_ENABLEHOOK .

Se il flag OFN_EXPLORER non è impostato nel membro Flags , lpfnHook è un puntatore a una routine di hook OFNHookProcOldStyle che riceve i messaggi destinati alla finestra di dialogo. La procedura di hook restituisce FALSE per passare un messaggio alla procedura predefinita della finestra di dialogo o TRUE per eliminare il messaggio.

Se OFN_EXPLORER è impostato, lpfnHook è un puntatore a una routine di hook OFNHookProc . La procedura di hook riceve messaggi di notifica inviati dalla finestra di dialogo. La procedura di hook riceve anche messaggi per eventuali controlli aggiuntivi definiti specificando un modello di finestra di dialogo figlio. La procedura di hook non riceve messaggi destinati ai controlli standard della finestra di dialogo predefinita.

lpTemplateName

Tipo: LPCTSTR

Nome della risorsa modello di dialogo nel modulo identificato dal membro hInstance . Per le risorse della finestra di dialogo numerate, questo può essere un valore restituito dalla macro MAKEINTRESOURCE . Questo membro viene ignorato a meno che il flag di OFN_ENABLETEMPLATE non sia impostato nel membro Flags . Se il flag di OFN_EXPLORER è impostato, il sistema usa il modello specificato per creare una finestra di dialogo figlio della finestra di dialogo Di esplorazione predefinita. Se il flag di OFN_EXPLORER non è impostato, il sistema usa il modello per creare una finestra di dialogo di stile precedente che sostituisce la finestra di dialogo predefinita.

lpEditInfo

Questo membro viene compilato in modo condizionale (usando #ifdef _MAC) in modo che sia applicabile solo ai computer Motorola 68K Macintosh e non ai sistemi operativi client Windows.

lpstrPrompt

Questo membro viene compilato in modo condizionale (usando #ifdef _MAC) in modo che sia applicabile solo ai computer Motorola 68K Macintosh e non ai sistemi operativi client Windows.

pvReserved

Tipo: void*

Questo membro è riservato.

dwReserved

Tipo: DWORD

Questo membro è riservato.

FlagsEx

Tipo: DWORD

Un set di flag di bit che è possibile usare per inizializzare la finestra di dialogo. Attualmente, questo membro può essere zero o il flag seguente.

Commenti

Per motivi di compatibilità, la barra Places è nascosta se flag è impostato su OFN_ENABLEHOOK e lStructSize è OPENFILENAME_SIZE_VERSION_400.

Requisiti

Vedi anche

Libreria delle finestre di dialogo comuni

Informazioni concettuali

Getopenfilename

GetSaveFileName

Altre risorse

Riferimento

SHGetSpecialFolderLocation