CloneTextCel

Clones an existing text cel.

Synopsis

TextCel * CloneTextCel (TextCel *templateTextCel, Boolean clonePixels)

Description

Creates a new TextCel using a TextCel that already exists as a template. If clonePixels is FALSE, the new TextCel contains no text; if TRUE, the pixels from the template TextCel are copied into the new TextCel.

If the template cel has a format buffer attached to it, and that buffer was dynamically allocated by the call to SetTextCelFormatBuffer(), a new buffer of the same size is allocated and attached to the new cel. If the template cel has a format buffer that you provided explicitly (a static buffer), the new cel will use the same static buffer.

This function is useful when you want to create a number of identical TextCels. You can call CreateTextCel(), followed by whatever SetTextCel...() functions you need to create a template cel with a given size and attributes, then call CloneTextCel() as often as necessary to create a number of cels with identical size and attributes.

Use DeleteTextCel() to dispose of the TextCel when you are finished with it.

Arguments

templateTextCel: Pointer to the TextCel structure you want to clone.

clonePixels: TRUE if the new TextCel is to contain the same pixels as those currently in the template TextCel.

Return Value

Pointer to the newly created TextCel structure; NULL if there isn't enough memory to create the new TextCel.

Associated Files