Funzione ExtCreatePen (wingdi.h)

Articolo
08/27/2023

La funzione ExtCreatePen crea una penna cosmetica o geometrica logica con gli attributi di stile, larghezza e pennello specificati.

Sintassi

HPEN ExtCreatePen(
  [in] DWORD          iPenStyle,
  [in] DWORD          cWidth,
  [in] const LOGBRUSH *plbrush,
  [in] DWORD          cStyle,
  [in] const DWORD    *pstyle
);

Parametri

[in] iPenStyle

Combinazione di attributi type, style, end cap e join. I valori di ogni categoria vengono combinati usando l'operatore OR bit per bit ( | ).

Il tipo di penna può essere uno dei valori seguenti.

Valore	Significato
PS_GEOMETRIC	La penna è geometrica.
PS_COSMETIC	La penna è cosmetica.

Lo stile della penna può essere uno dei valori seguenti.

Valore	Significato
PS_ALTERNATE	La penna imposta ogni altro pixel. Questo stile è applicabile solo per le penne cosmetiche.
PS_SOLID	La penna è solida.
PS_DASH	La penna è tratteggiata.
PS_DOT	La penna è punteggiata.
PS_DASHDOT	La penna ha trattini alternati e puntini.
PS_DASHDOTDOT	La penna ha trattini alternati e punti doppie.
PS_NULL	La penna è invisibile.
PS_USERSTYLE	La penna usa una matrice di stili fornita dall'utente.
PS_INSIDEFRAME	La penna è solida. Quando questa penna viene usata in qualsiasi funzione di disegno GDI che accetta un rettangolo di selezione, le dimensioni della figura vengono ridotto in modo che si adatta interamente nel rettangolo di delimitazione, tenendo conto della larghezza della penna. Questo vale solo per le penne geometriche.

Il limite finale viene specificato solo per le penne geometriche. Il limite finale può essere uno dei valori seguenti.

Valore	Significato
PS_ENDCAP_ROUND	I limiti finali sono arrotondati.
PS_ENDCAP_SQUARE	I limiti finali sono quadrati.
PS_ENDCAP_FLAT	I limiti finali sono flat.

Il join viene specificato solo per le penne geometriche. Il join può essere uno dei valori seguenti.

Valore	Significato
PS_JOIN_BEVEL	I join vengono svelti.
PS_JOIN_MITER	I join vengono miterati quando si trovano all'interno del limite corrente impostato dalla funzione SetMiterLimit . Se supera questo limite, il join vienevelato.
PS_JOIN_ROUND	I join sono arrotondati.

[in] cWidth

Larghezza della penna. Se il parametro dwPenStyle è PS_GEOMETRIC, la larghezza viene specificata in unità logiche. Se dwPenStyle è PS_COSMETIC, la larghezza deve essere impostata su 1.

[in] plbrush

Puntatore a una struttura LOGBRUSH . Se dwPenStyle è PS_COSMETIC, il membro lbColor specifica il colore della penna e il membro lpStyle deve essere impostato su BS_SOLID. Se dwPenStyle è PS_GEOMETRIC, tutti i membri devono essere usati per specificare gli attributi del pennello della penna.

[in] cStyle

Lunghezza, nelle unità DWORD , della matrice lpStyle . Questo valore deve essere zero se dwPenStyle non è PS_USERSTYLE.

Il conteggio dello stile è limitato a 16.

[in] pstyle

Puntatore a una matrice. Il primo valore specifica la lunghezza del primo trattino in uno stile definito dall'utente, il secondo valore specifica la lunghezza del primo spazio e così via. Questo puntatore deve essere NULL se dwPenStyle non è PS_USERSTYLE.

Se la matrice lpStyle viene superata durante il disegno della linea, il puntatore viene reimpostato all'inizio della matrice. Quando si verifica e dwStyleCount è un numero pari, il modello di trattini e spazi si ripete. Tuttavia, se dwStyleCount è strano, il modello si inverte quando il puntatore viene reimpostato - il primo elemento di lpStyle ora fa riferimento a spazi, il secondo fa riferimento a trattini e così via.

Valore restituito

Se la funzione ha esito positivo, il valore restituito è un handle che identifica una penna logica.

Se la funzione ha esito negativo, il valore restituito è zero.

Commenti

Una penna geometrica può avere qualsiasi larghezza e può avere uno qualsiasi degli attributi di un pennello, ad esempio dithers e modelli. Una penna cosmetica può essere solo un singolo pixel wide e deve essere un colore a tinta unita, ma le penne cosmetiche sono generalmente più veloci rispetto alle penne geometriche.

La larghezza di una penna geometrica viene sempre specificata nelle unità mondiali. La larghezza di una penna cosmetica è sempre 1.

Le estremità e i join vengono specificati solo per le penne geometriche.

Dopo che un'applicazione crea una penna logica, può selezionare tale penna in un contesto di dispositivo chiamando la funzione SelectObject . Dopo aver selezionato una penna in un contesto di dispositivo, può essere usata per disegnare linee e curve.

Se dwPenStyle è PS_COSMETIC e PS_USERSTYLE, le voci nella matrice lpStyle specificano le lunghezze dei trattini e degli spazi nelle unità di stile. Un'unità di stile viene definita dal dispositivo in cui viene usata la penna per disegnare una linea.

Se dwPenStyle è PS_GEOMETRIC e PS_USERSTYLE, le voci nella matrice lpStyle specificano lunghezze di trattini e spazi in unità logiche.

Se dwPenStyle è PS_ALTERNATE, l'unità di stile viene ignorata e ogni altro pixel viene impostato.

Se il membro lbStyle della struttura LOGBRUSH a cui punta lplb è BS_PATTERN, la bitmap puntata al membro lbHatch di tale struttura non può essere una sezione DIB. Una sezione DIB è una bitmap creata da CreateDIBSection. Se la bitmap è una sezione DIB, la funzione ExtCreatePen ha esito negativo.

Quando un'applicazione non richiede più una penna specificata, deve chiamare la funzione DeleteObject per eliminare la penna.

ICM: Nessuna gestione dei colori viene eseguita alla creazione della penna. Tuttavia, la gestione dei colori viene eseguita quando la penna viene selezionata in un contesto di dispositivo abilitato per ICM.

Esempio

Per un esempio, vedere Uso di penne.

Requisiti


Client minimo supportato	Windows 2000 Professional [solo app desktop]
Server minimo supportato	Windows 2000 Server [solo app desktop]
Piattaforma di destinazione	Windows
Intestazione	wingdi.h (include Windows.h)
Libreria	Gdi32.lib
DLL	Gdi32.dll