From c09f5819c24221867628a9b645cc871b362c469e Mon Sep 17 00:00:00 2001 From: Yves Rizoud Date: Sat, 18 Apr 2009 19:58:19 +0000 Subject: [PATCH] Doxygen documentation for text.h, SFont.h, setup.h, realpath.h, readline.h, palette.h, keyboard.h, io.h, input.h, hotkeys.h, helpfile.h, errors.h; and a basic description for all other headers. Removed 2 unused function prototypes (They escaped translation) In each C file, added a #include of its own header, to help doxygen generate a more complete documentation for the C files (and also double-check function prototypes) All these changes don't change the generated executable, it's still beta 99.0. git-svn-id: svn://pulkomandy.tk/GrafX2/trunk@752 416bcca6-2ee7-4201-b75f-2eb2f807beb1 --- SFont.h | 44 ++++++++++++++-------- brush.c | 1 + brush.h | 5 +++ buttons.h | 5 +++ const.h | 1 + engine.h | 5 +++ errors.h | 20 ++++++++-- filesel.c | 1 + filesel.h | 5 +++ graph.h | 5 +++ help.h | 9 ++++- helpfile.h | 106 +++++++++++++++++++++++++++++----------------------- hotkeys.h | 30 +++++++++++---- init.c | 1 + init.h | 6 +++ input.h | 16 ++++++++ io.h | 44 ++++++++++++++++++---- keyboard.c | 1 + keyboard.h | 24 +++++++++++- loadsave.h | 31 +++++++++++---- misc.h | 8 ++-- mountlist.h | 6 +++ op_c.h | 8 ++++ operatio.h | 9 +++++ pages.h | 6 +++ palette.c | 1 + palette.h | 14 +++++-- pxdouble.c | 1 + pxdouble.h | 6 +++ pxsimple.c | 1 + pxsimple.h | 6 +++ pxtall.c | 1 + pxtall.h | 6 +++ pxwide.c | 1 + pxwide.h | 6 +++ readini.c | 1 + readini.h | 6 +++ readline.h | 39 +++++++++++-------- realpath.h | 30 +++++++++++++++ saveini.c | 1 + saveini.h | 6 +++ sdlscreen.h | 6 +++ setup.c | 1 + setup.h | 29 ++++++++++++++ shade.c | 1 + shade.h | 6 +++ special.c | 1 + special.h | 7 ++++ text.h | 36 +++++++++++++----- windows.h | 5 +++ 50 files changed, 493 insertions(+), 122 deletions(-) diff --git a/SFont.h b/SFont.h index 568c44df..8f90b443 100644 --- a/SFont.h +++ b/SFont.h @@ -33,6 +33,13 @@ * contact me, if you problem isn' addressed anywhere. * * * ************************************************************************/ +////////////////////////////////////////////////////////////////////////////// +///@file SFont.h +/// Text rendering system, that uses bitmaps as fonts. +/// Not specific to Grafx2, it writes to SDL_Surface. +////////////////////////////////////////////////////////////////////////////// + + #ifndef _SFONT_H_ #define _SFONT_H_ @@ -42,37 +49,44 @@ extern "C" { #endif -// Delcare one variable of this type for each font you are using. -// To load the fonts, load the font image into YourFont->Surface -// and call InitFont( YourFont ); +/// +/// Declare one variable of this type for each font you are using. +/// To load the fonts, load the font image into YourFont->Surface +/// and call InitFont( YourFont ); typedef struct { SDL_Surface *Surface; int CharPos[512]; int MaxPos; } SFont_Font; -// Initializes the font -// Font: this contains the suface with the font. -// The Surface must be loaded before calling this function +/// +/// Initializes the font. +/// @param Font this contains the suface with the font. +/// The Surface must be loaded before calling this function SFont_Font* SFont_InitFont (SDL_Surface *Font); -// Frees the font -// Font: The font to free -// The font must be loaded before using this function. +/// +/// Frees the font. +/// @param Font The font to free +/// The font must be loaded before using this function. void SFont_FreeFont(SFont_Font* Font); -// Blits a string to a surface -// Destination: the suface you want to blit to -// text: a string containing the text you want to blit. +/// +/// Blits a string to a surface. +/// @param Surface The surface you want to blit to. +/// @param Font The font to use. +/// @param text A string containing the text you want to blit. +/// @param x Coordinates to start drawing. +/// @param y Coordinates to start drawing. void SFont_Write(SDL_Surface *Surface, const SFont_Font *Font, int x, int y, const char *text); -// Returns the width of "text" in pixels +/// Returns the width of "text" in pixels int SFont_TextWidth(const SFont_Font* Font, const char *text); -// Returns the height of "text" in pixels (which is always equal to Font->Surface->h) +/// Returns the height of "text" in pixels (which is always equal to Font->Surface->h) int SFont_TextHeight(const SFont_Font* Font); -// Blits a string to Surface with centered x position +/// Blits a string to Surface with centered x position void SFont_WriteCenter(SDL_Surface *Surface, const SFont_Font* Font, int y, const char *text); diff --git a/brush.c b/brush.c index 089b207c..c3f33ccc 100644 --- a/brush.c +++ b/brush.c @@ -34,6 +34,7 @@ #include "errors.h" #include "windows.h" #include "sdlscreen.h" +#include "brush.h" // Calcul de redimensionnement du pinceau pour éviter les débordements de // l'écran et de l'image diff --git a/brush.h b/brush.h index ab9a5217..8ffba112 100644 --- a/brush.h +++ b/brush.h @@ -19,6 +19,11 @@ 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. */ +////////////////////////////////////////////////////////////////////////////// +///@file brush.h +/// Actions on the brush. +////////////////////////////////////////////////////////////////////////////// + #ifndef __BRUSH_H_ #define __BRUSH_H_ diff --git a/buttons.h b/buttons.h index 94cb74b5..816957ee 100644 --- a/buttons.h +++ b/buttons.h @@ -19,6 +19,11 @@ 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. */ +////////////////////////////////////////////////////////////////////////////// +///@file buttons.h +/// Almost all the editor actions that are called by the menu are here. +////////////////////////////////////////////////////////////////////////////// + #ifndef __BOUTONS_H_ #define __BOUTONS_H_ diff --git a/const.h b/const.h index 4fbf7841..9e085838 100644 --- a/const.h +++ b/const.h @@ -24,6 +24,7 @@ ///@file const.h /// Constants (preprocessor defines) and enumerations used anywhere. ////////////////////////////////////////////////////////////////////////////// + #ifndef _CONST_H_ #define _CONST_H_ diff --git a/engine.h b/engine.h index 6fe45890..ac579b0c 100644 --- a/engine.h +++ b/engine.h @@ -19,6 +19,11 @@ 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. */ +////////////////////////////////////////////////////////////////////////////// +///@file engine.h +/// Utility functions for the menu and all windows. +////////////////////////////////////////////////////////////////////////////// + void Main_handler (void); void Draw_menu_button_frame(byte btn_number,byte pressed); void Unselect_bouton (int btn_number); diff --git a/errors.h b/errors.h index 4949b1f7..c1b1b9f5 100644 --- a/errors.h +++ b/errors.h @@ -17,16 +17,30 @@ write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. */ -// Affiche nom fichier, n° ligne, nom fonction, une chaine et un entier. + +////////////////////////////////////////////////////////////////////////////// +///@file errors.h +/// Functions and macros for tracing and error reporting. +////////////////////////////////////////////////////////////////////////////// + +/// Prints the source filename, line number, function name, a string and an integer. #define DEBUG(y,z) printf("%s %d %s | %s : %d###\n",__FILE__,__LINE__,__func__,y,(unsigned int)z) -// DEBUG en hexadécimal +/// Same as ::DEBUG but in hexadecimal #define DEBUGX(y,z) printf("%s %d %s | %s : %X###\n",__FILE__,__LINE__,__func__,y,(unsigned int)z) +/// Macro to report unimplemented functions. #define UNIMPLEMENTED printf("%s %d %s non implémenté !\n",__FILE__,__LINE__,__func__); +/// Macro to report untested functions. #define UNTESTED printf("%s %d %s à tester !\n",__FILE__,__LINE__,__func__); +/// Helper function used by the macro ::Error void Error_function(int error_code, const char *filename, int line_number, const char *function_name); -#define Error(n) Error_function(n, __FILE__,__LINE__,__func__) +/// +/// Report a run-time error: It will print to standard output some information +/// about the calling function, and then: +/// - If the error code is 0, just do a red screen flash and resume. +/// - If the error code is non-zero, abort the program. +#define Error(n) Error_function(n, __FILE__,__LINE__,__func__) diff --git a/filesel.c b/filesel.c index 1f9d4c89..55b74bea 100644 --- a/filesel.c +++ b/filesel.c @@ -56,6 +56,7 @@ #include "readline.h" #include "input.h" #include "help.h" +#include "filesel.h" #define NORMAL_FILE_COLOR MC_Light // color du texte pour une ligne de fichier non sélectionné #define NORMAL_DIRECTORY_COLOR MC_Dark // color du texte pour une ligne de répertoire non sélectionné diff --git a/filesel.h b/filesel.h index 4eb14a06..62873276 100644 --- a/filesel.h +++ b/filesel.h @@ -19,4 +19,9 @@ 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. */ +////////////////////////////////////////////////////////////////////////////// +///@file filesel.h +/// Fileselector window, used for loading and saving images and brushes. +////////////////////////////////////////////////////////////////////////////// + byte Button_Load_or_Save(byte load, byte image); diff --git a/graph.h b/graph.h index b52f0105..acc0c4a3 100644 --- a/graph.h +++ b/graph.h @@ -19,6 +19,11 @@ 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. */ +////////////////////////////////////////////////////////////////////////////// +///@file graph.h +/// Graphic functions that target the screen and/or image. +////////////////////////////////////////////////////////////////////////////// + void Shade_list_to_lookup_tables(word * list, short step, byte mode, byte * table_inc, byte * table_dec ); diff --git a/help.h b/help.h index 4b08ab9c..63988948 100644 --- a/help.h +++ b/help.h @@ -19,8 +19,13 @@ 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. */ -#ifndef __AIDE_H_ -#define __AIDE_H_ +////////////////////////////////////////////////////////////////////////////// +///@file help.h +/// Functions related to the help browser. The help data is in helpfile.h +////////////////////////////////////////////////////////////////////////////// + +#ifndef __HELP_H_ +#define __HELP_H_ /*! Called to open the help window with the keyboard shortcut. diff --git a/helpfile.h b/helpfile.h index 83882786..eaf8a553 100644 --- a/helpfile.h +++ b/helpfile.h @@ -19,26 +19,38 @@ 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. */ -#include "const.h" // Utilise les enumerations BOUTON_ et SPECIAL_ +////////////////////////////////////////////////////////////////////////////// +///@file helpfile.h +/// This is all the text that appears in contextual help and credits. +/// +/// Note: The source code is kept on a public website, so keep this in mind +/// if you're thinking of putting an e-mail address in there. At least, use +/// "\100" instead of @, to help against the most basic email address harversters. +////////////////////////////////////////////////////////////////////////////// + +#include "const.h" // Uses enumerations BUTTON_NUMBERS and SPECIAL_ACTIONS + +// Some magic formulas: -// Quelques formules magiques: #define HELP_TEXT(x) {'N', x, 0}, -// Génère une ligne 'N' (Normale) +// Generates a 'N' line (Normal) #define HELP_LINK(x,y) {'K', x, y}, -// Génère une ligne 'K' (Key) +// Generates a 'K' line (Key) #define HELP_BOLD(x) {'S', x, 0}, -// Génère une ligne 'S' (BOLD) +// Generates a 'S' line (BOLD) #define HELP_TITLE(x) {'T', x, 0}, {'-', x, 0}, -// Génère une ligne 'T' (Titre partie haute) -// et une deuxième '-' (Titre partie basse) -// (pour gérer les gros titres qui occupent deux lignes) +// Generates a 'T' line (Title, upper half) +// and a second '-' line (Title, lower half), with the same text. static const T_Help_table helptable_about[] = /* + Do not exceed 44 characters for normal lines: HELP_TEXT ("--------------------------------------------") + Do not exceed 22 characters for title lines: + HELP_TITLE("======================") */ { HELP_TEXT ("") // Laisse de la place pour le logo @@ -2215,43 +2227,43 @@ T_Help_section Help_section[] = HELP_TABLE_DECLARATION(helptable_help) HELP_TABLE_DECLARATION(helptable_credits) - // Attention, dans l'ordre de BUTTON_NUMBERS - HELP_TABLE_DECLARATION(helptable_paintbrush ) - HELP_TABLE_DECLARATION(helptable_adjust ) - HELP_TABLE_DECLARATION(helptable_draw ) - HELP_TABLE_DECLARATION(helptable_curves ) - HELP_TABLE_DECLARATION(helptable_lines ) - HELP_TABLE_DECLARATION(helptable_airbrush ) - HELP_TABLE_DECLARATION(helptable_floodfill ) - HELP_TABLE_DECLARATION(helptable_polygons ) - HELP_TABLE_DECLARATION(helptable_polyfill ) - HELP_TABLE_DECLARATION(helptable_rectangles ) - HELP_TABLE_DECLARATION(helptable_filled_rectangles ) - HELP_TABLE_DECLARATION(helptable_circles ) - HELP_TABLE_DECLARATION(helptable_filled_circles ) - HELP_TABLE_DECLARATION(helptable_grad_rect ) - HELP_TABLE_DECLARATION(helptable_grad_menu ) - HELP_TABLE_DECLARATION(helptable_spheres ) - HELP_TABLE_DECLARATION(helptable_brush ) - HELP_TABLE_DECLARATION(helptable_polybrush ) - HELP_TABLE_DECLARATION(helptable_brush_fx ) - HELP_TABLE_DECLARATION(helptable_effects ) - HELP_TABLE_DECLARATION(helptable_text ) - HELP_TABLE_DECLARATION(helptable_magnifier ) - HELP_TABLE_DECLARATION(helptable_colorpicker ) - HELP_TABLE_DECLARATION(helptable_resolution ) - HELP_TABLE_DECLARATION(helptable_page ) - HELP_TABLE_DECLARATION(helptable_save ) - HELP_TABLE_DECLARATION(helptable_load ) - HELP_TABLE_DECLARATION(helptable_settings ) - HELP_TABLE_DECLARATION(helptable_clear ) - HELP_TABLE_DECLARATION(helptable_general ) - HELP_TABLE_DECLARATION(helptable_undo ) - HELP_TABLE_DECLARATION(helptable_kill ) - HELP_TABLE_DECLARATION(helptable_quit ) - HELP_TABLE_DECLARATION(helptable_palette ) - HELP_TABLE_DECLARATION(helptable_pal_scroll ) - HELP_TABLE_DECLARATION(helptable_pal_scroll ) - HELP_TABLE_DECLARATION(helptable_color_select ) - HELP_TABLE_DECLARATION(helptable_hide ) + // Attention, keep the same order as BUTTON_NUMBERS: + HELP_TABLE_DECLARATION(helptable_paintbrush) + HELP_TABLE_DECLARATION(helptable_adjust) + HELP_TABLE_DECLARATION(helptable_draw) + HELP_TABLE_DECLARATION(helptable_curves) + HELP_TABLE_DECLARATION(helptable_lines) + HELP_TABLE_DECLARATION(helptable_airbrush) + HELP_TABLE_DECLARATION(helptable_floodfill) + HELP_TABLE_DECLARATION(helptable_polygons) + HELP_TABLE_DECLARATION(helptable_polyfill) + HELP_TABLE_DECLARATION(helptable_rectangles) + HELP_TABLE_DECLARATION(helptable_filled_rectangles) + HELP_TABLE_DECLARATION(helptable_circles) + HELP_TABLE_DECLARATION(helptable_filled_circles) + HELP_TABLE_DECLARATION(helptable_grad_rect) + HELP_TABLE_DECLARATION(helptable_grad_menu) + HELP_TABLE_DECLARATION(helptable_spheres) + HELP_TABLE_DECLARATION(helptable_brush) + HELP_TABLE_DECLARATION(helptable_polybrush) + HELP_TABLE_DECLARATION(helptable_brush_fx) + HELP_TABLE_DECLARATION(helptable_effects) + HELP_TABLE_DECLARATION(helptable_text) + HELP_TABLE_DECLARATION(helptable_magnifier) + HELP_TABLE_DECLARATION(helptable_colorpicker) + HELP_TABLE_DECLARATION(helptable_resolution) + HELP_TABLE_DECLARATION(helptable_page) + HELP_TABLE_DECLARATION(helptable_save) + HELP_TABLE_DECLARATION(helptable_load) + HELP_TABLE_DECLARATION(helptable_settings) + HELP_TABLE_DECLARATION(helptable_clear) + HELP_TABLE_DECLARATION(helptable_general) + HELP_TABLE_DECLARATION(helptable_undo) + HELP_TABLE_DECLARATION(helptable_kill) + HELP_TABLE_DECLARATION(helptable_quit) + HELP_TABLE_DECLARATION(helptable_palette) + HELP_TABLE_DECLARATION(helptable_pal_scroll) + HELP_TABLE_DECLARATION(helptable_pal_scroll) + HELP_TABLE_DECLARATION(helptable_color_select) + HELP_TABLE_DECLARATION(helptable_hide) }; diff --git a/hotkeys.h b/hotkeys.h index 29576b4c..8b77c401 100644 --- a/hotkeys.h +++ b/hotkeys.h @@ -19,6 +19,13 @@ write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. */ + +////////////////////////////////////////////////////////////////////////////// +///@file hotkeys.h +/// Definition of the tables used by the keyboard shortcuts. +/// The actual data is in hotkeys.c +////////////////////////////////////////////////////////////////////////////// + #include #include @@ -26,15 +33,22 @@ typedef struct { - word Number; - char Label[36]; - char Explic1[37]; - char Explic2[37]; - char Explic3[37]; - bool Suppr; // Shortcut facultatif - word Key; - word Key2; + word Number; ///< Identifier for shortcut. This is a number starting from 0, which matches ::T_Config_shortcut_info.Number + char Label[36]; ///< Text to show in the screen where you can edit the shortcut. + char Explic1[37]; ///< Explanation text (1/3) to show in the screen where you can edit the shortcut. + char Explic2[37]; ///< Explanation text (2/3) to show in the screen where you can edit the shortcut. + char Explic3[37]; ///< Explanation text (3/3) to show in the screen where you can edit the shortcut. + bool Suppr; ///< Boolean, true if the shortcut can be removed. + word Key; ///< Primary shortcut. Value is a keycode, see keyboard.h + word Key2; ///< Secondary shortcut. Value is a keycode, see keyboard.h } T_Key_config; +/// Table with all the configurable shortcuts, whether they are for a menu button or a special action. extern T_Key_config ConfigKey[NB_SHORTCUTS]; +/// +/// Translation table from a shortcut index to a shortcut identifier. +/// The value is either: +/// - 0x000 + special shortcut number +/// - 0x100 + button number (left click) +/// - 0x200 + button number (right click) extern word Ordering[NB_SHORTCUTS]; diff --git a/init.c b/init.c index 5d40238d..9e3c5611 100644 --- a/init.c +++ b/init.c @@ -65,6 +65,7 @@ #include "sdlscreen.h" #include "mountlist.h" // read_file_system_list #include "loadsave.h" // Image_emergency_backup +#include "init.h" // Rechercher la liste et le type des lecteurs de la machine diff --git a/init.h b/init.h index 4b68c745..802e8f23 100644 --- a/init.h +++ b/init.h @@ -18,6 +18,12 @@ write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. */ + +////////////////////////////////////////////////////////////////////////////// +///@file init.h +/// Initialization (and some de-initialization) functions. +////////////////////////////////////////////////////////////////////////////// + void Load_graphics(const char * skin_file); void Init_buttons(void); void Init_operations(void); diff --git a/input.h b/input.h index 7915478b..d510f839 100644 --- a/input.h +++ b/input.h @@ -19,5 +19,21 @@ 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. */ +////////////////////////////////////////////////////////////////////////////// +///@file input.h +/// Functions for mouse, keyboard and joystick input. +/// Joystick input is used to emulate mouse on platforms that don't have a +/// pointing device, ie: the GP2X. +////////////////////////////////////////////////////////////////////////////// + +/// +/// This is the keyboard/mouse/joystick input polling function. +/// Returns 1 if a significant changed occurred, such as a mouse button pressed +/// or depressed, or a new keypress was in the keyboard buffer. +/// The latest input variables are held in ::Key, ::Key_ANSI, ::Mouse_X, ::Mouse_Y, ::Mouse_K. +/// Note that ::Key and ::Key_ANSI are not persistent, they will be reset to 0 +/// on subsequent calls to ::Get_input(). int Get_input(void); + +/// Returns true if the keycode has been set as a keyboard shortcut for the function. int Is_shortcut(word Key, word function); diff --git a/io.h b/io.h index e28f53d3..704b7a2f 100644 --- a/io.h +++ b/io.h @@ -18,29 +18,60 @@ write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. */ +////////////////////////////////////////////////////////////////////////////// +///@file io.h +/// Low-level endian-neutral file operations, and also some filesystem operations. +/// Many of these may seem trivial, but the wrappers eliminate the need for a +/// forest of preprocessor defines in each file. +/// You MUST use the functions in this file instead of: +/// - fread() and fwrite() +/// - stat() +/// - fstat() +/// - opendir() +/// - readdir() +/// - Also, don't assume "/" or "\\", use PATH_SEPARATOR +/// If you don't, you break another platform. +////////////////////////////////////////////////////////////////////////////// +/// Returns x, swapped if the current target is low-endian. Deprecated, please don't use it. word Endian_magic16(word x); +/// Returns x, swapped if the current target is low-endian. Deprecated, please don't use it. dword Endian_magic32(dword x); +/// Reads a single byte from an open file. Returns true if OK, false if a file i/o error occurred. int Read_byte(FILE *file, byte *dest); +/// Writes a single byte to an open file. Returns true if OK, false if a file i/o error occurred. int Write_byte(FILE *file, byte b); +/// Reads several bytes from an open file. Returns true if OK, false if a file i/o error occurred. int Read_bytes(FILE *file, void *dest, size_t size); +/// Writes several bytes to an open file. Returns true if OK, false if a file i/o error occurred. int Write_bytes(FILE *file, void *dest, size_t size); +/// Reads a 16-bit Low-Endian word from an open file. Returns true if OK, false if a file i/o error occurred. int Read_word_le(FILE *file, word *dest); +/// Writes a 16-bit Low-Endian word to an open file. Returns true if OK, false if a file i/o error occurred. int Write_word_le(FILE *file, word w); +/// Reads a 32-bit Low-Endian dword from an open file. Returns true if OK, false if a file i/o error occurred. int Read_dword_le(FILE *file, dword *dest); +/// Writes a 32-bit Low-Endian dword to an open file. Returns true if OK, false if a file i/o error occurred. int Write_dword_le(FILE *file, dword dw); +/// Reads a 16-bit Big-Endian word from an open file. Returns true if OK, false if a file i/o error occurred. int Read_word_be(FILE *file, word *dest); +/// Writes a 16-bit Big-Endian word to an open file. Returns true if OK, false if a file i/o error occurred. int Write_word_be(FILE *file, word w); +/// Reads a 32-bit Big-Endian dword from an open file. Returns true if OK, false if a file i/o error occurred. int Read_dword_be(FILE *file, dword *dest); +/// Writes a 32-bit Big-Endian dword to an open file. Returns true if OK, false if a file i/o error occurred. int Write_dword_be(FILE *file, dword dw); +/// Extracts the filename part from a full file name. void Extract_filename(char *dest, const char *source); +/// Extracts the directory from a full file name. void Extract_path(char *dest, const char *source); +/// Finds the rightmost path separator in a full filename. Used to separate directory from file. char * Find_last_slash(const char * str); #if defined(__WIN32__) @@ -49,18 +80,17 @@ char * Find_last_slash(const char * str); #define PATH_SEPARATOR "/" #endif -// Taille de fichier, en octets +/// Size of a file, in bytes. Returns 0 in case of error. int File_length(const char *fname); -// Taille de fichier, en octets +/// Size of a file, in bytes. Takes an open file as argument, returns 0 in case of error. int File_length_file(FILE * file); -// Détermine si un file passé en paramètre existe ou non dans le -// répertoire courant. +/// Returns true if a file passed as a parameter exists in the current directory. int File_exists(char * fname); -// Détermine si un répertoire passé en paramètre existe ou non dans le -// répertoire courant. + +/// Returns true if a directory passed as a parameter exists in the current directory. int Directory_exists(char * directory); -// Scans a directory, calls Callback for each file in it, +/// Scans a directory, calls Callback for each file in it, void For_each_file(const char * directory_name, void Callback(const char *)); diff --git a/keyboard.c b/keyboard.c index b42f85a4..bcd790c5 100644 --- a/keyboard.c +++ b/keyboard.c @@ -21,6 +21,7 @@ #include #include #include "global.h" +#include "keyboard.h" // Table de correspondance des scancode de clavier IBM PC AT vers // les symboles de touches SDL (sym). diff --git a/keyboard.h b/keyboard.h index 449f7df0..50662586 100644 --- a/keyboard.h +++ b/keyboard.h @@ -20,8 +20,26 @@ 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. */ +////////////////////////////////////////////////////////////////////////////// +///@file keyboard.h +/// Functions to convert bewteen the SDL key formats and the keycode we use +/// in grafx2. +/// The keycode we're using is generalized to handle mouse and joystick shortcuts +/// as well. The format can be broken down as: +/// - 0x0000 + a number between 0 and SDLK_LAST (about 324) : the SDL "sym" key number. +/// - 0x0000 + SDLK_LAST+1: Mouse middle button. +/// - 0x0000 + SDLK_LAST+2: Mouse wheel up. +/// - 0x0000 + SDLK_LAST+3: Mouse wheel down. +/// - 0x0000 + SDLK_LAST+4+B : Joystick button number "B", starting at B=0. +/// - 0x0800 + a number between 0 and 0x7FF: The scancode key number, for keys which have no "sym", such as keys from multimedia keyboards, and "fn" and "Thinkpad" key for a laptop. +/// Add 0x1000 for the Shift modifier MOD_SHIFT +/// Add 0x2000 for the Control modifier ::MOD_CONTROL +/// Add 0x4000 for the Alt modifier ::MOD_ALT +////////////////////////////////////////////////////////////////////////////// + /*! Convert an SDL keysym to an ANSI/ASCII character. + This is used to type text and numeric values in input boxes. @param keysym SDL symbol to convert */ word Keysym_to_ANSI(SDL_keysym keysym); @@ -30,12 +48,15 @@ word Keysym_to_ANSI(SDL_keysym keysym); Convert an SDL keysym to an internal keycode number. This is needed because SDL tends to split the information across the unicode sym, the regular sym, and the raw keycode. We also need to differenciate 1 (keypad) and 1 (regular keyboard), and some other things. + See the notice at the beginning of keyboard.h for the format of a keycode. @param keysym SDL symbol to convert */ word Keysym_to_keycode(SDL_keysym keysym); /*! - Helper function to convert between SDL system and old coding for keycodes. This is needed because some SDL keycode are actually unicode and won't fit in 8 bits. + Helper function to convert between SDL system and the old coding for PC keycodes. + This is only used to convert configuration files from the DOS version of + Grafx2, where keyboard codes are in in the IBM PC AT form. @param scancode Scancode to convert */ word Key_for_scancode(word scancode); @@ -48,6 +69,7 @@ const char * Key_name(word Key); /*! Gets the modifiers in our format from the SDL_Mod information. + Returns a combination of ::MOD_SHIFT, ::MOD_ALT, ::MOD_CONTROL @param mod SDL modifiers state */ word Key_modifiers(SDLMod mod); diff --git a/loadsave.h b/loadsave.h index aa646f3f..352cca3a 100644 --- a/loadsave.h +++ b/loadsave.h @@ -18,6 +18,11 @@ write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. */ +////////////////////////////////////////////////////////////////////////////// +///@file loadsave.h +/// Saving and loading different picture formats. +/// Also handles showing the preview in fileselectors. +////////////////////////////////////////////////////////////////////////////// void Pixel_load_in_current_screen(word x_pos,word y_pos,byte color); void Pixel_load_in_preview (word x_pos,word y_pos,byte color); @@ -25,20 +30,30 @@ void Pixel_load_in_brush (word x_pos,word y_pos,byte color); void filename_complet(char * filename, byte is_colorix_format); +/// +/// High-level picture loading function. +/// Handles loading an image or a brush, or previewing only. +/// @param image true if the fileselector is the one for loading images (not brush) void Load_image(byte image); +/// +/// High-level picture saving function. +/// @param image true if the image should be saved (instead of the brush) void Save_image(byte image); +/// Data for an image file format. typedef struct { - char *Extension; - Func_action Test; - Func_action Load; - Func_action Save; - byte Backup_done; // Le format enregistre toute l'image, on la considère à jour. - byte Comment; // Le format de fichier autorise un commentaire. + char *Extension; ///< Three-letter file extension + Func_action Test; ///< Function which tests if the file is of this format + Func_action Load; ///< Function which loads an image of this format + Func_action Save; ///< Function which saves an image of this format + byte Backup_done; ///< Boolean, true if this format saves all the image, and considers it backed up. Set false for formats which only save the palette. + byte Comment; ///< This file format allows a text comment } T_Format; -// Tableau des formats connus +/// Array of the known file formats extern T_Format File_formats[NB_KNOWN_FORMATS]; -// Fonction de sauvegarde en cas de probleme +/// +/// Function which attempts to save backups of the images (main and spare), +/// called in case of SIGSEGV. void Image_emergency_backup(void); diff --git a/misc.h b/misc.h index 47898cc5..319f1c52 100644 --- a/misc.h +++ b/misc.h @@ -18,10 +18,12 @@ write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. */ -void Effacer_ecran_courant(void); -void Copier_ecran_sur_brouillon(void); +////////////////////////////////////////////////////////////////////////////// +///@file misc.h +/// Miscellanous unsorted functions. +////////////////////////////////////////////////////////////////////////////// + void Copy_image_to_brush(short start_x,short start_y,short Brush_width,short Brush_height,word image_width); -void Permuter_dans_l_image_les_couleurs(byte color_1,byte color_2); void Remap_general_lowlevel(byte * conversion_table,byte * buffer,short width,short height,short buffer_width); void Scroll_picture(short x_offset,short y_offset); void Set_mouse_video_mode_number(void); diff --git a/mountlist.h b/mountlist.h index dd066a0e..51f7dc74 100644 --- a/mountlist.h +++ b/mountlist.h @@ -17,6 +17,12 @@ along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. */ +////////////////////////////////////////////////////////////////////////////// +///@file mountlist.h +/// A function to enumerate the mounting points in the filesystem. +/// Used to display them in fileselectors. +////////////////////////////////////////////////////////////////////////////// + #ifndef MOUNTLIST_H_ # define MOUNTLIST_H_ diff --git a/op_c.h b/op_c.h index c0d5031b..a5c6ebd6 100644 --- a/op_c.h +++ b/op_c.h @@ -18,6 +18,14 @@ write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. */ + +////////////////////////////////////////////////////////////////////////////// +///@file op_c.h +/// Color reduction and color conversion (24b->8b, RGB<->HSL). +/// This is called op_c because half of the process was originally +/// coded in op_asm, in assembler. +////////////////////////////////////////////////////////////////////////////// + #ifndef _OP_C_H_ #define _OP_C_H_ diff --git a/operatio.h b/operatio.h index 107d1e7e..a8dc3058 100644 --- a/operatio.h +++ b/operatio.h @@ -18,8 +18,17 @@ write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. */ + +////////////////////////////////////////////////////////////////////////////// +///@file operatio.h +/// Code for the operations, ie all drawing tools. +////////////////////////////////////////////////////////////////////////////// + +/// Do some housekeeping before starting work on a operation. void Start_operation_stack(word new_operation); +/// Put a value on ::Operation_stack void Operation_push(short value); +/// Take a value off ::Operation_stack void Operation_pop(short * value); //////////////////////////////////////////////////// OPERATION_CONTINUOUS_DRAW diff --git a/pages.h b/pages.h index d0611f16..99a42641 100644 --- a/pages.h +++ b/pages.h @@ -18,6 +18,12 @@ write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. */ + +////////////////////////////////////////////////////////////////////////////// +///@file pages.h +/// Handler for the Undo/Redo system. +////////////////////////////////////////////////////////////////////////////// + #ifndef _PAGES_H_ #define _PAGES_H_ diff --git a/palette.c b/palette.c index 1e14ccee..70a4ba0b 100644 --- a/palette.c +++ b/palette.c @@ -35,6 +35,7 @@ #include "op_c.h" #include "windows.h" #include "input.h" +#include "palette.h" byte Palette_view_is_RGB = 1; // Indique si on est en HSL ou en RGB diff --git a/palette.h b/palette.h index af687567..30a3d258 100644 --- a/palette.h +++ b/palette.h @@ -18,14 +18,22 @@ write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. */ +////////////////////////////////////////////////////////////////////////////// +///@file palette.h +/// Palette screen, and some palette-related high-level functions. +////////////////////////////////////////////////////////////////////////////// + +/// Open the palette menu and handles everything inside it. void Button_Palette(void); +/// Open the secondary palette menu and handles it. void Button_Secondary_palette(void); -// Choose the number of graduations for RGB components, from 2 to 256. +/// Choose the number of graduations for RGB components, from 2 to 256. void Set_palette_RGB_scale(int); -// Scale a component (R, G or B) according to the current RGB graduations -// The resulting range is [0-255] +/// +/// Scale a component (R, G or B) according to the current RGB graduations. +/// Returns the resulting value, in the [0-255] range. byte Round_palette_component(byte comp); /*! diff --git a/pxdouble.c b/pxdouble.c index 05ba46f0..7246cfd1 100644 --- a/pxdouble.c +++ b/pxdouble.c @@ -27,6 +27,7 @@ #include "global.h" #include "sdlscreen.h" #include "misc.h" +#include "pxdouble.h" #include "pxwide.h" // for Display_transparent_line_on_screen_wide() #define ZOOMX 2 diff --git a/pxdouble.h b/pxdouble.h index 94928db8..fa9dc9a7 100644 --- a/pxdouble.h +++ b/pxdouble.h @@ -19,6 +19,12 @@ write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. */ + +////////////////////////////////////////////////////////////////////////////// +///@file pxdouble.h +/// Renderer for double pixels (2x2). +////////////////////////////////////////////////////////////////////////////// + #include "struct.h" void Pixel_double (word x,word y,byte color); diff --git a/pxsimple.c b/pxsimple.c index a9c8e475..49cc00ae 100644 --- a/pxsimple.c +++ b/pxsimple.c @@ -27,6 +27,7 @@ #include "global.h" #include "sdlscreen.h" #include "misc.h" +#include "pxsimple.h" void Pixel_simple (word x,word y,byte color) /* Affiche un pixel de la color aux coords x;y à l'écran */ diff --git a/pxsimple.h b/pxsimple.h index f7e1c7d8..63802a78 100644 --- a/pxsimple.h +++ b/pxsimple.h @@ -19,6 +19,12 @@ write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. */ + +////////////////////////////////////////////////////////////////////////////// +///@file pxsimple.h +/// Renderer for simple pixels (1x1). This is the normal one. +////////////////////////////////////////////////////////////////////////////// + #include "struct.h" void Pixel_simple (word x,word y,byte color); diff --git a/pxtall.c b/pxtall.c index 54a93d71..46ac2593 100644 --- a/pxtall.c +++ b/pxtall.c @@ -27,6 +27,7 @@ #include "global.h" #include "sdlscreen.h" #include "misc.h" +#include "pxtall.h" #include "pxsimple.h" void Pixel_tall (word x,word y,byte color) diff --git a/pxtall.h b/pxtall.h index f097bd87..5ecf7761 100644 --- a/pxtall.h +++ b/pxtall.h @@ -19,6 +19,12 @@ write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. */ + +////////////////////////////////////////////////////////////////////////////// +///@file pxtall.h +/// Renderer for tall pixels (1x2). +////////////////////////////////////////////////////////////////////////////// + #include "struct.h" void Pixel_tall (word x,word y,byte color); diff --git a/pxwide.c b/pxwide.c index 992cbfe7..04477173 100644 --- a/pxwide.c +++ b/pxwide.c @@ -27,6 +27,7 @@ #include "global.h" #include "sdlscreen.h" #include "misc.h" +#include "pxwide.h" void Pixel_wide (word x,word y,byte color) /* Affiche un pixel de la color aux coords x;y à l'écran */ diff --git a/pxwide.h b/pxwide.h index 7c1c8c47..68669346 100644 --- a/pxwide.h +++ b/pxwide.h @@ -19,6 +19,12 @@ write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. */ + +////////////////////////////////////////////////////////////////////////////// +///@file pxwide.h +/// Renderer for wide pixels (2x1). +////////////////////////////////////////////////////////////////////////////// + #include "struct.h" void Pixel_wide (word x,word y,byte color); diff --git a/readini.c b/readini.c index c04ff89b..a4448ce3 100644 --- a/readini.c +++ b/readini.c @@ -27,6 +27,7 @@ #include "const.h" #include "global.h" #include "misc.h" +#include "readini.h" void Load_INI_clear_string(char * str) { diff --git a/readini.h b/readini.h index cacee3dc..1e6ab0d0 100644 --- a/readini.h +++ b/readini.h @@ -18,6 +18,12 @@ write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. */ + +////////////////////////////////////////////////////////////////////////////// +///@file readini.h +/// Reading settings in gfx2.ini +////////////////////////////////////////////////////////////////////////////// + int Load_INI(T_Config * conf); int Load_INI_seek_pattern(char * buffer,char * pattern); void Load_INI_clear_string(char * str); diff --git a/readline.h b/readline.h index fda53ba5..62fdfc31 100644 --- a/readline.h +++ b/readline.h @@ -19,21 +19,28 @@ 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. */ -byte Readline(word x_pos,word y_pos,char * str,byte visible_size,byte input_type); -// Paramètres: -// x_pos, y_pos : Coordonnées de la saisie dans la fenêtre -// str : Chaîne recevant la saisie (et contenant éventuellement une valeur initiale) -// visible_size : Nombre de caractères logeant dans la zone de saisie -// input_type : 0=Chaîne, 1=Nombre, 2=Nom de fichier (255 caractères réels) -// Sortie: -// 0: Sortie par annulation (Esc.) / 1: sortie par acceptation (Return) +////////////////////////////////////////////////////////////////////////////// +///@file readline.h +/// Text input functions. +////////////////////////////////////////////////////////////////////////////// +/// +/// Lets the user input a line of text, exit by Esc or Return. +/// @param x_pos Coordinates of input, in window coordinates before scaling. +/// @param y_pos Coordinates of input, in window coordinates before scaling. +/// @param str The original string value (will be modified, unless user cancels. +/// @param visible_size Number of characters visible and editable. +/// @param input_type 0=string, 1=number, 2=filename (255 editable characters) +/// @return 0 if user cancelled (esc), 1 if accepted (return) +byte Readline(word x_pos,word y_pos,char * str,byte visible_size,byte input_type); + +/// +/// Lets the user input a line of text, exit by Esc or Return. +/// @param x_pos Coordinates of input, in window coordinates before scaling. +/// @param y_pos Coordinates of input, in window coordinates before scaling. +/// @param str The original string value (will be modified, unless user cancels. +/// @param visible_size Number of characters visible. +/// @param max_size Number of characters editable. +/// @param input_type 0=string, 1=number, 2=filename (255 editable characters) +/// @return 0 if user cancelled (esc), 1 if accepted (return) byte Readline_ex(word x_pos,word y_pos,char * str,byte visible_size,byte max_size, byte input_type); -// Paramètres: -// x_pos, y_pos : Coordonnées de la saisie dans la fenêtre -// str : Chaîne recevant la saisie (et contenant éventuellement une valeur initiale) -// visible_size : Nombre de caractères logeant dans la zone de saisie -// max_size : Nombre de caractères logeant dans la zone de saisie -// input_type : 0=Chaîne, 1=Nombre, 2=Nom de fichier (255 caractères réels) -// Sortie: -// 0: Sortie par annulation (Esc.) / 1: sortie par acceptation (Return) diff --git a/realpath.h b/realpath.h index 61687743..7692154f 100644 --- a/realpath.h +++ b/realpath.h @@ -1,6 +1,36 @@ +/* Grafx2 - The Ultimate 256-color bitmap paint program + + Copyright 2008 Adrien Destugues + + Grafx2 is free software; you can redistribute it and/or + modify it under the terms of the GNU General Public License + as published by the Free Software Foundation; version 2 + of the License. + + Grafx2 is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with Grafx2; if not, see or + write to the Free Software Foundation, Inc., + 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. +*/ + +////////////////////////////////////////////////////////////////////////////// +///@file realpath.h +/// Implementation of realpath() that is portable on all our platforms. +////////////////////////////////////////////////////////////////////////////// + #ifndef _REALPATH_H #define _REALPATH_H +/// +/// Makes an absolute filename, resolving symbolic links etc. +/// @param _path Input path +/// @param resolved_path Output path, allocated by caller +/// @return (points to resolved_path) char *Realpath(const char *_path, char *resolved_path); #endif diff --git a/saveini.c b/saveini.c index b3217844..eaca33a1 100644 --- a/saveini.c +++ b/saveini.c @@ -29,6 +29,7 @@ #include "io.h" #include "errors.h" #include "misc.h" +#include "saveini.h" int Save_INI_reach_group(FILE * old_file,FILE * new_file,char * buffer,char * group) { diff --git a/saveini.h b/saveini.h index cd3e9b0e..27421467 100644 --- a/saveini.h +++ b/saveini.h @@ -18,4 +18,10 @@ write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. */ + +////////////////////////////////////////////////////////////////////////////// +///@file saveini.h +/// Saving settings in gfx2.ini +////////////////////////////////////////////////////////////////////////////// + int Save_INI(T_Config * conf); diff --git a/sdlscreen.h b/sdlscreen.h index 1fb7d008..496f3956 100644 --- a/sdlscreen.h +++ b/sdlscreen.h @@ -19,6 +19,12 @@ write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. */ + +////////////////////////////////////////////////////////////////////////////// +///@file sdlscreen.h +/// Screen update (refresh) system, and some SDL-specific graphic functions. +////////////////////////////////////////////////////////////////////////////// + #ifndef SDLSCREEN_H_INCLUDED #define SDLSCREEN_H_INCLUDED diff --git a/setup.c b/setup.c index 1c0faca3..a70951a7 100644 --- a/setup.c +++ b/setup.c @@ -39,6 +39,7 @@ #include "struct.h" #include "io.h" +#include "setup.h" int Create_ConfigDirectory(char * config_dir) { diff --git a/setup.h b/setup.h index de1d719c..24150509 100644 --- a/setup.h +++ b/setup.h @@ -21,7 +21,36 @@ write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. */ + +////////////////////////////////////////////////////////////////////////////// +///@file setup.h +/// Functions that determine where grafx2 is running, finds its data, and +/// reads and writes configuration files. +////////////////////////////////////////////////////////////////////////////// + +/// +/// Determine which directory contains the executable. +/// - IN: Main's argv[0], some platforms need it, some don't. +/// - OUT: Write into program_dir. Trailing / or \ is kept. +/// Note : in fact this is only used to check for the datafiles and fonts in this same directory. void Set_program_directory(const char * argv0,char * program_dir); + +/// +/// Determine which directory contains the read-only data. +/// IN: The directory containing the executable +/// OUT: Write into data_dir. Trailing / or \ is kept. void Set_data_directory(const char * program_dir, char * data_dir); + +/// +/// Determine which directory should store the user's configuration. +/// For most Unix and Windows platforms: +/// If a config file already exists in program_dir, it will return it in priority +/// (Useful for development, and possibly for upgrading from DOS version) +/// If the standard directory doesn't exist yet, this function will attempt +/// to create it ($(HOME)/.grafx2, or %APPDATA%\\GrafX2) +/// If it cannot be created, this function will return the executable's +/// own directory. +/// IN: The directory containing the executable +/// OUT: Write into config_dir. Trailing / or \ is kept. void Set_config_directory(const char * program_dir, char * config_dir); diff --git a/shade.c b/shade.c index 1d404138..9d4c88d0 100644 --- a/shade.c +++ b/shade.c @@ -30,6 +30,7 @@ #include "sdlscreen.h" #include "windows.h" #include "input.h" +#include "shade.h" void Button_Shade_mode(void) { diff --git a/shade.h b/shade.h index 765ee158..ce57d1cd 100644 --- a/shade.h +++ b/shade.h @@ -18,6 +18,12 @@ write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. */ +////////////////////////////////////////////////////////////////////////////// +///@file shade.h +/// Screens for Shade and Quick-shade settings. +////////////////////////////////////////////////////////////////////////////// + + #ifndef SHADE_H_INCLUDED #define SHADE_H_INCLUDED diff --git a/special.c b/special.c index 7ed279cc..d0d7c6a6 100644 --- a/special.c +++ b/special.c @@ -26,6 +26,7 @@ #include "graph.h" #include "engine.h" #include "windows.h" +#include "special.h" diff --git a/special.h b/special.h index 001c86a4..3383d71c 100644 --- a/special.h +++ b/special.h @@ -18,6 +18,13 @@ write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. */ + +////////////////////////////////////////////////////////////////////////////// +///@file special.h +/// Editor functions that can be hooked to a keyboard shortcut, but don't have +/// a menu button associated to them. +////////////////////////////////////////////////////////////////////////////// + void Set_paintbrush_size(int width, int height); void Smaller_paintbrush(void); void Bigger_paintbrush(void); diff --git a/text.h b/text.h index 07a26236..1293dc3d 100644 --- a/text.h +++ b/text.h @@ -20,19 +20,37 @@ 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. */ -// Initialisation à faire une fois au début du programme +////////////////////////////////////////////////////////////////////////////// +///@file text.h +/// Functions related to rendering text as a brush, using TrueType or SFont. +////////////////////////////////////////////////////////////////////////////// + +/// Initialization of text settings, needs to be called once on program startup. void Init_text(void); -// Informe si texte.c a été compilé avec l'option de support TrueType ou pas. +/// Returns true if text.c was compiled with TrueType support. int TrueType_is_supported(void); -// Ajout d'une fonte à la liste. -void Add_font(char *name); -// Crée une brosse à partir des paramètres de texte demandés. +/// Add a new font to the list to propose to the user. +void Add_font(const char *name); +/// +/// Creates a brush, from the parameters given: +/// @param str The text to render +/// @param font_number The index of the font to use. Pass 0 for the first font you declared with ::Add_font(), 1 for the second etc. +/// @param size The size in points (unused for bitmap fonts) +/// @param antialias Boolean, true to use antialiasing in TrueType +/// @param bold Boolean, true to use bold rendering in TrueType +/// @param italic Boolean, true to use italic rendering in TrueType +/// @param width Returns the width of the created brush, in pixels. +/// @param height Returns the height of the created brush, in pixels. +/// Returns true on success. byte *Render_text(const char *str, int font_number, int size, int antialias, int bold, int italic, int *width, int *height); -// Trouve le libellé d'affichage d'une fonte par son numéro + +/// Finds a label to display for a font declared with ::Add_font(). char * Font_label(int index); -// Trouve le nom d'une fonte par son numéro +/// Finds the filename of a font declared with ::Add_font(). char * Font_name(int index); -// Vérifie si une fonte donnée est TrueType +/// Returns true if the font of this number is TrueType, false if it's a SFont bitmap. char * TrueType_font(int index); -// Nombre de fontes déclarées +/// +/// Number of fonts declared with a series of ::Add_font(). This is public for +/// convenience, but functionaly it is read-only. extern int Nb_fonts; diff --git a/windows.h b/windows.h index a3e572e3..397b9b7a 100644 --- a/windows.h +++ b/windows.h @@ -19,6 +19,11 @@ 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. */ +////////////////////////////////////////////////////////////////////////////// +///@file windows.h +/// Graphical interface management functions (windows, menu, cursor) +////////////////////////////////////////////////////////////////////////////// + #ifndef __WINDOWS_H_ #define __WINDOWS_H_