Name
GetFreePen -- find unused pen (V10.0)
Synopsis
pen = GetFreePen([t])
Function
This function tries to find an unused pen in the currently active palette image and returns it. If all pens are used, -1 will be returned. By default, this function scans the palette pixel data of the current display so it will only work if the current display is a palette mode display. See Palette mode displays for details. If you don't want GetFreePen() to use the current display, you can select the active palette image using the SelectPalette() command but keep in mind that you need to select a palette object that has pixel data attached, e.g. a palette brush or a palette BGPic. Just selecting a palette object won't work because free pens can obviously only be determined if there's pixel data.

You can also use the optional table argument t to specify the source palette object. The table argument supports exactly the same arguments as the optional table argument of GetPen(). See GetPen for details.

Inputs
t
optional: table for specifying further options (see above)
Results
pen
unused pen index or -1 if all pens are in use
Show TOC