.TH "libcaca canvas frame handling" 3caca "Fri Apr 6 2012" "Version 0.99.beta18" "libcaca" \" -*- nroff -*-
.ad l
.nh
.SH NAME
libcaca canvas frame handling \- 
.SS "Functions"

.in +1c
.ti -1c
.RI "__extern int \fBcaca_get_frame_count\fP (\fBcaca_canvas_t\fP const *)"
.br
.RI "\fIGet the number of frames in a canvas\&. \fP"
.ti -1c
.RI "__extern int \fBcaca_set_frame\fP (\fBcaca_canvas_t\fP *, int)"
.br
.RI "\fIActivate a given canvas frame\&. \fP"
.ti -1c
.RI "__extern char const * \fBcaca_get_frame_name\fP (\fBcaca_canvas_t\fP const *)"
.br
.RI "\fIGet the current frame's name\&. \fP"
.ti -1c
.RI "__extern int \fBcaca_set_frame_name\fP (\fBcaca_canvas_t\fP *, char const *)"
.br
.RI "\fISet the current frame's name\&. \fP"
.ti -1c
.RI "__extern int \fBcaca_create_frame\fP (\fBcaca_canvas_t\fP *, int)"
.br
.RI "\fIAdd a frame to a canvas\&. \fP"
.ti -1c
.RI "__extern int \fBcaca_free_frame\fP (\fBcaca_canvas_t\fP *, int)"
.br
.RI "\fIRemove a frame from a canvas\&. \fP"
.in -1c
.SH "Detailed Description"
.PP 
These functions provide high level routines for canvas frame insertion, removal, copying etc\&. 
.SH "Function Documentation"
.PP 
.SS "__extern int \fBcaca_get_frame_count\fP (\fBcaca_canvas_t\fP const *cv)"Return the current canvas' frame count\&.
.PP
This function never fails\&.
.PP
\fBParameters:\fP
.RS 4
\fIcv\fP A libcaca canvas 
.RE
.PP
\fBReturns:\fP
.RS 4
The frame count 
.RE
.PP

.PP
Referenced by caca_set_canvas_boundaries()\&.
.SS "__extern int \fBcaca_set_frame\fP (\fBcaca_canvas_t\fP *cv, intid)"Set the active canvas frame\&. All subsequent drawing operations will be performed on that frame\&. The current painting context set by \fBcaca_set_attr()\fP is inherited\&.
.PP
If the frame index is outside the canvas' frame range, nothing happens\&.
.PP
If an error occurs, -1 is returned and \fBerrno\fP is set accordingly:
.IP "\(bu" 2
\fCEINVAL\fP Requested frame is out of range\&.
.PP
.PP
\fBParameters:\fP
.RS 4
\fIcv\fP A libcaca canvas 
.br
\fIid\fP The canvas frame to activate 
.RE
.PP
\fBReturns:\fP
.RS 4
0 in case of success, -1 if an error occurred\&. 
.RE
.PP

.PP
References caca_add_dirty_rect()\&.
.PP
Referenced by caca_set_canvas_boundaries()\&.
.SS "__extern char const* \fBcaca_get_frame_name\fP (\fBcaca_canvas_t\fP const *cv)"Return the current frame's name\&. The returned string is valid until the frame is deleted or \fBcaca_set_frame_name()\fP is called to change the frame name again\&.
.PP
This function never fails\&.
.PP
\fBParameters:\fP
.RS 4
\fIcv\fP A libcaca canvas\&. 
.RE
.PP
\fBReturns:\fP
.RS 4
The current frame's name\&. 
.RE
.PP

.SS "__extern int \fBcaca_set_frame_name\fP (\fBcaca_canvas_t\fP *cv, char const *name)"Set the current frame's name\&. Upon creation, a frame has a default name of \fC'frame#xxxxxxxx'\fP where \fCxxxxxxxx\fP is a self-incrementing hexadecimal number\&.
.PP
If an error occurs, -1 is returned and \fBerrno\fP is set accordingly:
.IP "\(bu" 2
\fCENOMEM\fP Not enough memory to allocate new frame\&.
.PP
.PP
\fBParameters:\fP
.RS 4
\fIcv\fP A libcaca canvas\&. 
.br
\fIname\fP The name to give to the current frame\&. 
.RE
.PP
\fBReturns:\fP
.RS 4
0 in case of success, -1 if an error occurred\&. 
.RE
.PP

.SS "__extern int \fBcaca_create_frame\fP (\fBcaca_canvas_t\fP *cv, intid)"Create a new frame within the given canvas\&. Its contents and attributes are copied from the currently active frame\&.
.PP
The frame index indicates where the frame should be inserted\&. Valid values range from 0 to the current canvas frame count\&. If the frame index is greater than or equals the current canvas frame count, the new frame is appended at the end of the canvas\&. If the frame index is less than zero, the new frame is inserted at index 0\&.
.PP
The active frame does not change, but its index may be renumbered due to the insertion\&.
.PP
If an error occurs, -1 is returned and \fBerrno\fP is set accordingly:
.IP "\(bu" 2
\fCENOMEM\fP Not enough memory to allocate new frame\&.
.PP
.PP
\fBParameters:\fP
.RS 4
\fIcv\fP A libcaca canvas 
.br
\fIid\fP The index where to insert the new frame 
.RE
.PP
\fBReturns:\fP
.RS 4
0 in case of success, -1 if an error occurred\&. 
.RE
.PP

.PP
Referenced by caca_set_canvas_boundaries()\&.
.SS "__extern int \fBcaca_free_frame\fP (\fBcaca_canvas_t\fP *cv, intid)"Delete a frame from a given canvas\&.
.PP
The frame index indicates the frame to delete\&. Valid values range from 0 to the current canvas frame count minus 1\&. If the frame index is greater than or equals the current canvas frame count, the last frame is deleted\&.
.PP
If the active frame is deleted, frame 0 becomes the new active frame\&. Otherwise, the active frame does not change, but its index may be renumbered due to the deletion\&.
.PP
If an error occurs, -1 is returned and \fBerrno\fP is set accordingly:
.IP "\(bu" 2
\fCEINVAL\fP Requested frame is out of range, or attempt to delete the last frame of the canvas\&.
.PP
.PP
\fBParameters:\fP
.RS 4
\fIcv\fP A libcaca canvas 
.br
\fIid\fP The index of the frame to delete 
.RE
.PP
\fBReturns:\fP
.RS 4
0 in case of success, -1 if an error occurred\&. 
.RE
.PP

.PP
References caca_add_dirty_rect()\&.
.SH "Author"
.PP 
Generated automatically by Doxygen for libcaca from the source code\&.