diff --git a/caca/caca.h b/caca/caca.h index 9364af0..05ca598 100644 --- a/caca/caca.h +++ b/caca/caca.h @@ -66,6 +66,7 @@ typedef struct caca_event caca_event_t; * Colours and styles that can be used with caca_set_attr(). * * @{ */ +/** \e libcaca colour keyword */ enum caca_color { CACA_BLACK = 0x00, /**< The colour index for black. */ @@ -88,6 +89,7 @@ enum caca_color CACA_TRANSPARENT = 0x20, /**< The transparent colour. */ }; +/** \e libcaca style keyword */ enum caca_style { CACA_BOLD = 0x01, /**< The style mask for bold. */ @@ -127,14 +129,16 @@ enum caca_event_type */ struct caca_event { - enum caca_event_type type; + enum caca_event_type type; /**< The event type. */ union { struct { int x, y, button; } mouse; struct { int w, h; } resize; struct { int ch; uint32_t utf32; char utf8[8]; } key; - } data; + } data; /**< The event information data */ +#if !defined(_DOXYGEN_SKIP_ME) uint8_t padding[16]; +#endif }; /** \brief Special key values. @@ -568,18 +572,18 @@ enum CACA_CONIO_MODE */ struct caca_conio_text_info { - unsigned char winleft; /* left window coordinate */ - unsigned char wintop; /* top window coordinate */ - unsigned char winright; /* right window coordinate */ - unsigned char winbottom; /* bottom window coordinate */ - unsigned char attribute; /* text attribute */ - unsigned char normattr; /* normal attribute */ - unsigned char currmode; /* current video mode: - BW40, BW80, C40, C80, or C4350 */ - unsigned char screenheight; /* text screen's height */ - unsigned char screenwidth; /* text screen's width */ - unsigned char curx; /* x-coordinate in current window */ - unsigned char cury; /* y-coordinate in current window */ + unsigned char winleft; /**< left window coordinate */ + unsigned char wintop; /**< top window coordinate */ + unsigned char winright; /**< right window coordinate */ + unsigned char winbottom; /**< bottom window coordinate */ + unsigned char attribute; /**< text attribute */ + unsigned char normattr; /**< normal attribute */ + unsigned char currmode; /**< current video mode: + BW40, BW80, C40, C80, or C4350 */ + unsigned char screenheight; /**< text screen's height */ + unsigned char screenwidth; /**< text screen's width */ + unsigned char curx; /**< x-coordinate in current window */ + unsigned char cury; /**< y-coordinate in current window */ }; /** \brief DOS direct video control */ diff --git a/caca/file.c b/caca/file.c index ed33e57..18d4ce4 100644 --- a/caca/file.c +++ b/caca/file.c @@ -50,6 +50,19 @@ struct caca_file }; #endif +/** \brief Open a file for reading or writing + * + * Create a caca file handle for a file. If the file is zipped, it is + * decompressed on the fly. + * + * If an error occurs, NULL is returned and \b errno is set accordingly: + * - \c ENOSTS Function not implemented. + * - \c EINVAL File not found or permission denied. + * + * \param path The file path + * \param mode The file open mode + * \return A file handle to \e path. + */ caca_file_t *caca_file_open(char const *path, const char *mode) { #if defined __KERNEL__ @@ -68,6 +81,7 @@ caca_file_t *caca_file_open(char const *path, const char *mode) if(!fp->gz) { free(fp); + seterrno(EINVAL); return NULL; } @@ -108,6 +122,7 @@ caca_file_t *caca_file_open(char const *path, const char *mode) { free(fp); gzclose(fp->gz); + seterrno(EINVAL); return NULL; } } @@ -117,6 +132,7 @@ caca_file_t *caca_file_open(char const *path, const char *mode) if(!fp->f) { free(fp); + seterrno(EINVAL); return NULL; } # endif @@ -125,6 +141,15 @@ caca_file_t *caca_file_open(char const *path, const char *mode) #endif } +/** \brief Close a file handle + * + * Close and destroy the resources associated with a caca file handle. + * + * This function is a wrapper for fclose() or, if available, gzclose(). + * + * \param fp The file handle + * \return The return value of fclose() or gzclose(). + */ int caca_file_close(caca_file_t *fp) { #if defined __KERNEL__ @@ -143,6 +168,13 @@ int caca_file_close(caca_file_t *fp) #endif } +/** \brief Return the position in a file handle + * + * Return the file handle position, in bytes. + * + * \param fp The file handle + * \return The current offset in the file handle. + */ uint64_t caca_file_tell(caca_file_t *fp) { #if defined __KERNEL__ @@ -157,6 +189,15 @@ uint64_t caca_file_tell(caca_file_t *fp) #endif } +/** \brief Read data from a file handle + * + * Read data from a file handle and copy them into the given buffer. + * + * \param fp The file handle + * \param ptr The destination buffer + * \param size The number of bytes to read + * \return The number of bytes read + */ size_t caca_file_read(caca_file_t *fp, void *ptr, size_t size) { #if defined __KERNEL__ @@ -171,6 +212,15 @@ size_t caca_file_read(caca_file_t *fp, void *ptr, size_t size) #endif } +/** \brief Write data to a file handle + * + * Write the contents of the given buffer to the file handle. + * + * \param fp The file handle + * \param ptr The source buffer + * \param size The number of bytes to write + * \return The number of bytes written + */ size_t caca_file_write(caca_file_t *fp, const void *ptr, size_t size) { #if defined __KERNEL__ @@ -194,6 +244,16 @@ size_t caca_file_write(caca_file_t *fp, const void *ptr, size_t size) #endif } +/** \brief Read a line from a file handle + * + * Read one line of data from a file handle, up to one less than the given + * number of bytes. A trailing zero is appended to the data. + * + * \param fp The file handle + * \param s The destination buffer + * \param size The maximum number of bytes to read + * \return The number of bytes read, including the trailing zero + */ char *caca_file_gets(caca_file_t *fp, char *s, int size) { #if defined __KERNEL__ @@ -228,6 +288,15 @@ char *caca_file_gets(caca_file_t *fp, char *s, int size) #endif } +/** \brief Tell whether a file handle reached end of file + * + * Return the end-of-file status of the file handle. + * + * This function is a wrapper for feof() or, if available, gzeof(). + * + * \param fp The file handle + * \return 1 if EOF was reached, 0 otherwise + */ int caca_file_eof(caca_file_t *fp) { #if defined __KERNEL__ diff --git a/caca/string.c b/caca/string.c index 2b890f1..0b402a8 100644 --- a/caca/string.c +++ b/caca/string.c @@ -325,7 +325,7 @@ int caca_printf(caca_canvas_t *cv, int x, int y, char const *format, ...) * \param x X coordinate. * \param y Y coordinate. * \param format The format string to print. - * \param ap A va_list containting the arguments to the format string. + * \param args A va_list containting the arguments to the format string. * \return The number of cells printed. */ int caca_vprintf(caca_canvas_t *cv, int x, int y, char const *format, diff --git a/win32/config.h b/win32/config.h index 088c943..e5d2118 100644 --- a/win32/config.h +++ b/win32/config.h @@ -80,6 +80,7 @@ /* #undef USE_CONIO */ /* #undef USE_GL */ /* #undef USE_IMLIB2 */ +/* #undef USE_KERNEL */ /* #undef USE_NCURSES */ /* #undef USE_PLUGINS */ /* #undef USE_SLANG */