libcaca  0.99.beta19
About: libcaca is a graphics library that outputs text instead of pixels, so that it can work on older video cards or text terminals (something like an advanced AAlib library).
  Fossies Dox: libcaca-0.99.beta19.tar.gz  ("inofficial" and yet experimental doxygen-generated source code documentation)  

libcaca canvas frame handling

These functions provide high level routines for canvas frame insertion, removal, copying etc. More...

Functions

int caca_get_frame_count (caca_canvas_t const *)
 Get the number of frames in a canvas. More...
 
int caca_set_frame (caca_canvas_t *, int)
 Activate a given canvas frame. More...
 
const char * caca_get_frame_name (caca_canvas_t const *)
 Get the current frame's name. More...
 
int caca_set_frame_name (caca_canvas_t *, char const *)
 Set the current frame's name. More...
 
int caca_create_frame (caca_canvas_t *, int)
 Add a frame to a canvas. More...
 
int caca_free_frame (caca_canvas_t *, int)
 Remove a frame from a canvas. More...
 

Detailed Description

These functions provide high level routines for canvas frame insertion, removal, copying etc.

Function Documentation

◆ caca_create_frame()

int caca_create_frame ( caca_canvas_t ,
int   
)

Add a frame to a canvas.

Create a new frame within the given canvas. Its contents and attributes are copied from the currently active frame.

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.

The active frame does not change, but its index may be renumbered due to the insertion.

If an error occurs, -1 is returned and errno is set accordingly:

  • ENOMEM Not enough memory to allocate new frame.
Parameters
cvA libcaca canvas
idThe index where to insert the new frame
Returns
0 in case of success, -1 if an error occurred.

Definition at line 145 of file frame.c.

References attrs, caca_canvas::attrs, caca_canvas::autoinc, chars, caca_canvas::chars, curattr, caca_canvas::curattr, cv, caca_canvas::frame, caca_canvas::framecount, caca_canvas::frames, handlex, handley, height, caca_canvas::height, name, width, caca_canvas::width, x, and y.

Referenced by _import_ansi(), caca_set_canvas_boundaries(), create_frame(), Canvas::createFrame(), cucul_create_canvas_frame(), Canvas::freeFrame(), import_caca(), and Java_org_zoy_caca_Canvas_createCanvasFrame().

◆ caca_free_frame()

int caca_free_frame ( caca_canvas_t ,
int   
)

Remove a frame from a canvas.

Delete a frame from a given canvas.

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.

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.

If an error occurs, -1 is returned and errno is set accordingly:

  • EINVAL Requested frame is out of range, or attempt to delete the last frame of the canvas.
Parameters
cvA libcaca canvas
idThe index of the frame to delete
Returns
0 in case of success, -1 if an error occurred.

Definition at line 205 of file frame.c.

References _caca_load_frame_info(), attrs, caca_add_dirty_rect(), chars, cv, caca_canvas::dirty_disabled, caca_canvas::frame, caca_canvas::framecount, caca_canvas::frames, caca_canvas::height, name, seterrno, and caca_canvas::width.

Referenced by cucul_free_canvas_frame(), free_frame(), import_caca(), and Java_org_zoy_caca_Canvas_freeCanvasFrame().

◆ caca_get_frame_count()

int caca_get_frame_count ( caca_canvas_t const *  )

Get the number of frames in a canvas.

Return the current canvas' frame count.

This function never fails.

Parameters
cvA libcaca canvas
Returns
The frame count

Definition at line 37 of file frame.c.

References cv, and caca_canvas::framecount.

Referenced by _import_ansi(), caca_set_canvas_boundaries(), cucul_get_canvas_frame_count(), Canvas::getFrameCount(), import_caca(), and Java_org_zoy_caca_Canvas_getCanvasFrameCount().

◆ caca_get_frame_name()

const char * caca_get_frame_name ( caca_canvas_t const *  )

Get the current frame's name.

Return the current frame's name. The returned string is valid until the frame is deleted or caca_set_frame_name() is called to change the frame name again.

This function never fails.

Parameters
cvA libcaca canvas.
Returns
The current frame's name.

Definition at line 90 of file frame.c.

References cv, caca_canvas::frame, caca_canvas::frames, and name.

Referenced by get_frame_name(), and Java_org_zoy_caca_Canvas_getCanvasFrameName().

◆ caca_set_frame()

int caca_set_frame ( caca_canvas_t ,
int   
)

Activate a given canvas frame.

Set the active canvas frame. All subsequent drawing operations will be performed on that frame. The current painting context set by caca_set_attr() is inherited.

If the frame index is outside the canvas' frame range, nothing happens.

If an error occurs, -1 is returned and errno is set accordingly:

  • EINVAL Requested frame is out of range.
Parameters
cvA libcaca canvas
idThe canvas frame to activate
Returns
0 in case of success, -1 if an error occurred.

Definition at line 57 of file frame.c.

References _caca_load_frame_info(), _caca_save_frame_info(), caca_add_dirty_rect(), cv, caca_canvas::dirty_disabled, caca_canvas::frame, caca_canvas::framecount, caca_canvas::height, seterrno, and caca_canvas::width.

Referenced by _import_ansi(), caca_set_canvas_boundaries(), cucul_set_canvas_frame(), import_caca(), Java_org_zoy_caca_Canvas_setCanvasFrame(), set_frame(), and Canvas::setFrame().

◆ caca_set_frame_name()

int caca_set_frame_name ( caca_canvas_t ,
char const *   
)

Set the current frame's name.

Set the current frame's name. Upon creation, a frame has a default name of "frame#xxxxxxxx" where xxxxxxxx is a self-incrementing hexadecimal number.

If an error occurs, -1 is returned and errno is set accordingly:

  • ENOMEM Not enough memory to allocate new frame.
Parameters
cvA libcaca canvas.
nameThe name to give to the current frame.
Returns
0 in case of success, -1 if an error occurred.

Definition at line 108 of file frame.c.

References cv, caca_canvas::frame, caca_canvas::frames, setup::name, name, and seterrno.

Referenced by Java_org_zoy_caca_Canvas_setCanvasFrameName(), and set_frame_name().