frame

libcucul canvas frame handling(3cacalibcalibcucul canvas frame handling(3caca)



NAME
       libcucul canvas frame handling -

   Functions
       unsigned int cucul_get_frame_count (cucul_canvas_t *)
           Get the number of frames in a canvas.
       int cucul_set_frame (cucul_canvas_t *, unsigned int)
           Activate a given canvas frame.
       char const * cucul_get_frame_name (cucul_canvas_t *)
           Get the current frame's name.
       int cucul_set_frame_name (cucul_canvas_t *, char const *)
           Set the current frame's name.
       int cucul_create_frame (cucul_canvas_t *, unsigned int)
           Add a frame to a canvas.
       int cucul_free_frame (cucul_canvas_t *, unsigned int)
           Remove a frame from a canvas.

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

Function Documentation
   unsigned int cucul_get_frame_count (cucul_canvas_t * cv)
       Return the current canvas' frame count.

       This function never fails.

       Parameters:
           cv A libcucul canvas

       Returns:
           The frame count

       Referenced by cucul_set_canvas_boundaries().

   int cucul_set_frame (cucul_canvas_t * cv, unsigned int id)
       Set the active canvas frame. All subsequent drawing operations will be
       performed on that frame. The current painting context set by
       cucul_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:
           cv A libcucul canvas
           id The canvas frame to activate

       Returns:
           0 in case of success, -1 if an error occurred.

       Referenced by cucul_set_canvas_boundaries().

   char const* cucul_get_frame_name (cucul_canvas_t * cv)
       Return the current frame's name. The returned string is valid until the
       frame is deleted or cucul_set_frame_name() is called to change the
       frame name again.

       This function never fails.

       Parameters:
           cv A libcucul canvas.

       Returns:
           The current frame's name.

   int cucul_set_frame_name (cucul_canvas_t * cv, char const * 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:
           cv A libcucul canvas.
           name The name to give to the current frame.

       Returns:
           0 in case of success, -1 if an error occurred.

   int cucul_create_frame (cucul_canvas_t * cv, unsigned int id)
       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.

       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:
           cv A libcucul canvas
           id The index where to insert the new frame

       Returns:
           0 in case of success, -1 if an error occurred.

       Referenced by cucul_set_canvas_boundaries().

   int cucul_free_frame (cucul_canvas_t * cv, unsigned int id)
       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 the 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:
           cv A libcucul canvas
           id The index of the frame to delete

       Returns:
           0 in case of success, -1 if an error occurred.

Version 0.99.beta11               21 Feb libcucul canvas frame handling(3caca)